Placeholder Reference
General:
The general form of placeholders is as follows:
$<field_1::field_2::field_3>$
which stand for …
$<name::args::max string length>$
Syntax and usage:
Every GNUmed placeholder must currently be bounded by $< and >$.
name
- must, in all cases, provide a valid (defined-in-GNUmed) placeholder name as listed within this source file.
args
- are in some cases unavailable and inapplicable, for example in 'lastname'
- otherwise provides one or more (sub) arguments, in the latter case separated by '//'
- may support an "output template" – see below.
max string length
- when specified, must be an integer and
- except as noted below, is optional, thus usually allowing $<field_1::::integer>$ or $<field_1::::>$.
Beginning with client release 1.4, the placeholder must always include the two sets of '::' even when no argument or max length are supplied.
Spaces, such as might make a placeholder's incarnation more readable, may not be harmless. Within a placeholder, spaces – except when part of a valid and properly formatted argument – may break the placeholder particularly if interposed between the $ and either < or >, and between the $< and the placeholder name. Spaces on either or both sides of 'max string length' should, however, still allow detection of the 3rd field integer:
$<field_1:::: 60>$
$<field_1:::: 60 >$
$<field_1::::60 >$
For the 'injectable' placeholders (form_… )
- 'max string length' is non-optional and
- if these placeholders had not been 'set' (programmed) into the code calling it, the placeholder's own name its returned
In all other cases where a properly-formatted placeholder cannot resolve to a value – as in the case where no value had yet been created for a patient – the resulting output will depend whether or not the instance of GNUmed is running with --debug on. If yes, it will return "no URL for …" and otherwise u'' (IOW, an empty value).
There is, at present, no way to include conditional statements inside a placeholder, for example to include or exclude characters (such as ', ") depending on whether a key (like 'suburb') is empty.
Placeholder output templates, fields, escape styles and formats
Some placeholder
args
involve an output template of the form
something %s something else
where 'something' and 'something else' represent any fixed text desired to be outputted, and where
%s
is the special pythonic token used to convert a specified value to a string using the
Str()
function.
The
%s
can be used in either of two ways.
When wanting only one or a few columns from the view referenced by a particular placeholder, each such column can be represented by a
field
around which
%s
needs to be applied, for example
%(laterality)s
%(is_active)s
When unqualified, meaning when it is not being applied to one or more fields, %s will return the content of what
str(the_class_in_question)
returns.
Placeholders no longer require an
<escape style>
to be specified, because the
LaTeX engine now tells the placeholder handler to use a suitable escape function to escape the data being returned, as should any other future-use engines within GNUmed.
At the point where target document description languages (other than
LaTeX) are supported, certain placeholders may require a
format
to be specified.
Placeholder particulars
The following table gives the particulars of most placeholders.
TBA
Placeholder examples
The following table provides a formatted example for most placeholders.
TBA