Field types and settings

Add a field type

A field type is a PHP class that extends VLT\Remaily\Fields\Field. Register it with remaily_field_types, and it appears among the editor’s field buttons with its own sidebar settings, checks and messages.

add_filter( 'remaily_field_types', function ( $types ) {
    require_once __DIR__ . '/class-rating-field.php';

    return $types + [ 'rating' => new My_Rating_Field() ];
} );

class My_Rating_Field extends VLT\Remaily\Fields\Field {
    public function type() { return 'rating'; }
    public function label() { return 'Rating'; }

    protected function own_defaults() { return [ 'stars' => 5 ]; }

    public function editor_schema() {
        return [ 'stars' => [ 'type' => 'number', 'label' => 'Stars', 'help' => 'How many stars to show.' ] ];
    }

    public function control( array $field, array $ctx ) {
        // The inputs, named $field['name'], with the ID in $ctx['id']
    }

    public function messages() {
        return [ 'rating_too_low' => [ 'label' => 'Rating under 3', 'default' => 'Please tell us what went wrong.' ] ];
    }

    public function validate( $value, array $field, VLT\Remaily\Submission\Submission $submission ) {
        return parent::validate( $value, $field, $submission ) ?: ( '' !== $value && (int) $value < 3 ? 'rating_too_low' : '' );
    }
}

validate() returns a message key, or an empty string when the value is fine. The type’s messages show in Settings → Messages and in the Messages tab of forms that use it. Other methods you can override:

• kind(): a template folder to share with similar types, such as input.
• icon(): the name of a built-in icon, or the d of a 24×24 stroke path for your own.
• value() and mail_value(): how the posted value is read, stored and printed in mail.
• submits(): false for a field that sends nothing.
• shared(): which settings every field has your type uses: required, style, class, id, attrs. The sidebar shows only those. A value can be a when, as in editor_schema(): Radio returns [ 'required' => [ 'allow_null' => [ true ] ] ] + parent::shared().
• request_value( $request, $field ): the value from the whole request, for a control that sends more than its own name. It calls value() by default. The Tel field uses it to read the number together with the country picked (_remaily_country[name]).
• tip(): a short tip with an example, shown at the bottom of the editor while the field is selected.
• menu(): 'main' for the row of field buttons, or 'more' for the More menu. summary() is its line there. remaily_field_menu moves any type.
• docs(): the address of the type’s page in your documentation, linked from its sidebar. Empty by default, so no link shows.

The sidebar control types for editor_schema() are text, textarea, number, toggle, select, options, pairs, field (pick another field), date and countries (pick countries by name; the value is their codes, "us, ca, gb"). A control’s when shows it only while other settings have those values, such as 'when' => [ 'mask' => [ '' ] ].

Add a place

A place is a chip with nothing to set up, like Captcha and Response. remaily_places adds one: it shows in the field buttons until placed, and prints what its render returns.

add_filter( 'remaily_places', fn( $places ) => $places + [
    'map' => [
        'label'   => 'Map',
        'summary' => 'Shows the office on a map',
        'menu'    => 'more',
        'render'  => fn( $form ) => '<div class="my-map"></div>',
    ],
] );

Add a payment provider

remaily_payment_gateways maps a field type to a class that implements VLT\Remaily\Payments\Gateway, next to Stripe and PayPal. Register the field type with remaily_field_types as above, extending VLT\Remaily\Fields\Payment.

Add a setting to existing types

Three filters add a setting to any type, such as a width on every field:

add_filter( 'remaily_field_defaults', fn( $defaults ) => $defaults + [ 'width' => 'full' ] );

add_filter( 'remaily_field_schema', fn( $schema ) => $schema + [
    'width' => [ 'type' => 'select', 'label' => 'Width', 'options' => [ 'full' => 'Full', 'half' => 'Half' ] ],
] );

Each filter also gets the type’s ID, so a setting can go to some types only. Plain values are cleaned by the type of their default. A setting that holds an array needs remaily_field_sanitize to clean it.

The setting reaches $field in your field templates:

<div class="field is-<?php echo esc_attr( $field['width'] ); ?>">