Skip to main content

​
When to use these helpers

Use these only in an entity serial configuration or a form-numbering configuration. They are not a general calculated-field API.

​
Calling style

Call a helper as serialPad($sequence, 5). In entity-serial and form-numbering editors, autocomplete identifies both helpers as callable functions and shows the signatures below; after |, it identifies their transform forms. Not every helper is available everywhere: validation, form, and document-template helpers have distinct context contracts. Editor suggestions are not proof that a helper is supported at runtime.

​
Complete function reference

​
serialDate

Formats a serial date using only yyyy, yy, MM, and dd tokens. An invalid date returns an empty string. Signature: serialDate(format, value = $now, timezone = $timezone) Example:
Availability: Entity Serial IDs and form-numbering formats only; both function and transform forms are registered in those contexts. Note: As a transform, the value to the left of the pipe is the date format: "yyyy-MM" | serialDate($now, $timezone).

​
serialPad

Pads a serial sequence from the left. Only the first character of char is used. Signature: serialPad(value, width, char = "0") Example:
Availability: Entity Serial IDs and form-numbering formats only; both function and transform forms are registered in those contexts. Note: As a transform, the value to the left of the pipe is the value to pad: $sequence | serialPad(5).

​
Runtime behavior and edge cases

​
serialDate rules

Only yyyy, yy, MM, and dd are supported date tokens. Other text and differently cased tokens are literal text; do not expect YYYY or time tokens to work like they do in another formatting library. KayanOS converts the input to a date and returns an empty string when it cannot form a valid date. Use the $timezone supplied by the serial configuration rather than an unreviewed free-form timezone: the same instant can fall on a different local day at a time boundary. Use function form when you want the argument order to remain explicit:
Remember that transform form has a visually different order: the date format, not the date itself, is the value to the left of the pipe. Write "yyyy-MM" | serialDate($now, $timezone), not $now | serialDate(...).

​
serialPad rules

The helper converts its value to text, so numeric 42 becomes "42". It coerces width to a number. A width of zero or less leaves the string unpadded. A width that cannot be converted to a number also leaves the string unpadded. It never truncates a value that is already longer than the requested width. Only the first character of char is used; a missing or empty character falls back to 0. Therefore serialPad(42, 5, "AB") returns "AAA42", while serialPad("123456", 5) returns "123456".

​
What formatting does and does not guarantee

These helpers do not allocate a number, reserve a sequence, or validate uniqueness. They only format the $sequence supplied by the serial-issuance path. Keep $sequence in the format unless an approved design prevents collisions some other way, and test the expression in preview and in a real issuance flow. Read Serial IDs for the context variables, namespace policy, collision behavior, and correction rules.

​
Before you publish

  • Start with a known value and confirm the expected result.
  • Handle null, empty text, and empty lists deliberately.
  • Do not place secrets, access tokens, or sensitive personal data in an expression.
  • Read expression contexts and availability before copying an expression between features.
Serial and form-number helpers in KayanOS