Numbers and money
The number field (min, max, step, integer, display unit) and the money field (a decimal amount with its ISO 4217 currency, fixed or chosen), with parameters, validation, stored shapes and template values.
number
A number: a distance, a capacity, a rating, a duration in minutes. Held once for every locale.
fields:
- { name: capacity, type: number, integer: true, min: 1, max: 5000, index: true }
- { name: rating, type: number, min: 0, max: 5, step: 0.5 }
- { name: walkMinutes, type: number, min: 0, unit: minutes } Parameters
| Parameter | Type | Default | What it does |
|---|---|---|---|
min | number | none | The smallest value accepted. |
max | number | none | The largest value accepted. |
step | number | none | The value must be a whole number of steps, counted from min when it is set and from zero otherwise. min: 1, step: 2 accepts 1, 3, 5. |
integer | boolean | false | Refuses fractions. |
unit | string | none | A unit shown beside the control (km, minutes). It is never applied to the value and a template does not receive it. |
Validation
| Code | Message |
|---|---|
number | Must be a number |
integer | Must be a whole number |
min_value | Must be N or more |
max_value | Must be N or less |
step | Must be a multiple of N |
Stored value and template value
A JSON number. A form may post a numeric string such as "12"; it is stored as a number. A string that is not a number is kept as posted and reported, never turned into zero.
A template receives a whole number when the field is integer or the value has no fraction, otherwise a decimal. Format it for the reader with |number, which uses the request locale’s grouping and decimal separator; |number:1 fixes one decimal place.
<p>Capacity: {{ entry.capacity|number }}</p>
{% if entry.rating %}<p>Rated {{ entry.rating|number:1 }} out of 5</p>{% endif %} A number reads an old numeric text value exactly and a boolean lossily when a schema change retypes it.
money
An amount of money in a currency: an entry fee, a price from, a deposit. The amount is a decimal string, never a floating-point number, so 0.10 stays 0.10. The currency is an ISO 4217 code carried on every value; it is never inferred from a locale.
fields:
- { name: entryFee, type: money, currency: GBP, min: 0, max: "250.00" }
- { name: deposit, type: money, currencies: [GBP, EUR] }
- { name: refund, type: money, currency: GBP, negative: true } Parameters
| Parameter | Type | Default | What it does |
|---|---|---|---|
currency | ISO 4217 code | none | The one currency accepted, fixed in the editor. An amount given without a currency takes this one. |
currencies | list of codes | the site’s, then the source locale’s | The currencies the editor offers, plus any the value already has. |
min | decimal | none | The smallest amount, compared exactly as a decimal. |
max | decimal | none | The largest amount, compared exactly as a decimal. |
negative | boolean | false | Accepts amounts below zero. |
Validation
| Code | Message |
|---|---|
money_amount | Enter an amount such as 12.50 (the amount is not a plain decimal: 12,50 and 1e3 are refused) |
money_currency_empty | Choose a currency |
money_currency | XXX is not an ISO 4217 currency code |
money_currency_fixed | Must be in GBP |
money_currency_allowed | Must be one of GBP, EUR |
money_precision | JPY has 0 decimal places (more decimal places than the currency has) |
money_negative | Must not be below zero |
min_value / max_value | Must be N or more / Must be N or less |
Stored value
{ "amount": "12.50", "currency": "GBP" } On save the amount is padded to the currency’s minor units: 12.5 in GBP is stored as 12.50, 1250 in JPY as 1250. The code is upper case. In a seed file or an import, a field with a fixed currency also accepts a bare amount (12.50).
With index: true, the amount is projected as a number under the field’s name and the code as text under <name>.currency, so a query filters “under 50” within one currency. Amounts in different currencies are never compared, and there is no conversion between currencies.
Template value
| Property | What it is |
|---|---|
amount | The decimal amount as stored, such as 12.50. |
currency | The ISO 4217 code. |
formatted | The amount formatted for the request locale, such as £12.50. |
{% if entry.entryFee %}<p>Entry {{ entry.entryFee.formatted }}</p>{% endif %}
<p>Deposit {{ entry.deposit|money }}</p> |money formats a money value for the request locale; |currency:"EUR" formats a plain number in a named currency (Filters).
Text and slug
The text field (single or multi-line, length limits, pattern, email format) and the slug field (a per-locale URL segment generated from another field), with parameters, validation and template values.
Boolean and select
The boolean field and the select field (one option or several from a declared list, each option with a stable id and per-locale label), with parameters, validation, stored values and what templates receive.