Placeholder Reference

General:

The general form of placeholders is as follows:

[START]name::arguments::output range definition[END]

Beginning with client release 1.4, the placeholder must always include the two sets of '::' even when no argument or range definition are supplied.

Syntax and usage:

START and END

Every GNUmed placeholder must currently be bounded by $< and >$. Some template types (currently LaTeX, TXT) also allow the following forms: $<<...>>$ and $<<<...>>>$. Those templates undergo three subsequent placeholder substitution runs of which the first scans for $<...>$, the second for $<<...>>$, and the third one for $<<<...>>>$. Note that you can nest placeholders with differing numbers of <> brackets but you can NOT nest the same <> bracket level within itself. You must make sure that the pairs of START and END tags are balanced.

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
• sub arguments are separated by // per default
• that default can be modified by using the placeholder ph_cfg::argumentsdivider
• may support an "output template" – see below.

output range definition

• can be empty, in which case the full string returned by the placeholder handler is inserted into the template
• can be a single number in which case the output is truncated to contain at most that many characters
• can be a number, a -, followed by a second number in which case that range of the of the output string is returned
• one can configure an ellipsis symbol by means of the ph_cfg::ellipsis placeholder
• if an ellipsis symbol is defined any output longer than the desired length is shortened by the length of the ellipsis symbol and the symbol is append

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