Developer guide: add custom fields and integrations

What you will achieve

You will register a custom field type that appears in the Visual Form Builder, renders on the front-end (shortcode and block), and participates in validation, sanitization and conditional logic.

Prerequisites

• Plattio Forms installed (plugin version 2.4.10 or equivalent).
• WordPress >= 6.7 and PHP >= 8.1 (plugin minimum requirements).
• Developer access to add a small plugin or mu-plugin to your site.

API and public hooks you will use

• Action plattio_forms_register_fields — register new field types. (Fired early: use priority so your code runs when expected.)
• Filter plattio_forms_field_type_available — control whether a field type is available in the builder.
• Filter plattio_forms_render_custom_field_control — customize the field control HTML output when needed.
• Action plattio_forms_after_form — triggered after a form renders (useful for enqueuing field-specific frontend scripts).
• Shortcodes that will render your field at runtime: [plattio_form] and conversational variants [plattio_form_conversational]. Ensure your field rendering is compatible with shortcode output.

Step-by-step: register a custom field type

1. Create a simple plugin or mu-plugin file. Example filename: plattio-forms-custom-field.php.
2. Hook into the public action plattio_forms_register_fields. The Plattio Forms registry passes a registry object you call to register a field type.
3. Provide a unique field key, a human label, a preview template (shown in builder), a render callback (for front-end HTML), and optional sanitize/validate callbacks.

Example registration (outline)

<?php
add_action( 'plattio_forms_register_fields', function( $registry ) {
    $registry->register( 'my_custom_field', [
        'label' => 'My Custom Field',
        'preview_template' => function() {
            echo '<div class="pf-preview">My Custom Field</div>';
        },
        'render_callback' => function( $field, $value, $context ) {
            // $field = field schema array; $value = current value; $context = ['form_id' => ...]
            echo '<div class="plattio-form-field my-custom-field" data-field-id="' . esc_attr( $field['id'] ) . '"><label>' . esc_html( $field['label'] ) . '</label>';
            echo '<input type="text" name="' . esc_attr( $field['name'] ) . '" value="' . esc_attr( $value ) . '" />';
            echo '</div>';
        },
        'sanitize_callback' => function( $raw ) {
            return sanitize_text_field( $raw );
        },
        'validate_callback' => function( $sanitized, $field ) {
            // return true or WP_Error
            return true;
        },
    ] );
} );

See the shipped example for a working reference: plattio-forms/docs/examples/plattio-forms-custom-field-example.php.

Where to run your registration

1. Put your plugin file in wp-content/plugins/ (or mu-plugins) and activate it.
2. Plattio Forms registers its field registry early (it calls its registry_hook on init with priority 1). Ensure your registration runs on plattio_forms_register_fields (no extra init wrapper required if you use that action).

What to expect after completing these steps

• Your field type label appears in the Visual Form Builder field list and in the field library preview.
• The preview_template runs inside the builder canvas so authors see a representative preview.
• When the form is rendered via shortcode ([plattio_form id="..." ]) your render_callback outputs the front-end HTML and your sanitize/validate callbacks are used during submission handling.

Integration tips, limitations and troubleshooting

• Hook early: if your custom field is not visible in the builder, confirm your code hooked to plattio_forms_register_fields and ran before the builder requested the field list.
• Field availability: use plattio_forms_field_type_available if you need to enable the field only under certain conditions (module present, WooCommerce active, etc.).
• Assets: enqueue frontend scripts/styles in response to plattio_forms_after_form so assets load only on pages that include forms.
• Save & Resume / file fields: be aware that drafts exclude file and signature values—if your field depends on uploaded files recommend reupload on resume.
• Server requirements: plugin requires WordPress >= 6.7 and PHP >= 8.1.

Developer references

• Example custom field: plattio-forms/docs/examples/plattio-forms-custom-field-example.php
• Developer API overview: plattio-forms/docs/DEVELOPER-API.md
• Foundation and registry hooks: plattio-forms/includes/class-plattio-forms-foundation.php

Expectations summary

After registering your field, it will be selectable in the builder, show the preview there, render on the front-end via shortcodes and blocks, and participate in form validation and sanitization. If it does not appear, verify your registration code ran and that any conditional availability filters allow the field.