FlowLinks Developer Reference

FlowLinks follows a clean singleton-based architecture with a clear separation between admin and public concerns. All persistence goes through a single settings manager that caches results per-request for performance.

Core Principles

Load Order

The bootstrap file loads classes in dependency order: settings → renderer → admin → public. Admin and Public are instantiated on the plugins_loaded action.

FlowLinks_Settings

Central configuration manager. Handles defaults, fetching, sanitizing, and saving settings.

FlowLinks_Renderer

Fetches related posts and produces escaped HTML for both frontend and preview contexts.

FlowLinks_Admin

Registers the admin menu, enqueues assets, handles settings saving, and serves AJAX tab content.

FlowLinks_Public

Hooks into the_content, injects rendered blocks, and enqueues frontend assets. Dynamic CSS is attached to the enqueued stylesheet via the WordPress style API.

Settings are stored under the option key flowlinks_settings_internal. The public external-credit setting show_powered_by is controlled by an explicit, clearly labeled administrator switch and defaults to false. WordPress.org supplies locale translation files; the plugin does not bundle English self-translation files or manually load its text domain.

Query Strategy

FlowLinks uses WP_Query for all standard sorts and a raw $wpdb query for WooCommerce best-sellers (joining on _total_sales). Each target content type is queried separately, then results are interleaved to produce a balanced mix.

Interleaving Algorithm

// Simplified pseudo-code of get_related_posts_by_types()
$by_type = [];
foreach ( $post_types as $type ) {
    $rule = get_order_settings_for_type( $settings, $type );
    $by_type[$type] = get_related_posts( $source_id, $rule, [$type] );
}

// Interleave: take one from each type per round
$merged = [];
$offset = 0;
while ( count( $merged ) < $limit ) {
    foreach ( $post_types as $type ) {
        $post = $by_type[$type][$offset] ?? null;
        if ( $post && ! isset( $seen[$post->ID] ) ) {
            $merged[] = $post;
            $seen[$post->ID] = true;
        }
    }
    $offset++;
}

Column Auto-Fit

When display_style = 'card' and the number of rendered items is ≤ 6, the effective column count matches the item count. This guarantees all cards fit into a single row regardless of the configured columns setting.

Admin Menu

FlowLinks registers a single top-level menu with slug pixel-flowlinks and the dashicons-admin-links icon at position 60.

Lazy Tab Loading

Tab content is rendered via AJAX (flowlinks_load_tab) to keep initial page weight minimal. The active tab is determined server-side by FlowLinks_Settings::get_current_tab() and reflected in the URL ?tab= parameter.

Asset Loading Rules

Localized Data

flowlinks_admin_obj = {
    ajax_url: '/wp-admin/admin-ajax.php',
    preview_nonce: '<nonce>',
    tabs_nonce: '<nonce>',
    current_tab: 'internal'
};

flowlinks_load_tab

flowlinks_get_preview

Injection Hook

FlowLinks hooks the_content at priority 20. In singular views, FlowLinks_Public::inject_links_into_content() builds the effective content.

Paragraph Detection

// The frontend scans the original HTML structure.
$paragraph_ends = $this->find_paragraph_end_offsets( $content, $analysis_mode );

// Only real <p>...</p> elements are counted.
// Comments and raw-text/code areas are ignored.
// Elementor mode recognizes text-editor/widget wrappers; without one, it falls back to all real <p> elements.

Position Matching

The paragraph positions string (e.g. "2, 5, 9") is parsed into an integer array, deduplicated, sorted, and capped at 10 values. Each matching real HTML paragraph is located by its byte offset, then a block is rendered immediately after that paragraph without reserializing the original content.

LTR Enforcement

Every text-bearing element is emitted with inline direction:ltr !important;text-align:left !important. This guarantees correct alignment even on RTL-themed sites that aggressively override styles.

Registered Actions

Suggested Future Filters

// Filter the final rendered HTML block
$html = apply_filters( 'flowlinks/rendered_block', $html, $posts, $settings );

// Filter the related posts before rendering
$posts = apply_filters( 'flowlinks/related_posts', $posts, $source_id, $settings );

// Filter paragraph positions
$positions = apply_filters( 'flowlinks/paragraph_positions', $positions, $post_id );

Nonce Verification

All form submissions are protected by wp_nonce_field( 'flowlinks_save_settings', 'flowlinks_save_settings_nonce' ). AJAX handlers call check_ajax_referer() with the relevant nonce action.

Capability Checks

Every mutating action requires current_user_can( 'manage_options' ). The menu itself is registered with the same capability.

Input Sanitization

Output Escaping

All HTML output goes through esc_html(), esc_attr(), or esc_url(). No raw user input is ever echoed.

SQL Safety

The single raw SQL query (WooCommerce best-sellers) uses $wpdb->prepare() with placeholder arrays. All other queries use WP_Query.

Recipe 1 — Add a Custom Post Type to the Matrix

// Register a CPT, then extend the matrix on save
add_filter( 'flowlinks/supported_post_types', function( $types ) {
    $types[] = 'recipe';
    return $types;
} );

Recipe 2 — Add a Custom Sort Method

add_filter( 'flowlinks/allowed_order_by', function( $allowed ) {
    $allowed[] = 'menu_order';
    return $allowed;
} );

add_filter( 'flowlinks/related_posts', function( $posts, $source_id, $settings ) {
    if ( $settings['order_by'] === 'menu_order' ) {
        usort( $posts, fn($a,$b) => $a->menu_order <=> $b->menu_order );
    }
    return $posts;
}, 10, 3 );

Recipe 3 — Add Custom CSS Variable

add_filter( 'flowlinks/style_vars', function( $vars, $settings ) {
    $vars[] = '--lf-custom-shadow: 0 4px 12px rgba(0,0,0,.08)';
    return $vars;
}, 10, 2 );

Recipe 4 — Replace Default Item Template

add_filter( 'flowlinks/item_html', function( $html, $post, $settings ) {
    return '<article class="custom-item">' . esc_html( $post->post_title ) . '</article>';
}, 10, 3 );