Layout System

The Jankx Layout System provides a powerful, flexible way to manage dynamic layouts for your WordPress theme.

Overview

┌─────────────────────────────────────────┐
│         Layout Registry                 │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐  │
│  │  Grid   │ │  List   │ │Carousel │  │
│  │ Layout  │ │ Layout  │ │ Layout  │  │
│  └────┬────┘ └────┬────┘ └────┬────┘  │
│       └────────────┴────────────┘       │
│              BlockTemplate              │
└─────────────────────────────────────────┘

Layout Registry

The LayoutRegistry manages all registered layouts and provides dependency injection support:

use Jankx\Layouts\DynamicDataLayout\LayoutRegistry;
use Jankx\Foundation\Application;

$app = Application::getInstance();
$registry = new LayoutRegistry($app);

// Register a layout
$registry->register('grid', GridLayout::class);

// Check if layout exists
if ($registry->has('grid')) {
    $layout = $registry->resolve('grid', ['columns' => 3]);
}

Methods

Available Layouts

Grid Layout

use Jankx\Layouts\DynamicDataLayout\BlockLayouts\GridLayout;

$layout = new GridLayout();
$layout->setOptions([
    'columns' => 3,
    'gap' => 20,
    'class_name' => 'my-grid',
]);

echo $layout->render($data);

Options:

• columns (int): Number of columns (1-12)
• gap (int): Gap between items in pixels
• responsive (bool): Enable responsive behavior
• class_name (string): CSS class name

List Layout

use Jankx\Layouts\DynamicDataLayout\BlockLayouts\ListLayout;

$layout = new ListLayout();
$layout->setOptions([
    'style' => 'vertical',
    'class_name' => 'my-list',
]);

Options:

• style (string): 'vertical' | 'horizontal'
• class_name (string): CSS class name

Carousel Layout PRO

use Jankx\Layouts\DynamicDataLayout\BlockLayouts\CarouselLayout;

$layout = new CarouselLayout();
$layout->setOptions([
    'slides_per_view' => 3,
    'autoplay' => true,
    'navigation' => true,
]);

Options:

• slides_per_view (int): Number of visible slides
• autoplay (bool): Enable autoplay
• navigation (bool): Show navigation arrows
• pagination (bool): Show pagination dots

Creating Custom Layouts

Step 1: Create Layout Class

<?php
// includes/MyTheme/Layouts/CustomLayout.php

namespace MyTheme\Layouts;

use Jankx\Layouts\DynamicDataLayout\BlockTemplateLayout;

class MasonryLayout extends BlockTemplateLayout
{
    protected $defaultOptions = [
        'columns' => 3,
        'gap' => 15,
        'class_name' => 'masonry-layout',
    ];

    public function getHtmlStructure(): string
    {
        return '<div class="{{class_name}} masonry-grid">
            {{#items}}
                <div class="masonry-item" style="margin-bottom: {{gap}}px;">
                    {{content}}
                </div>
            {{/items}}
        </div>';
    }
}

Step 2: Register Layout

// functions.php or service provider

use Jankx\Layouts\DynamicDataLayout\LayoutRegistry;
use MyTheme\Layouts\MasonryLayout;

add_action('jankx/layouts/register', function(LayoutRegistry $registry) {
    $registry->register('masonry', MasonryLayout::class);
});

Usage Examples

Dynamic Data Block

use Jankx\Gutenberg\Blocks\DynamicDataLayoutBlock;

class MyCustomBlock extends DynamicDataLayoutBlock
{
    public function render($attributes, $content)
    {
        $layoutName = $attributes['layout'] ?? 'grid';
        $layout = LayoutRegistry::getInstance()->resolve($layoutName, [
            'columns' => $attributes['columns'] ?? 3,
        ]);

        $data = $this->fetchData($attributes);
        return $layout->render($data);
    }
}

Template Integration

// In your template file
$layout = LayoutRegistry::getInstance()->resolve('list', [
    'style' => 'vertical',
    'class_name' => 'post-list',
]);

$query = new WP_Query(['posts_per_page' => 10]);
$items = [];

while ($query->have_posts()) {
    $query->the_post();
    $items[] = [
        'title' => get_the_title(),
        'content' => get_the_excerpt(),
        'link' => get_permalink(),
    ];
}

echo $layout->render(['items' => $items]);

Best Practices

1. Always use LayoutRegistry: Don't instantiate layouts directly, use the registry for proper DI
2. Validate options: Use setOptions() with type checking
3. Cache renders: For expensive layouts, consider caching the output
4. Responsive design: Use the built-in responsive options
5. Accessibility: Include ARIA labels and proper semantic HTML

← Back to Documentation