# 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 `` 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