Large screen
Small screen
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:
- text elements inside a document template, such as a specimen label;
Custom fieldcolumns inside a record-export preset.
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.
The basics in one minute
Section titled “The basics in one minute”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:
| Add | Purpose | Example | Output |
|---|---|---|---|
??text | Fallback when the field is empty | [taxonomy::specificEpithet??sp.] | sp. when no epithet is recorded |
#label | Print 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.
Common expressions
Section titled “Common expressions ”Copy these into a document-template text element or into a tabular preset column as noted. All examples below use specimen fields.
Species name
Section titled “Species name ”[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.
Full locality
Section titled “Full locality ”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 typetoList Valuesand choose the comma format. - Record-export preset: set
Mapping typetoList field,List outputtoOne column, andSeparatortoComma (A, B). Paste the expression intoAdvanced>Raw source expressionand setColumn 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.
Testis size
Section titled “Testis size ”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]"]]| Record | Output |
|---|---|
| Scrotal, 10 mm by 6.5 mm | 10 x 6.5 |
| Scrotal, width missing | Nothing |
| Abdominal | Nothing |
| Female | Nothing |
"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.
Encoded field labels
Section titled “Encoded field labels ”[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.
Placeholders in detail
Section titled “Placeholders in detail”Symbols
Section titled “Symbols”| Symbol | Meaning | Example |
|---|---|---|
[ ] | Field placeholder | [fieldNumber] |
:: | Separates table from field in a full key | [specimen::fieldNumber] |
?? | Fallback when the field is empty | [specimen::preparator??N/A] |
#label | Outputs a coded field's label instead of its code | [mammalAttribute::testisPosition#label] |
-img | Renders 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"]] |
Field keys
Section titled “Field keys”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.
Missing values
Section titled “Missing values”?? specifies what prints when a field is empty. The No Content Placeholder setting writes this syntax for you:
| Option | Written as | Output 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.
Sex icons and pictures
Section titled “Sex icons and pictures”Two placeholders render images rather than text and must appear alone in their text element:
[mammal.sex]-imgdraws a sex icon (the key must end in.sex; set icon dimensions with width and height).[media::media]withText typeset toPicturerenders the record's attached images in a grid.
Custom fields
Section titled “Custom fields ”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:
| Control | What it does |
|---|---|
Add field | Inserts a field from the picker. |
Add text B | Inserts fixed text or a separator. |
Add conditional text | Inserts conditional text. |
Show label | Adds #label on a coded field to print its label instead of its code. |
Edit conditional text | Reopens a conditional text segment for editing. |
Move segment up / Move segment down | Reorders segments (written left to right). |
Remove segment | Deletes a segment. |
Expression: | Previews the saved expression string. |
Column name | Sets the output column header. |
Examples of complete custom fields:
[personnel::initial]-[specimen::fieldNumber][taxonomy::genus] [taxonomy::specificEpithet]NAHPUNAHPU 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.
Conditional output
Section titled “Conditional output ”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).
Choose a type
Section titled “Choose a type”| You want to… | Type | Example output |
|---|---|---|
| Bracket a value when another field flags it | Conditional brackets | [82.5] when weight was estimated |
| Replace a value when another field matches | Conditional field | ? instead of the epithet when ID is uncertain |
| Replace a value based on its own value | Conditional value | Not recorded when the value is 0 |
| Output standalone text (such as a unit) conditionally | Conditional text | mm only after a recorded width |
In the dialog:
- Select
Conditional type. - Select
Target field(the field to bracket or replace).Conditional texthas no target and appends to the element text. - Add one or more conditions (
Controlling field, comparison operator, and value).Conditional valuetests the target itself, so no separate field picker appears. - For multiple conditions, set
Match logictoAny condition (OR)orAll conditions (AND). - Enter
Replacement text(orText when matchedand optionalText otherwise (optional)for conditional text). LeaveReplacement textblank to hide the value when matched.
Conditional text (if and else)
Section titled “Conditional text (if and else) ”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.
ifmust 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.
Worked examples
Section titled “Worked examples”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==""]=>"?"]]Rules for conditions
Section titled “Rules for conditions”- 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
!=). UseIs empty(=="") orIs 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.
Syntax reference
Section titled “Syntax reference”The dialog generates these automatically; use this reference when reading or editing expressions by hand.
| Symbol | Name | Meaning |
|---|---|---|
[[ … ]] | Expression delimiters | Open and close a conditional expression. |
][ | Target separator | Separates the target field from conditions. |
== | Equals | Matches an exact value. |
!= | Not equals | Matches any non-empty differing value. |
~= | Contains | Matches when the substring appears anywhere in the value. |
!="" | Is not empty | Matches any non-blank value. |
=="" | Is empty | Matches blank or missing values. |
&& | All (AND) | Every condition must match. |
|| | Any (OR) | At least one condition must match. |
" … " | Value quotes | Wrap every comparison value (empty for emptiness checks). |
\", \\ | Escapes | Literal quote or backslash inside quotes. |
]=> | Replacement marker | Ends conditions and begins replacement/output text. |
if | Conditional text keyword | Replaces the target so the expression emits text. |
| | Else separator | Starts 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"]]Text types and their formats
Section titled “Text types and their formats ”In document templates, Text type and Format format the rendered value. A tabular Single field column exposes the same formatting via Value format.
| Text type | Format options |
|---|---|
Normal Text | Normal, Uppercase, Lowercase, Capitalize |
Picture | Sized with width and height rather than a format |
Markdown | Normal; renders rich text such as narratives |
Coordinates | Decimal, Cardinal Dec, DMS, DDM |
List Values | Pipe, comma, semicolon, slash, new line, bulleted, custom separator |
Nested List | Table (adds Header Case) or Card list |
Dates | YYYY-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 Time | 17 combinations of the date formats above with 24h, 12h, ISO, and time-only outputs |
Time | 24h, 24h seconds, 12h, 12h padded |
Sex | Format and Missing, described below |
Number | Original, or 0, 1, 2, or 3 decimal places |
Encoded Text | Default mapping or Custom mapping... |
Nested List formats repeated child records (specimen parts, personnel, collecting methods) and usually benefits from dynamic text sizing.
Encoded Text: what decodes
Section titled “Encoded Text: what decodes”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 with | Code 0 | 1 | 2 | 3 | 4 | 5 | 6 |
|---|---|---|---|---|---|---|---|
::sex | Male | Female | Unknown | Gynandromorph | Hermaphrodite | Female? | Male? |
::iDConfidence | Low | Medium | High | ||||
mammalAttribute::age | Adult | Subadult | Juvenile | Unknown | |||
herpAttribute::age | Adult | Juvenile | Neonate | Metamorph | Unknown | ||
::testisPosition | Scrotal | Abdominal | |||||
::epididymisAppearance | Tubular | Partial | Not Tubular | ||||
::vaginaOpening | Imperforate | Perforate | |||||
::pubicSymphysis | Close | Small Open | Open | ||||
::reproductiveStage | Nulliparous | Primiparous | Multiparous | ||||
::mammaeCondition | Small | Large | Lactating | ||||
::echolocation | FM | CF | QCF | None | |||
::ovaryAppearance | Smooth | Ova minute | At least one ovum ≥ 1 mm dia. | ||||
::oviductAppearance | Straight | Convoluted | |||||
::fat | None | Trace | Light | Moderate | Heavy | Extremely Heavy | |
::bodyMolt | None | Trace | Light | Moderate | Heavy |
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.
Decode an encoded field
Section titled “Decode an encoded field ”Keep the placeholder unchanged and let Encoded Text or #label decode it:
- Document template: set
Text typetoEncoded Text. Each placeholder in the element decodes against its own field:Testes: [mammalAttribute::testisPosition][mammalAttribute::age], [mammalAttribute::testisPosition] - Record-export preset: use a
Single fieldcolumn withValue formatset toEncoded text, or in aCustom fieldcolumn append#label(or selectShow labelon the segment):[mammalAttribute::testisPosition#label], [mammalAttribute::mammaeCondition#label] - Inline
#label: decodes a single placeholder with the default mapping in any text type. Place#labelbefore any fallback:[mammalAttribute::sex#label??Unknown]. - Custom labels: in the template editor, choose
Custom mapping...and selectMap encoded values(starts prefilled from defaults). In a tabular preset, entercustom_map:underAdvanced>Raw format option:Separatecustom_map:0=Scrotal,1=Abdominalcode=labelpairs 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.
Sex formatting
Section titled “Sex formatting”| Control | Options |
|---|---|
Format | Symbol (♂/♀), Letter (M/F), Text (Male/Female) |
Missing | Unknown, N/A, None |
Uncertain determinations retain their question mark in every format: Female?, F?, ♀?, and Male?, M?, ♂?.
Troubleshooting
Section titled “Troubleshooting”| Symptom | What to check |
|---|---|
| Conditional prints as plain text | Syntax 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 text | The element must contain only […sex]-img, with a key ending in .sex. |
| Record images do not appear | The element must contain only [media::media] with Text type set to Picture. |
| Unexpected custom-field header | Set Column name; otherwise it defaults to the first field or fixed text. |
| Coded field prints a number | Use Encoded Text / Encoded text or #label, and verify the code is in the mapping. |
| Condition never matches | Conditions compare stored codes, are case-sensitive, and blank fields only match Is empty. |
| Conditional text prints nothing | Add an else branch after | for non-matching records, and ensure if is lowercase. |
Template editor options
Section titled “Template editor options ”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.
Toolbar
Section titled “Toolbar”| Control | What it does |
|---|---|
Add text | Places a text element on the canvas. |
Add image | Places a static image from the device. |
Add line | Places a straight rule. |
Add shape | Places a rectangle, ellipse, circle, triangle, or polygon. |
Save template | Saves the template (Save as... creates a variation). |
Undo / Redo | Steps through edit history. |
Template border | Configures the outer template border. |
Show grid / Hide grid | Toggles the alignment grid. |
Enable snap / Disable snap | Toggles snapping to the grid and elements. |
| Canvas lock | Locks panning so dragging does not move the canvas. |
Select specimen for text preview | Chooses the record used to populate live preview placeholders. |
Template settings D | Name, description, side count, and template size. |
Preset template A | Loads a bundled starting template. |
Zoom in / Zoom out | Scales canvas view only (does not affect PDF size). |
1 sided / Front / Back | Switches side mode and active side. |
| Mirror | Mirrors a side for folded tags. |
Text element options
Section titled “Text element options”Content
Section titled “Content”| Option | Values | Notes |
|---|---|---|
| Text | Text, placeholders, conditionals | Element content. |
Text type | See table above | Selects value formatting category. |
Format | Depends on Text type | Specific format within that category. |
No Content Placeholder | Blank, table::field, N/A, None, custom | Writes ?? fallback. |
Conditional output | Brackets, field, value, text | Writes [[ … ]] or [[if] … ]] expressions. |
Find and replace | — | Edits element text in place. |
| Replacement rules | Pattern, replacement, match type, case sensitivity | Rewrites values after formatting. |
Map encoded values | Default or custom mapping | Maps stored codes to labels for Encoded Text. |
Type and style
Section titled “Type and style”| Option | Values |
|---|---|
Font | Bundled and installed fonts (missing fonts are marked (not installed)) |
| Font size | Points, with step buttons |
Bold, Italic, Underline, Strikethrough | On or off |
| Alignment | Align left, Align center, Align right |
| Case | Normal, Uppercase, Lowercase, Capitalize |
| Text colour | Colour picker |
Box and placement
Section titled “Box and placement”| Option | Values | Notes |
|---|---|---|
| Position | X and Y in mm | Measured from the template's top-left corner. |
| Max width | mm | Wraps text at this width (unset = no wrapping). |
| Height | mm | Bounds box height. |
| Padding | pt | Space inside the box around text. |
| Rotation | 0–359° | Whole degrees. |
| Background colour | Colour or none | — |
| Border colour, width, stroke | Colour, pt, solid / dashed / dotted / double | — |
| Corner radius | pt | Rounds box corners. |
| Dynamic sizing | On or off | Lets the box grow with content; pair with Auto-fill page. |
| Stacking | Bring to front, Bring forward, Send backward, Send to back | — |
| Lock | On or off | Prevents dragging or resizing. |
| Visible | On or off | Hidden elements stay saved but do not print. |
QR code
Section titled “QR code”Convert a text element into a scannable QR code:
| Option | Values |
|---|---|
| QR code | On or off |
| Size | mm |
| Background colour | Colour picker |
| Shape | Square 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.
Picture
Section titled “Picture”| Option | Values |
|---|---|
| Width, height | mm |
Only a bare [media::media] or [media] element resolves to record images; mixing text with the placeholder disables image rendering.
Image, line, and shape options
Section titled “Image, line, and shape options”Static images, lines, and shapes are decorative and carry no record data:
| Element | Options |
|---|---|
| Image | Image path, position, width, height, rotation, stacking, lock, visibility |
| Line | Position, length, rotation, thickness (pt), colour, stroke style, stacking, lock, visibility |
| Shape | Shape 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.
Template options
Section titled “Template options”| Option | Values | Notes |
|---|---|---|
Template name | Text | Must be unique; renaming updates all print layouts referencing it. |
Description | Text (up to 80 characters) | Optional. |
Record type | Specimen, Specimen parts, Symbionts, Site, Collecting event, Narrative, No records | Determines available fields and records. |
| Side count | 1 sided or 2 sided | One-sided mode keeps the Back design saved without printing it. |
| Width, height | mm | Size of one block, not the sheet. |
| Template border | solid, 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.



