Datatypes

Latch includes a wide assortment of datatypes to use as form fields.

Each datatype may define its own settings, but most datatypes include these default settings:

• Character Limit: Maximum string length for the field value.
• Placeholder: Text to display when no value has been entered.
• Default Value: The default value for the field.

Included Datatypes

Frontend datatype modules are available in js/forms/datatypes. Server-side datatype handlers are available in lib/forms/datatypes when special save, validation, or render behavior is needed.

Common included frontend datatypes include:

• address
• button
• blocks
• checkbox
• color
• custom
• datalist
• datetime
• editor
• email
• file
• google-font
• hidden
• image
• list
• number
• password
• range
• select
• tags
• text
• textarea
• timestamp
• url

The file datatype stores uploads under a basename derived from the field name by default, preserving established stable paths such as featured-media.png. Enable Preserve Original Filename on fields whose files are intended to be independently identifiable, such as a Media Library. The original basename is slugified and its extension normalized before storage.

The select datatype normally uses each line in Options as both the stored value and displayed label. Use value|Display label when a field needs to store a stable value while showing a friendlier label. Lines without a pipe retain the original behavior.

The blocks datatype provides an ordered content editor with nested layout groups and extension-aware block handlers. See Blocks for its authoring, persistence, and extension contracts.

Creating a Datatype

To create a new frontend datatype, add a JavaScript module at:

js/forms/datatypes/your-datatype.js

The filename corresponds to the entry label in the Data Type dropdown menu.

Example:

export async function backend(args)
{
    var html = args["preset_texts"];
    html += await Latch.Echo.field(`custom-setting${args["id"]}`, "Custom Setting", "text", "This is a description for your custom setting.");
    return html;
}

export async function frontend(args)
{
    args["html"] = `<label for="${args["id"]}">${args["label"]}</label><input name="${args["id"]}" id="${args["id"]}" value="${args["value"]}" />`;
    return args;
}

export async function frontend_ready(args)
{
    // Optional deferred setup after the field has been inserted.
}

backend(args)

Defines the settings that appear for the datatype in the form editor.

The args object includes:

• id: The unique numeric ID of the field. Use this when naming custom datatype settings.
• preset_texts: HTML for common settings such as character limit, placeholder, and default value.
• file_texts: HTML for common file upload settings such as max file size and file encryption.

Return the HTML for your datatype's settings.

frontend(args)

Defines the field markup on the frontend form.

The args object includes:

• id: The full unique identifier string for this field, such as field479.
• id_num: The numeric portion of the field ID, such as 479.
• label: The field description.
• label_position: Whether the label should appear before or after the field. Defaults to auto.
• type: The datatype name.
• placeholder: The field placeholder.
• value: The field value.
• meta: Additional metadata associated with the field.
• html: Default frontend HTML for the field.
• name: The field name/title.
• context: Arbitrary contextual value, defaulting to form.

Set args["html"] to your custom markup and return args.

frontend_ready(args)

Runs after the field has finished loading. Use this for deferred JavaScript setup.

It receives the same args object as frontend().

field_tools(args)

Optional. Returns custom field tool HTML for the admin/editor UI.

Return an empty string to suppress the default tools for the datatype.

Server-Side Setup

Create a PHP datatype class when you need custom validation, sanitization, metadata transformation, file saving, or render-time behavior.

Server-side datatype files live at:

lib/forms/datatypes/your-datatype.php

Example:

<?php

namespace Latch\Datatypes;

class YourDatatype extends Datatype
{
    public function validate($data, $name, $meta)
    {
        return true;
    }

    public function sanitize($value, $field_id, $type)
    {
        return \Latch\Input\sanitize("sql", \Latch\Input\sanitize("text", $value));
    }

    public function extra_metadata($metadata, int $field_id)
    {
        return $metadata;
    }

    public function backend_metadata(array $metadata): array
    {
        return $metadata;
    }

    public function render_field(array $args): array
    {
        return $args;
    }

    public function upload_filename(string $original_name, string $field_name, array $meta): string
    {
        return parent::upload_filename($original_name, $field_name, $meta);
    }

    public function is_file(): bool
    {
        return false;
    }
}

validate()

Checks whether submitted data should be accepted. If this returns false, form validation fails.

This is primarily used by file upload datatypes.

sanitize()

Transforms the submitted value before writing it to the database.

For multi-input datatypes, $type may be the subname of the field. Returning null prevents that submitted value from being saved.

extra_metadata()

Adjusts submitted field metadata before saving. For example, address.php adds geolocation metadata.

backend_metadata()

Adjusts datatype metadata before saving form settings from the Admin Dashboard.

render_field()

Adjusts field render arguments before Latch includes the field component.

For example, the custom datatype evaluates shortcodes in its saved content before rendering.

save()

Controls how uploaded file data is written. The base implementation supports encrypted and unencrypted file uploads.

Encrypted uploads use a random per-file data key and return its LATCH_KEY-wrapped value through saved_metadata(). Datatype overrides that transform uploads, including the core image datatype, should pass their final plaintext file through the parent save() implementation so encryption and metadata persistence remain consistent. See Cryptography for the storage and delivery contract.

saved_metadata()

Returns metadata produced by the most recent successful save() operation. The database upload pipeline commits these values beside the stored file reference. Unencrypted saves return an empty <Field Name>-encrypt-key value so replacing an encrypted file cannot retain a stale key.

is_file()

Return true when the datatype submits through $_FILES instead of $_POST.

Editor Sanitization

The editor and blocks datatypes preserve executable Administrator-authored content when the current sender is an Administrator.

In all other cases, Latch strips unsafe executable elements and attributes such as scripts, inline event handlers, srcdoc, unsafe URL schemes, and executable CSS. Safe inline formatting generated by editor toolbars is preserved.