Custom fields
Extend field definitions and write your own field types.
On this page
Extending a field
A field definition, or a view's entry for a field, can extends another field. It keeps that field's type, label and options and replaces whichever keys it sets; a nested fields map is replaced whole, not merged:
// site/views/post/index.json
{
"fields": {
"summary": { "extends": "description", "label": "Summary" }
}
}
// site/fields/password/index.json
{
"extends": "@phlat/password",
"options": { "required": true }
}
A name that resolves to nothing, a definition with no type, a type that doesn't exist and a field that extends itself are all errors when the definition is read.
Names from addons
A field or type from an addon carries its owner in the name, the way a view does: @ui/colors is the ui addon's field. A field type is a PHP class in phlat/fieldtypes/{type}/, an addon's fieldtypes/{type}/ or site/fieldtypes/{type}/.
Custom field types
Create site/fieldtypes/{type}/{type}.php, extending the primitive base that matches the JSON shape the type stores: FieldTypeText, FieldTypeNumber, FieldTypeList or FieldTypeObject. Your fields name it bare: "type": "rating".
<?php
namespace Phlat;
class FieldTypeRating extends FieldTypeNumber
{
public function decode(FieldValue $field): mixed
{
// clamp stored value to 0-5
return max(0, min(5, (int) $field->value));
}
public function stars(FieldValue $field): string
{
$rating = (int) $this->decode($field);
return str_repeat('★', $rating) . str_repeat('☆', 5 - $rating);
}
}
site/fieldtypes/
rating/
rating.php ← class FieldTypeRating extends FieldTypeNumber
index.json ← optional, default search behaviour
edit.latte ← optional, dash field-editing UI
render.latte ← optional, |render output
To control |render output, add render.latte beside the type (site/fieldtypes/{type}/render.latte, or site/fieldtypes/@phlat/{type}/render.latte to override a core type). It receives $field and $value (the decoded value: for code and markdown that is the source, so print $field->highlight() or $field->html()). A view renders a field through {name}.field.latte in its own folder (site/views/{view}/{name}.field.latte). Inside a stack or repeater, {parent}.{name}.field.latte (for example site/views/docs/stack.code.field.latte) is tried first. A container field's own folder holds the render of its entries for every view: site/fields/stack/code.field.latte renders a code entry of any stack, after the view's files and before the entry's own. A render.latte beside a field's own definition, site/fields/{name}/render.latte, takes precedence over the type's. To keep one field's per-view renders together, put render.{view}.latte beside it (site/fields/gallery/render.article.latte; a nested view uses dots, render.docs.api.latte), which beats render.latte on that view. The view's own render wins over all of these. edit.latte is a separate template for the dash editor.
A type in site/fieldtypes/ is your own and can't share a core type's name. To change a core type's editor templates or defaults, see Overrides; different behaviour is a type of your own.