je-query-builder-custom-type

JetEngine Query Builder custom type

Build a saved-query type as two coordinated components: a runtime query and an admin editor. Keep the runtime authoritative; editor controls, REST inputs, filters, and MCP-created settings are all untrusted input to that runtime.

When to use this skill

• Expose a custom table, service, or repository to Query Builder/Listings.
• Add query-type-specific editor controls.
• Diagnose abstract-class fatals after a JetEngine upgrade.
• Fix dynamic arguments, filters, cache, count, or pagination behavior.
• Make a custom type intentionally usable from saved-query REST or MCP tooling.

Architecture and registration

Use the same vendor-prefixed slug in both registrations.

add_action(
    'jet-engine/query-builder/queries/register',
    static function($factory): void {
        require_once __DIR__ . '/src/class-my-plugin-query.php';
        $factory::register_query('my-plugin-records', My_Plugin_Query::class);
    }
);

add_action(
    'jet-engine/query-builder/query-editor/register',
    static function($editor): void {
        require_once __DIR__ . '/src/class-my-plugin-query-editor.php';
        $editor->register_type(new My_Plugin_Query_Editor());
    }
);

The runtime base has six required methods in 3.8.14:

_get_items()
get_items_total_count()
get_items_page_count()
get_items_pages_count()
get_current_items_page()
set_filtered_prop($prop = '', $value = null)

Omitting set_filtered_prop() leaves the subclass abstract and causes a fatal when JetEngine instantiates it.

Runtime skeleton

use Jet_Engine\Query_Builder\Queries\Base_Query;

final class My_Plugin_Query extends Base_Query {
    private function args(): array {
        $this->setup_query();
        $args = $this->get_query_args();

        return array(
            'status'   => sanitize_key($args['status'] ?? 'active'),
            'page'     => max(1, absint($args['page'] ?? 1)),
            'per_page' => min(100, max(1, absint($args['per_page'] ?? 20))),
        );
    }

    public function _get_items() {
        return my_plugin_repository()->find($this->args());
    }

    public function get_items_total_count() {
        $cached = $this->get_cached_data('count');
        if (false !== $cached) {
            return (int) $cached;
        }

        $count = (int) my_plugin_repository()->count($this->args());
        $this->update_query_cache($count, 'count');
        return $count;
    }

    public function get_items_per_page() {
        return $this->args()['per_page'];
    }

    public function get_current_items_page() {
        return $this->args()['page'];
    }

    public function get_items_pages_count() {
        return max(1, (int) ceil(
            $this->get_items_total_count() / $this->get_items_per_page()
        ));
    }

    public function get_items_page_count() {
        return count($this->get_items());
    }

    public function set_filtered_prop($prop = '', $value = null) {
        if ('_page' === $prop) {
            $this->final_query['page'] = max(1, absint($value));
            return;
        }

        $this->merge_default_props($prop, $value);
    }
}