Skip to content

Export Expressions

An export expression tells NAHPU which record fields to output, what fixed text to include around them, and how to handle missing or conditional values. Expressions work in two places:

The same expression produces the same text in both. For example, [taxonomy::genus] [taxonomy::specificEpithet] C prints Rattus rattus on a label and writes Rattus rattus to a spreadsheet cell.

Wrap any field key in square brackets as [table::field]. Everything outside brackets prints verbatim:

Field no. [specimen::fieldNumber]

outputs Field no. 156. Three modifiers handle most formatting needs:

AddPurposeExampleOutput
??textFallback when the field is empty[taxonomy::specificEpithet??sp.]sp. when no epithet is recorded
#labelPrint a coded field's label instead of its integer code[mammalAttribute::testisPosition#label]Scrotal instead of 0
[[if]…]]Print text only when conditions hold[[if][coordinate::elevationInMeter!=""]=>"m"]]m only when elevation is recorded

You rarely need to type keys manually: use Insert Field in the template editor or Add field in a custom field column.

Copy these into a document-template text element or into a tabular preset column as noted. All examples below use specimen fields.

[taxonomy::genus] [taxonomy::specificEpithet]

Outputs Rattus rattus. For genus-only identifications, add a fallback so the output reads Rattus sp.:

[taxonomy::genus] [taxonomy::specificEpithet??sp.]

For the full scientific name including subspecies, use [specimen::scientificName]. In a tabular preset, place either expression in a Custom field column.

Joins geography fields into one string while skipping empty parts, preventing doubled commas when a level like county is blank:

[geography::country]|[geography::islandGroup]|[geography::stateProvince]|[geography::county]|[geography::municipality]|[geography::locality]

Each | separates parts; the printed separator comes from the list settings:

  • Document template: set Text type to List Values and choose the comma format.
  • Record-export preset: set Mapping type to List field, List output to One column, and Separator to Comma (A, B). Paste the expression into Advanced > Raw source expression and set Column name (optional) (required for Darwin Core and NAHPU namespace headers).

A complete record prints Indonesia, West Java, Bogor, Cibodas; one without a county prints Indonesia, West Java, Cibodas. Add, remove, or reorder parts as needed.

Outputs length x width only when the testis is scrotal and both measurements exist; otherwise outputs nothing:

[[if][mammalAttribute::testisPosition=="0"&&mammalAttribute::testisLength!=""&&mammalAttribute::testisWidth!=""]=>"[mammalAttribute::testisLength] x [mammalAttribute::testisWidth]"]]
RecordOutput
Scrotal, 10 mm by 6.5 mm10 x 6.5
Scrotal, width missingNothing
AbdominalNothing
FemaleNothing

"0" is the stored code for Scrotal. Add mm inside the quotes for a unit, or add |"not scrotal" before ]] to write an alternative for non-matching records. See Conditional text. In a tabular preset, use a Custom field column.

[mammalAttribute::testisPosition#label]

Outputs Scrotal instead of the stored code 0. Works in any text type, including Custom field columns. See Decode an encoded field.

SymbolMeaningExample
[ ]Field placeholder[fieldNumber]
::Separates table from field in a full key[specimen::fieldNumber]
??Fallback when the field is empty[specimen::preparator??N/A]
#labelOutputs a coded field's label instead of its code[mammalAttribute::testisPosition#label]
-imgRenders a .sex field as an icon instead of text[mammal.sex]-img
[[ ]]Conditional expression[[specimen::condition][…]]
[[if] … ]]Conditional text written only when conditions match[[if][…]=>" mm"]]

A placeholder accepts a full table::field key or a short field name:

Field number: [specimen::fieldNumber]
Scientific name: [taxonomy::scientificName]
Locality: [site::specificLocality]

Use the full table::field key whenever two tables share a field name. The field picker offers only fields available to the active record type.

?? specifies what prints when a field is empty. The No Content Placeholder setting writes this syntax for you:

OptionWritten asOutput when empty
Blank[specimen::preparator]Nothing
table::field[specimen::preparator??specimen::preparator]The field key as a visible reminder
N/A[specimen::preparator??N/A]N/A
None[specimen::preparator??None]None
Custom[specimen::preparator??not recorded]Your custom text

Text after ?? prints verbatim. Placeholders ending in -img do not accept fallbacks.

Two placeholders render images rather than text and must appear alone in their text element:

  • [mammal.sex]-img draws a sex icon (the key must end in .sex; set icon dimensions with width and height).
  • [media::media] with Text type set to Picture renders the record's attached images in a grid.

A custom field combines placeholders with fixed text, or holds fixed text alone. In a document template, every text element behaves this way (Insert Field plus typed text). In a record-export preset, select Add custom field in Edit Fields or switch a column's Mapping type to Custom field.

Build the expression segment by segment in the custom field editor:

ControlWhat it does
Add fieldInserts a field from the picker.
Add text BInserts fixed text or a separator.
Add conditional textInserts conditional text.
Show labelAdds #label on a coded field to print its label instead of its code.
Edit conditional textReopens a conditional text segment for editing.
Move segment up / Move segment downReorders segments (written left to right).
Remove segmentDeletes a segment.
Expression:Previews the saved expression string.
Column nameSets the output column header.

Examples of complete custom fields:

[personnel::initial]-[specimen::fieldNumber]
[taxonomy::genus] [taxonomy::specificEpithet]
NAHPU

NAHPU outputs the same fixed string in every row (useful for an institution code). A custom field with a Column name and no segments writes a blank column so exported columns align with an external sheet.

Always set a Column name (required for Darwin Core and NAHPU namespace headers). With table::fieldName or fieldName headers, an unnamed custom field defaults to its first field key or its fixed text.

Custom field columns output plain text. When you need Encoded text, Date, conditional brackets, or indexed list columns, use a Single field or List field column instead.

A conditional expression checks one or more fields before deciding what to write. In the template editor, use Conditional output on the text toolbar to create or edit conditionals via dialog. In a tabular preset, pick a conditional Value format on a Single field column (its own field is the target).

You want to…TypeExample output
Bracket a value when another field flags itConditional brackets[82.5] when weight was estimated
Replace a value when another field matchesConditional field? instead of the epithet when ID is uncertain
Replace a value based on its own valueConditional valueNot recorded when the value is 0
Output standalone text (such as a unit) conditionallyConditional text mm only after a recorded width

In the dialog:

  1. Select Conditional type.
  2. Select Target field (the field to bracket or replace). Conditional text has no target and appends to the element text.
  3. Add one or more conditions (Controlling field, comparison operator, and value). Conditional value tests the target itself, so no separate field picker appears.
  4. For multiple conditions, set Match logic to Any condition (OR) or All conditions (AND).
  5. Enter Replacement text (or Text when matched and optional Text otherwise (optional) for conditional text). Leave Replacement text blank to hide the value when matched.

Conditional text writes text based on conditions rather than modifying a target field—ideal for units or labels that should appear only alongside a value:

[mammalAttribute::testisWidth][[if][mammalAttribute::testisWidth!=""]=>" mm"]]

A width of 6.5 prints 6.5 mm; an empty width prints nothing.

Add | and a second quoted string for an else branch:

[[if][mammalAttribute::testisPosition=="0"]=>"scrotal"|"not scrotal"]]

Quoted outputs can include placeholders, fallbacks, and #label:

[[if][mammalAttribute::testisLength!=""&&mammalAttribute::testisWidth!=""]=>"[mammalAttribute::testisPosition#label], [mammalAttribute::testisLength] x [mammalAttribute::testisWidth] mm"]]
  • Wrap each output string in double quotes; escape literal quotes as \". A | inside quotes is treated as ordinary text.
  • Without an else branch, non-matching records output nothing.
  • Nested conditionals inside quoted output are not evaluated.
  • if must be lowercase.

Hide a value unless another field is recorded

Section titled “Hide a value unless another field is recorded”

Use Is empty with an empty replacement. This outputs testis length only when testis position is recorded:

[[mammalAttribute::testisLength][mammalAttribute::testisPosition==""]=>""]]

A conditional hides only its own target. Surrounding text (like a unit or x) still prints unless wrapped in conditional text:

[[mammalAttribute::testisLength][mammalAttribute::testisPosition==""]=>""]][[if][mammalAttribute::testisPosition!=""&&mammalAttribute::testisLength!=""]=>" mm"]]

See Testis size for the complete combined pattern.

Bracket an estimated weight. A mammal's accuracy note lists measurements that are estimates. Bracket weight when flagged:

[[mammalAttribute::weight][mammalAttribute::accuracy~="weight"]]

Flagged weights print [82.5]; precise weights print 82.5. On mammalAttribute::accuracy, ~= checks whether the named measurement is flagged.

Mark an uncertain identification. Identification confidence is stored as 0 (Low), 1 (Medium), or 2 (High), so "not High" is !="2":

[taxonomy::genus] [[taxonomy::specificEpithet][specimen::iDConfidence!="2"]=>"?"]]

High confidence prints Rattus rattus; Low or Medium prints Rattus ?. Because replacements replace the entire target, append a symbol instead by following the field with conditional text.

!="2" does not match a blank confidence field. Include blank records by adding Is empty with ||:

[[taxonomy::specificEpithet][specimen::iDConfidence=="0"||specimen::iDConfidence=="1"||specimen::iDConfidence==""]=>"?"]]
  • Stored values, not labels: test codes (specimen::iDConfidence!="2", mammalAttribute::testisPosition=="0"), not display labels.
  • Case-sensitive: leading and trailing spaces are trimmed, but letter case must match.
  • Blank values never match ordinary operators (including !=). Use Is empty (=="") or Is not empty (!="").
  • One joiner per expression: use all && or all ||, never mixed.
  • Empty target: uses No Content Placeholder, not the replacement text.
  • Full replacement: replacement text replaces the entire value; an empty replacement hides it.
  • Syntax errors print verbatim: always preview both matching and non-matching records.

The dialog generates these automatically; use this reference when reading or editing expressions by hand.

SymbolNameMeaning
[[ … ]]Expression delimitersOpen and close a conditional expression.
][Target separatorSeparates the target field from conditions.
==EqualsMatches an exact value.
!=Not equalsMatches any non-empty differing value.
~=ContainsMatches when the substring appears anywhere in the value.
!=""Is not emptyMatches any non-blank value.
==""Is emptyMatches blank or missing values.
&&All (AND)Every condition must match.
||Any (OR)At least one condition must match.
" … "Value quotesWrap every comparison value (empty for emptiness checks).
\", \\EscapesLiteral quote or backslash inside quotes.
]=>Replacement markerEnds conditions and begins replacement/output text.
ifConditional text keywordReplaces the target so the expression emits text.
|Else separatorStarts the fallback text when conditions do not match.

Three valid forms (each ending in ]]; |"otherwise" is optional; ~="" is invalid):

[[target][conditions]]
[[target][conditions]=>"replacement"]]
[[if][conditions]=>"text"|"otherwise"]]

In document templates, Text type and Format format the rendered value. A tabular Single field column exposes the same formatting via Value format.

Text typeFormat options
Normal TextNormal, Uppercase, Lowercase, Capitalize
PictureSized with width and height rather than a format
MarkdownNormal; renders rich text such as narratives
CoordinatesDecimal, Cardinal Dec, DMS, DDM
List ValuesPipe, comma, semicolon, slash, new line, bulleted, custom separator
Nested ListTable (adds Header Case) or Card list
DatesYYYY-MM-DD, DD-MM-YYYY, MM-DD-YYYY, DD/MM/YYYY, MM/DD/YYYY, Month DD, YYYY, DD Month YYYY, DD Mon YYYY
Date and Time17 combinations of the date formats above with 24h, 12h, ISO, and time-only outputs
Time24h, 24h seconds, 12h, 12h padded
SexFormat and Missing, described below
NumberOriginal, or 0, 1, 2, or 3 decimal places
Encoded TextDefault mapping or Custom mapping...

Nested List formats repeated child records (specimen parts, personnel, collecting methods) and usually benefits from dynamic text sizing.

Some database fields store numeric codes. Encoded Text with Default mapping matches on the end of the field key (so both mammalAttribute::testisPosition and testisPosition decode):

Field key ends withCode 0123456
::sexMaleFemaleUnknownGynandromorphHermaphroditeFemale?Male?
::iDConfidenceLowMediumHigh
mammalAttribute::ageAdultSubadultJuvenileUnknown
herpAttribute::ageAdultJuvenileNeonateMetamorphUnknown
::testisPositionScrotalAbdominal
::epididymisAppearanceTubularPartialNot Tubular
::vaginaOpeningImperforatePerforate
::pubicSymphysisCloseSmall OpenOpen
::reproductiveStageNulliparousPrimiparousMultiparous
::mammaeConditionSmallLargeLactating
::echolocationFMCFQCFNone
::ovaryAppearanceSmoothOva minuteAt least one ovum ≥ 1 mm dia.
::oviductAppearanceStraightConvoluted
::fatNoneTraceLightModerateHeavyExtremely Heavy
::bodyMoltNoneTraceLightModerateHeavy

Boolean flags decode 1 as Yes and 0 as No: ::broodPatch, ::hasBursa, ::wingIsMolt, ::tailIsMolt, ::showBatFields, and ::showEchoFields.

Unlisted keys, non-integer values, and out-of-range codes pass through unchanged. Use Custom mapping... to label fields not covered by the default table. For sex symbols or letters, use the Sex text type; for icons, use […sex]-img.

Keep the placeholder unchanged and let Encoded Text or #label decode it:

  • Document template: set Text type to Encoded Text. Each placeholder in the element decodes against its own field:
    Testes: [mammalAttribute::testisPosition]
    [mammalAttribute::age], [mammalAttribute::testisPosition]
  • Record-export preset: use a Single field column with Value format set to Encoded text, or in a Custom field column append #label (or select Show label on the segment):
    [mammalAttribute::testisPosition#label], [mammalAttribute::mammaeCondition#label]
  • Inline #label: decodes a single placeholder with the default mapping in any text type. Place #label before any fallback: [mammalAttribute::sex#label??Unknown].
  • Custom labels: in the template editor, choose Custom mapping... and select Map encoded values (starts prefilled from defaults). In a tabular preset, enter custom_map: under Advanced > Raw format option:
    custom_map:0=Scrotal,1=Abdominal
    Separate code=label pairs with commas (labels cannot contain , or =; unmapped codes stay unchanged). Custom mappings apply to every placeholder in the element, so give each custom-mapped field its own element.

Decoding affects display only; conditions still test stored codes and empty values still use No Content Placeholder.

ControlOptions
FormatSymbol (♂/♀), Letter (M/F), Text (Male/Female)
MissingUnknown, N/A, None

Uncertain determinations retain their question mark in every format: Female?, F?, ♀?, and Male?, M?, ♂?.

SymptomWhat to check
Conditional prints as plain textSyntax error: check for missing ]], unquoted values, or mixed && and ||.
Fallback prints [table::field]No Content Placeholder is set to table::field; switch to Blank, N/A, None, or custom text.
Sex icon prints as textThe element must contain only […sex]-img, with a key ending in .sex.
Record images do not appearThe element must contain only [media::media] with Text type set to Picture.
Unexpected custom-field headerSet Column name; otherwise it defaults to the first field or fixed text.
Coded field prints a numberUse Encoded Text / Encoded text or #label, and verify the code is in the mapping.
Condition never matchesConditions compare stored codes, are case-sensitive, and blank fields only match Is empty.
Conditional text prints nothingAdd an else branch after | for non-matching records, and ensure if is lowercase.

The reference below applies to the document template editor only E; record-export presets do not use these controls.

Canvas sizes are in millimetres (mm). Stroke widths, font sizes, and padding are in PDF points (pt, 1 pt = 1/72 inch). Colours are stored as 0xAARRGGBB and selected with the colour picker.

ControlWhat it does
Add textPlaces a text element on the canvas.
Add imagePlaces a static image from the device.
Add linePlaces a straight rule.
Add shapePlaces a rectangle, ellipse, circle, triangle, or polygon.
Save templateSaves the template (Save as... creates a variation).
Undo / RedoSteps through edit history.
Template borderConfigures the outer template border.
Show grid / Hide gridToggles the alignment grid.
Enable snap / Disable snapToggles snapping to the grid and elements.
Canvas lockLocks panning so dragging does not move the canvas.
Select specimen for text previewChooses the record used to populate live preview placeholders.
Template settings DName, description, side count, and template size.
Preset template ALoads a bundled starting template.
Zoom in / Zoom outScales canvas view only (does not affect PDF size).
1 sided / Front / BackSwitches side mode and active side.
MirrorMirrors a side for folded tags.
OptionValuesNotes
TextText, placeholders, conditionalsElement content.
Text typeSee table aboveSelects value formatting category.
FormatDepends on Text typeSpecific format within that category.
No Content PlaceholderBlank, table::field, N/A, None, customWrites ?? fallback.
Conditional outputBrackets, field, value, textWrites [[ … ]] or [[if] … ]] expressions.
Find and replace—Edits element text in place.
Replacement rulesPattern, replacement, match type, case sensitivityRewrites values after formatting.
Map encoded valuesDefault or custom mappingMaps stored codes to labels for Encoded Text.
OptionValues
FontBundled and installed fonts (missing fonts are marked (not installed))
Font sizePoints, with step buttons
Bold, Italic, Underline, StrikethroughOn or off
AlignmentAlign left, Align center, Align right
CaseNormal, Uppercase, Lowercase, Capitalize
Text colourColour picker
OptionValuesNotes
PositionX and Y in mmMeasured from the template's top-left corner.
Max widthmmWraps text at this width (unset = no wrapping).
HeightmmBounds box height.
PaddingptSpace inside the box around text.
Rotation0–359°Whole degrees.
Background colourColour or none—
Border colour, width, strokeColour, pt, solid / dashed / dotted / double—
Corner radiusptRounds box corners.
Dynamic sizingOn or offLets the box grow with content; pair with Auto-fill page.
StackingBring to front, Bring forward, Send backward, Send to back—
LockOn or offPrevents dragging or resizing.
VisibleOn or offHidden elements stay saved but do not print.

Convert a text element into a scannable QR code:

OptionValues
QR codeOn or off
Sizemm
Background colourColour picker
ShapeSquare or Circle

The QR payload keeps the raw formatted value—including trailing .0 values that printed text drops—so scanned values match stored values exactly.

OptionValues
Width, heightmm

Only a bare [media::media] or [media] element resolves to record images; mixing text with the placeholder disables image rendering.

Static images, lines, and shapes are decorative and carry no record data:

ElementOptions
ImageImage path, position, width, height, rotation, stacking, lock, visibility
LinePosition, length, rotation, thickness (pt), colour, stroke style, stacking, lock, visibility
ShapeShape type (rect, ellipse, circle, triangle, polygon with side count), position, width, height, rotation, stroke thickness/colour/style, fill colour or Clear fill, stacking, lock, visibility

Stroke styles for lines and shapes are solid, dashed, dotted, and double. Static image elements store a path rather than embedding the picture; templates transferred to another device ask for the image again there.

OptionValuesNotes
Template nameTextMust be unique; renaming updates all print layouts referencing it.
DescriptionText (up to 80 characters)Optional.
Record typeSpecimen, Specimen parts, Symbionts, Site, Collecting event, Narrative, No recordsDetermines available fields and records.
Side count1 sided or 2 sidedOne-sided mode keeps the Back design saved without printing it.
Width, heightmmSize of one block, not the sheet.
Template bordersolid, dashed, dotted, double line; width (pt); colour—

Print options stored with a template cover duplex, front/back mirroring, page size, rows/columns per page, page padding, and document padding. A print-layout preset overrides these for the exported PDF; see Create a print-layout preset.