> For the complete documentation index, see [llms.txt](https://docs.dbnetsoft.com/dbnetsoft/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dbnetsoft.com/dbnetsoft/finalscore/expressions/custom-functions-and-fields.md).

# Custom functions and fields

Your own functions and additional athlete fields, defined per event on Setup → Fields.

On **Setup → Fields** an event gets its own names for expressions: **additional fields** that every athlete can have a value for, and **functions** that work something out once so lists, rankings and rules can reuse it.

## Additional fields

An additional field is an extra value per athlete - a shirt size, a licence check, points from an earlier race.

| Column          | Meaning                                                                                                                                                    |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Key             | the name in expressions and the column in a CSV import: letters, digits and `_`, not starting with a digit; not the name of a built-in field (e.g. `club`) |
| Label           | the column header on the Athletes page                                                                                                                     |
| Type            | Text, Number, Yes / no, Choice                                                                                                                             |
| Options         | the choices of a Choice field                                                                                                                              |
| Athletes column | show it as a column on the Athletes page                                                                                                                   |
| Order           | the order of the fields                                                                                                                                    |

The values are entered on the **Athletes** page or imported; an athlete import creates a field for every column it does not know.

### In expressions

* **By its key** - typed by the field's type: `shirtSize`, `points`, `checkedIn`.
  * Number: a number (empty when the value is not a number).
  * Yes / no: true or false - true for `yes`, `1`, `true` or `x`.
  * Text and Choice: the text.
* **As `custom.<key>`** - always the text as entered: `custom.points`. Values without a field definition (e.g. from an older import) are reachable this way too.

{% hint style="warning" %}
Use the key alone for yes / no fields in filters and rules: `checkedIn` is true or false, while `custom.checkedIn` is the text "no" - and a text that is not empty counts as true.
{% endhint %}

Additional fields work in athlete, heat and bracket lists, in formulas, rankings and rules - not in team lists.

## Functions

A function is an expression with a name, worked out for the row it is used in.

| Column      | Meaning                                                                                        |
| ----------- | ---------------------------------------------------------------------------------------------- |
| Name        | how it is called: letters, digits and `_`, not starting with a digit, unique                   |
| Parameters  | optional: names separated by `,` (`prefix, length`) - inside the expression they are variables |
| Expression  | what it works out, with the row's fields and its parameters                                    |
| Value       | the result for the athlete whose bib you enter above the table                                 |
| Description | a note for you                                                                                 |
| Order       | the order in the table                                                                         |

### Calling a function

* Without parameters: `fullName` or `fullName()`.
* With parameters: `label("Mr. ")`. A parameter you leave out is empty.

A function sees the fields of the row it is used for (the athlete, the team, ...) and its parameters - not the variables of the expression calling it. In a ranking, formula or rule it sees [the fields there](https://docs.dbnetsoft.com/dbnetsoft/finalscore/expressions/fields.md#formulas-rankings-and-rules).

### Examples

| Name           | Parameters | Expression                                             | Use                                      |
| -------------- | ---------- | ------------------------------------------------------ | ---------------------------------------- |
| `fullName`     |            | `firstName + " " + (lastName \| string.upcase)`        | `fullName` in a column                   |
| `label`        | `prefix`   | `prefix + bib`                                         | `label("#")` → `#12`                     |
| `ageGroup`     |            | `iif(age >= 50, "50+", iif(age >= 40, "40+", "Open"))` | a column, a ranking group, a filter      |
| `runsWon`      | `key`      | `countWhere(rounds[key].runs, "rank == 1")`            | `runsWon("final")`                       |
| `doublePoints` |            | `ifEmpty(points, 0) * 2`                               | with an additional Number field `points` |

### Good to know

* **A function named like a built-in or additional field replaces it everywhere** - a function `displayName` changes `displayName` in every list, and a function `points` would hide the field `points` (and call itself when it reads it). Functions are looked up before fields, ignoring case.
* Do not name functions or fields like the built-in functions or groups (`iif`, `string`, `math`, ...) - they would hide them.
* Functions can call other functions, up to 16 deep; deeper (e.g. a function calling itself without end) gives `#ERR`.
* Changing a function updates every list. A ranking may call a function that reads other ranks; a circle (ranking A reads B, B reads A) is refused.
