Custom Connector Reference

Last updated: August 2026

A Custom connector lets you write your own PHP logic to feed a Swiffle Grid block — a live API call, a database query, or a fully embedded dataset. It’s the same mechanism used internally by the built-in WordPress, WooCommerce, Google Sheets, CSV, and RSS sources, just exposed for your own code.

1. Package structure and registration

A Custom connector is a standalone WordPress plugin, installed the same way as any other plugin — via Plugins → Add New → Upload Plugin. It never runs inside Swiffle Grid’s own settings screen; it simply announces itself to Swiffle Grid through a filter hook, so Swiffle Grid knows it exists and how to call it.

Your plugin’s main file needs three things: a standard plugin header, an ABSPATH guard, and a registration block:

<?php
/*
Plugin Name: My Connector
Requires Plugins: swiffle-grid-embed-data-anywhere
*/

if ( ! defined( 'ABSPATH' ) ) exit;

add_action( 'plugins_loaded', function () {

    add_filter( 'swiffle_grid_register_connector', function ( $connectors ) {
        $connectors['swg_connector_myslug'] = [
            'label'           => __( 'My Connector', 'my-connector' ),
            'get_data'        => 'swiffle_custom_myslug_get_data',
            'get_filter_form' => 'swiffle_custom_myslug_get_filter_form', // optional
        ];
        return $connectors;
    } );

} );

Once your plugin is active, its slug (myslug in the example above — without the swg_connector_ prefix) appears automatically in the «Source» dropdown of every Swiffle Grid block set to Custom, and the connector is listed under Swiffle Grid in the WordPress admin sidebar for reference. There is nothing to import, edit, or delete from within Swiffle Grid itself — manage the connector the same way you’d manage any other plugin, under Plugins → Installed Plugins.

2. The data function

function swiffle_custom_{slug}_get_data($pagesize, $strl, $parameters) {
    // ... your logic here ...
    return [$posts, $have_more, $css, $script];
}

Parameters

Filter values

Any field in your filter form with name="FILTR_xxx" arrives as $parameters['xxx'] — the FILTR_ prefix is stripped automatically. For example, name="FILTR_year" maps to $parameters['year'].

Block parameters — $parameters['swiffle_grid']

All block settings configured in Gutenberg or Elementor are available as a nested array under $parameters['swiffle_grid']. Most parameters exist in a desktop variant and a phone variant (key ending in p); your connector can use whichever is relevant to its logic.

3. Return value

The function must return a 4-element indexed array:

return [$posts, $have_more, $css, $script];

$posts — two supported formats

A. Tabular / auto-rendered mode

The first element of $posts is a header row containing column names; every subsequent element is a data row with values in the same order. Swiffle Grid reads the column names and auto-generates the matching card element based on recognised prefixes:

Example — tabular mode:

$posts = [
    ['TIT_Title', 'IMG_Photo', 'OTHER_Description'],  // header row
    ['Grand Canyon',  'https://example.com/grand_canyon.jpg',  'A vast canyon in Arizona.'],
    ['Mount Fuji',    'https://example.com/mount_fuji.jpg',    'Japan's iconic volcano.'],
];

B. Full custom HTML mode

When you need full control over the card layout, each element of $posts is an associative array with three keys:

$posts[] = [
    'front'  => '<div class="my-card">...</div>',  // HTML for the card's front face
    'back'   => '<div class="my-back">...</div>',   // HTML for the card's back face (shown on flip)
    'navurl' => 'https://example.com/page',           // destination URL; empty string if unused
];

$have_more

String 'y' or 'n'. Tells the block whether a next page of results exists. Set it to 'y' when more records are available beyond the current page, 'n' when the current page is the last one.

$css

A string of CSS, injected directly into the block’s own rendering scope. Because Swiffle Grid renders as a <swiffle-grid> custom element using a Shadow DOM, page-level theme CSS does not reach inside it. Every class and style your connector’s HTML relies on must be returned here.

$css = <<<CSS
    .my-card { background:#0f172a; color:#e5e7eb; border-radius:16px; }
    .my-card h3 { margin:0; font-size:18px; }
CSS;

$script

A JavaScript string executed after the block has finished rendering its HTML for the current page. Use it to wire up client-side behaviour that depends on the rendered card DOM (event listeners, third-party widget initialisation, etc.). It runs once per page load (i.e. once per pagination step).

$script = <<<SCRIPT
    document.querySelectorAll('.my-card').forEach(card => {
        card.addEventListener('click', () => console.log('Card clicked'));
    });
SCRIPT;

4. The filter form function

function swiffle_custom_{slug}_get_filter_form() {
    // ...
    return $html . "n<!--SWIFFLE_SCRIPT-->n" . $js;
}

Returns a single string: the filter form’s HTML, followed by the literal separator <!--SWIFFLE_SCRIPT-->, followed by JavaScript that runs once the form is in the page. The function does not return a CSS value — all CSS for the filter form must be included inline in the HTML string itself (via a <style> tag or inline style attributes).

• Every input that should act as a filter must use name="FILTR_xxx". The FILTR_ prefix is stripped and the remainder becomes the key in $parameters.
• The JavaScript portion runs in the page context, not inside the Shadow DOM. To reach inside the block, use the standard pattern:

const getSwiffleBlock = () => {
    for (const sg of document.querySelectorAll('swiffle-grid')) {
        if (sg.shadowRoot?.querySelector('.fltfrm')) return sg;
    }
    return null;
};
const block = getSwiffleBlock();

Minimal example:

function swiffle_custom_myplugin_get_filter_form() {
    $html = <<<HTML
        <div class="form_control">
            <div class="form_control_container">
                <label for="my_year">Year</label>
                <input type="number" id="my_year" name="FILTR_year" min="2000" max="2030" placeholder="E.g.: 2024">
            </div>
        </div>
HTML;

    $js = <<<JS
        (() => {
            const block = (() => {
                for (const sg of document.querySelectorAll('swiffle-grid')) {
                    if (sg.shadowRoot?.querySelector('.fltfrm')) return sg;
                }
            })();
            if (!block) return;
            // Add behaviour here if needed.
        })();
JS;

    return $html . "n<!--SWIFFLE_SCRIPT-->n" . $js;
}

5. Pagination patterns

The recommended approach is to request $pagesize + 1 records from your data source, then check whether that extra record exists to set $have_more, and remove it before returning the slice. This avoids a separate count query and works with any data source.

$limit  = intval($pagesize) + 1;           // fetch one extra
$offset = max(0, intval($strl));

// ... fetch $limit records from offset $offset ...

if (count($data) === $limit) {
    $have_more = 'y';
    array_pop($data);                      // remove the extra record
} else {
    $have_more = 'n';
}

$posts = [['TIT_Title', 'IMG_Photo']];    // header row
foreach ($data as $row) {
    $posts[] = [$row['title'], $row['image']];
}

You are free to use a different method — the only constraint is that $have_more must accurately reflect whether more pages exist. A separate count query, a date-window calculation, or any other logic that correctly sets this value is equally valid.

6. Practical recommendations

• Use wp_remote_get(), not file_get_contents() — some hosts disable the allow_url_fopen PHP setting. wp_remote_get() uses cURL when available, returns a real HTTP status code, and gives you a WP_Error object to check on failure instead of a silent false.
• Set an explicit user-agent header — some external APIs return 403 Forbidden to requests with an empty or generic user agent. A descriptive user agent also helps API owners identify legitimate traffic.
• Cache responses for unreliable APIs — use set_transient($key, $data, HOUR_IN_SECONDS) for a short-lived cache, and update_option($key, $data, false) for a durable fallback. On a transient miss, try the API; if the API fails, fall back to the last stored option. This ensures your grid stays visible even during brief outages.
• Never hardcode credentials — store API keys and secrets via register_setting() and get_option() on your own settings page (see section 1), never as a literal string or a define() in your plugin file.
• Escape all output — use htmlspecialchars() for plain text, esc_attr() for HTML attribute values, esc_html() for inline text content, and esc_url() for URLs.
• Handle empty results gracefully — always return a valid 4-element array, even when there is no data: return [[], 'n', '', ''];