# 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