Jfb Form Sidebar Panel

JetFormBuilder: form-level settings panel in the Gutenberg sidebar

JetFormBuilder forms are stored as a custom post type (jet-form-builder) edited in the standard Gutenberg block editor. Companion plugins add per-form settings by injecting a panel into the editor's document sidebar — the panel reads and writes post meta on the form, so each form gets its own configuration independently of the plugin's global Settings page.

This skill covers that subsystem. It is distinct from the global plugin Settings page covered in the jfb-settings-tab skill — that one uses Vue + cx-vui components, this one uses WordPress packages (@wordpress/components, React under the hood) and standard post-meta REST exposure.

A typical JFB companion plugin (e.g. media-storage-for-jetformbuilder) ships both: a global tab for site-wide defaults, and a per-form sidebar panel for overrides. See the Dual-mode pattern section below.

API stability note

The register_post_meta + REST exposure pattern is standard WordPress and stable since WP 4.9. The JFB-specific pieces — the 'jet-form-builder/editor-assets/before' PHP action, the 'jet.fb.register.plugins' JS filter, and the useMetaState hook exposed on window.JetFBHooks — are stable across the JFB 3.x line in the source observed. The plugin-version-tested field records last end-to-end verification only.

When to use this skill

• A JFB companion plugin needs settings that differ between forms.
• The user asks how to add a sidebar panel to the JFB form editor.
• The diff/files contain register_post_meta for the jet-form-builder post type, jet.fb.register.plugins, jet-form-builder/editor-assets/before, or useMetaState.

Architecture in one paragraph

The JFB form CPT (jet-form-builder) registers post meta keys with 'show_in_rest' => true and an auth_callback, making them readable and writable through the WordPress REST API. The Gutenberg post editor automatically syncs registered REST meta with its data store, so any UI bound to that meta auto-saves when the user clicks "Update". JFB exposes a JS filter 'jet.fb.register.plugins' that collects panel definitions, each containing a render function. Inside the render function, the panel calls JFB's useMetaState hook (a thin wrapper around Gutenberg's useEntityProp) to bind component state to a meta key, then renders WP standard form controls.

Step 1 — PHP: register the post meta

<?php
namespace MyPlugin\FormSettings;

class FormMeta {

    const FORM_CPT = 'jet-form-builder';
    const META_KEY = '_myplugin_form_settings';

    public function register() {
        add_action( 'init', array( $this, 'register_meta' ) );
    }

    public function register_meta() {
        register_post_meta(
            self::FORM_CPT,
            self::META_KEY,
            array(
                'type'              => 'string',
                'single'            => true,
                'default'           => wp_json_encode( $this->defaults() ),
                'show_in_rest'      => array(
                    'schema' => array( 'type' => 'string' ),
                ),
                'auth_callback'     => static function ( $allowed, $meta_key, $post_id, $user_id ) {
                    return user_can( $user_id, 'edit_post', $post_id );
                },
                'sanitize_callback' => array( $this, 'sanitize' ),
            )
        );
    }

    public function defaults() {
        return array(
            'enabled'         => false,
            'target_folder'   => '',
            'max_filesize_mb' => null,
        );
    }

    public function sanitize( $raw ) {
        $decoded = json_decode( (string) $raw, true );
        if ( ! is_array( $decoded ) ) {
            return wp_json_encode( $this->defaults() );
        }
        // Coerce types per known schema.
        $clean = array(
            'enabled'         => ! empty( $decoded['enabled'] ),
            'target_folder'   => sanitize_text_field( $decoded['target_folder'] ?? '' ),
            'max_filesize_mb' => isset( $decoded['max_filesize_mb'] )
                ? (float) $decoded['max_filesize_mb']
                : null,
        );
        return wp_json_encode( $clean );
    }
}

Critical points:

• Use post-level auth_callback. The signature is ( $allowed, $meta_key, $post_id, $user_id ) — call user_can( $user_id, 'edit_post', $post_id ). This matches what JFB core itself does and scopes access correctly. Avoid the simpler current_user_can( 'edit_posts' ) shortcut: it's a global capability check and lets any post-editor write meta on any form, which is over-permissive.
• Store one JSON blob per feature, not separate meta keys per field. JFB core does this (_jf_args, _jf_messages, _jf_actions, etc.) and the convention keeps the wp_postmeta table sane and the REST schema simple.
• Always provide sanitize_callback that decodes, type-coerces, and re-encodes. The REST API will accept whatever string the client sends — your sanitizer is the gate.
• type: 'string' is intentional. Even though the data is structurally an object, you store it as a JSON-encoded string; if you set type: 'object' you have to declare a full JSON schema and the default handling becomes awkward.

Step 2 — PHP: enqueue the editor assets

JFB fires 'jet-form-builder/editor-assets/before' when the form editor loads its scripts. Hook into this rather than enqueue_block_editor_assets directly — it ensures your bundle loads in the right order, after JFB's own data module is registered.

add_action(
    'jet-form-builder/editor-assets/before',
    function () {
        $handle = 'myplugin-form-editor';

        wp_enqueue_script(
            $handle,
            plugins_url( 'assets/js/form-editor.js', __FILE__ ),
            array(
                'wp-hooks',
                'wp-element',
                'wp-components',
                'wp-data',
                'wp-i18n',
                'jet-fb-data', // exposes window.JetFBHooks (incl. useMetaState)
            ),
            '1.0.0',
            true
        );

        if ( function_exists( 'wp_set_script_translations' ) ) {
            wp_set_script_translations( $handle, 'myplugin' );
        }

        // Pass site-wide defaults and labels to the panel.
        wp_localize_script(
            $handle,
            'MyPluginFormPanel',
            array(
                'metaKey'        => '_myplugin_form_settings',
                'globalDefaults' => array(
                    'max_filesize_mb' => (float) get_option( 'myplugin_max_filesize_mb', 0 ),
                ),
                'labels'         => array(
                    'panelTitle' => __( 'My Plugin', 'myplugin' ),
                    'enabled'    => __( 'Enable for this form', 'myplugin' ),
                    'folder'     => __( 'Target folder', 'myplugin' ),
                    'filesize'   => __( 'Max file size (MB)', 'myplugin' ),
                ),
            )
        );
    }
);

The jet-fb-data script handle is what exposes window.JetFBHooks.useMetaState. Declare it as a dependency even though JFB usually loads it first — the dependency is the contract.

Step 3 — JS: register the sidebar panel

import { addFilter } from '@wordpress/hooks';
import { __ } from '@wordpress/i18n';
import { Fragment, createElement as el } from '@wordpress/element';
import { ToggleControl, TextControl, RangeControl, Notice } from '@wordpress/components';

const { metaKey, globalDefaults, labels } = window.MyPluginFormPanel || {};
const useMetaState = window.JetFBHooks && window.JetFBHooks.useMetaState;

if ( ! useMetaState ) {
    // JFB data module not loaded — fail silently rather than crashing the editor.
    return;
}

function MyPluginPanel() {
    const [ raw, setRaw ] = useMetaState( metaKey, '{}', [] );

    const state = ( () => {
        try { return JSON.parse( raw ); } catch ( e ) { return {}; }
    } )();

    const update = ( patch ) => {
        setRaw( JSON.stringify( { ...state, ...patch } ) );
    };

    return el( Fragment, null,
        el( ToggleControl, {
            label:    labels.enabled,
            checked:  !! state.enabled,
            onChange: ( v ) => update( { enabled: v } ),
        } ),
        el( TextControl, {
            label:    labels.folder,
            value:    state.target_folder || '',
            onChange: ( v ) => update( { target_folder: v } ),
            disabled: ! state.enabled,
        } ),
        el( RangeControl, {
            label:    labels.filesize,
            value:    state.max_filesize_mb ?? globalDefaults.max_filesize_mb,
            min:      0,
            max:      500,
            step:     0.5,
            onChange: ( v ) => update( { max_filesize_mb: v } ),
            help:     state.max_filesize_mb == null && globalDefaults.max_filesize_mb > 0
                ? __( 'Using global default. Change here to override.', 'myplugin' )
                : undefined,
        } )
    );
}

addFilter(
    'jet.fb.register.plugins',
    'myplugin/form-panel',
    ( plugins = [] ) => {
        const def = {
            base: {
                name:  'myplugin-form-panel',
                title: labels.panelTitle,
            },
            settings: {
                icon:   'admin-generic',
                render: MyPluginPanel,
            },
        };

        // Idempotency guard — addFilter callbacks can run more than once.
        if ( ! plugins.some( ( p ) => p.base.name === def.base.name ) ) {
            plugins.push( def );
        }
        return plugins;
    }
);

useMetaState — what it actually does

useMetaState( metaKey, defaultValue, deps ) is a JFB-specific React hook exposed at window.JetFBHooks.useMetaState. It wraps useEntityProp from @wordpress/core-data to bind a component to a single post-meta key on the currently-edited post. It returns [ value, setValue ] like useState, but writes go through the WP data store and trigger Gutenberg's "post is dirty" indicator, so saving is automatic on the next "Update" click.

Treat the value as an opaque string in the hook layer; parse JSON in your component, write JSON back via setValue( JSON.stringify( ... ) ). Wrapping JSON.parse in try/catch is mandatory — corrupt or partially-saved meta should not crash the editor.

If window.JetFBHooks.useMetaState is undefined (JFB data module failed to load, version mismatch, etc.), the panel must fail silently. Don't throw, don't render an error UI inside the editor — that just confuses the user.

Native components — use these 1:1

These are from @wordpress/components and work without modification in the JFB sidebar context. They are not the same as the cx-vui-* set used in the global Settings page.

The full component catalog is on the WordPress block editor handbook page; the list above is the subset confirmed in the wild for JFB sidebar panels.

Beyond the native set — "hack zone"

@wordpress/components covers most form UI needs. If you need something not in the table:

Preferred: compose existing components

Most "complex" UI (a key/value pair editor, a list of items, a conditional reveal) is just a loop of TextControl + Button inside a PanelBody. Compose first.

Acceptable: bundle your own React component

For genuinely custom UI (a code editor, a JSON tree view, an OAuth-aware connector card) use @wordpress/element (which is React under another name) and write your own component. Keep it inside your plugin's bundle.

Avoid: Vue or cx-vui inside the sidebar

The JFB sidebar is React. Don't try to mount Vue components or pull in cx-vui-* here — that's the global Settings page world. Mixing the two breaks reactivity and confuses users.

Avoid: directly mutating Gutenberg state

Always go through useMetaState (or useEntityProp if you have a reason). Calling wp.data.dispatch( 'core/editor' ).editPost(...) directly works but bypasses the meta-key abstraction and makes save flow harder to reason about.

Storage format — one JSON blob per feature

Per the JFB convention, store all your form-level config under one meta key as a JSON-encoded string. Concrete row in wp_postmeta:

post_id  | meta_key                   | meta_value
123      | _myplugin_form_settings    | {"enabled":true,"target_folder":"uploads","max_filesize_mb":50}

Don't split into _myplugin_enabled, _myplugin_folder, _myplugin_filesize etc. — that bloats wp_postmeta, multiplies REST schema entries, and complicates atomic saves.

Dual-mode pattern: global default + per-form override

A common requirement: "if the form sets a value, use it; otherwise fall back to the plugin's site-wide setting." JFB does not provide a built-in merge utility — you implement it in your plugin's runtime code.

The convention observed in production companion plugins:

1. Global defaults live in the plugin Settings page (jfb-settings-tab skill), stored in wp_options.
2. Per-form overrides live in post meta, stored as JSON under a single key.
3. Both are passed to the panel JS via wp_localize_script — the global as globalDefaults, the meta key name as metaKey.
4. In the panel, when a per-form value is null / unset, render placeholder or help text showing the global default ("Using global default. Change here to override.").
5. On the frontend (form rendering / submission handler), implement the merge:

function get_effective_setting( $form_id, $key ) {
    $form_raw  = get_post_meta( $form_id, '_myplugin_form_settings', true );
    $form_data = $form_raw ? json_decode( $form_raw, true ) : array();
    if ( isset( $form_data[ $key ] ) && $form_data[ $key ] !== null ) {
        return $form_data[ $key ];
    }
    return get_option( 'myplugin_' . $key );
}

Keep the merge logic in one function called from every consumer. Otherwise inevitably one consumer reads only the form meta, another reads only the global, and they drift.

Critical rules

• Register the post meta on init, not earlier. The CPT must exist first.
• auth_callback MUST do a post-level capability check (user_can( $user_id, 'edit_post', $post_id )). The simpler current_user_can( 'edit_posts' ) is a security loosening — flag it in security review.
• sanitize_callback MUST validate the JSON shape, not just run wp_json_encode on whatever came in. Anyone with edit-post capability on a form can write any string to the REST endpoint; your sanitizer is the schema gate.
• Hook editor JS via 'jet-form-builder/editor-assets/before', not enqueue_block_editor_assets directly. Otherwise jet-fb-data may not be loaded yet when your bundle runs.
• Always declare jet-fb-data as a script dependency if you use useMetaState. Without it, window.JetFBHooks may be undefined at first render.
• Wrap JSON.parse in try/catch in the panel — corrupt meta must not crash the editor.
• Idempotency guard in the addFilter callback (plugins.some( p => p.base.name === ... )). Filter callbacks can fire multiple times during HMR / hot reloads.
• One JSON blob per feature, not many small meta keys.
• Fail silently if useMetaState is missing, don't render error UI inside the editor.

Common pitfalls (failure modes inferred from the API contract)

• Panel doesn't appear: check that the script is enqueued (Network tab), jet-fb-data is loaded before it (script order), and the filter name is exact ('jet.fb.register.plugins' — note dots).
• Values don't save: meta key not registered with show_in_rest, OR auth_callback returns false for the current user, OR sanitize_callback rejects the payload silently.
• Values save but don't reload: default is malformed JSON, so initial parse throws and the panel renders defaults each time.
• Panel renders, but useMetaState is undefined: missing jet-fb-data dependency, or JFB version doesn't expose window.JetFBHooks.
• REST returns 401/403 on save: capability check too strict (e.g. requiring manage_options for editors). Use edit_post against the specific form ID.
• Editor's "post is dirty" indicator never clears: you're calling setValue with a new object reference every render even when the data didn't change. Memoize or compare before writing.

Cross-references

• Run jfb-settings-tab when the user needs a site-wide settings tab in addition to (or instead of) per-form panels — it covers the global Vue/cx-vui Settings page.
• Run wp-security-audit on the PHP side before release — register_post_meta with REST exposure is a write endpoint that an audit must check (auth_callback strength, sanitize_callback completeness).
• Run wp-i18n-audit on both PHP and JS strings to verify text-domain consistency.

What this skill does NOT cover

• Adding new JFB form blocks (different subsystem — block.json, edit/save components).
• Adding JFB form actions (the "after submit do X" flow — Google Sheet plugin uses that, not this).
• Adding JFB preset providers (data sources for prefilling form fields).
• Customizing Gutenberg's main editor canvas, post status info, or pre-publish panel — those are standard Gutenberg slots accessed via registerPlugin from @wordpress/plugins, not through JFB's filter.
• Multi-form UI (settings that span multiple forms or aggregate across them).

References

• Form CPT registration: wp-content/plugins/jetformbuilder/modules/post-type/module.php
• Meta base class with reference auth_callback: wp-content/plugins/jetformbuilder/modules/post-type/meta/base-meta-type.php
• Editor asset enqueue trigger: wp-content/plugins/jetformbuilder/includes/admin/editor.php
• Real-world panel implementation: wp-content/plugins/media-storage-for-jetformbuilder/assets/js/form-editor.js and includes/Plugin.php
• WP component catalog: https://developer.wordpress.org/block-editor/reference-guides/components/
• register_post_meta reference: https://developer.wordpress.org/reference/functions/register_post_meta/
• Official documentation: https://github.com/Crocoblock/developer-documentation/tree/main/03-jet-form-builder