Sections

Sections have two things to setup:

• Definition inc/sections/section-id.php

  This is where you register the section and define the data structure (meta inputs).

• Template template/sections/section-id.php

  This is the "frontend", it's where you render the section, the html (php).

Everything else is behind the scenes and configurable via Wordpress actions and filters.

Prerequisites

• fx-classes >= v3.2.5

If you're upgrading a site that uses the 'legacy' sections system. You will have to disable the new sections to avoid breaking changes. See how here.

Quick Start

Blank will include an example section, so you can copy the definition and template:

• Definition - inc/sections/section-id.php
• Template - template/sections/section-id.php

Change the name and id of the section in each file.

Make sure you require the definition inside inc/fx-sections.php.

The rest is handled by the section loop (templates/sections/loop.php).

Definition

Register a section with fx_register_section(id: string, args: Object, merge_options?: Object).

See example below for args explanation:

fx_register_section('id', [
    'title' => 'Title for the section',
    'template' => 'sections/section-id', // This file needs to exist inside templates
    'global' => false, // Can this section be used to make global sections
    'page' => true, // Can this section be created at a page level
    'inputs' => [
        'case_study' => [
            'type' => 'select',
            'options' => 'case_study',
            'title' => 'Select Case Study',
            'exclude_post_type' => true,
        ],
    ],
]);

Template

You can build your template however you want.

Section data is available on the global $section variable.

Example

Definition

// inc/sections/section-simple.php
fx_register_section('simple', [
    'title' => 'Simple Section',
    'template' => 'sections/section-simple',
    'global' => false,
    'page' => true,
    'inputs' => [
        'title' => [
            'type' => 'textfield',
            'title' => 'Title',
        ],
    ],
]);

Template

// templates/sections/section-simple.php
global $section;
$title = $section['title'];

<section class="section">
    <h1><?php echo $title; ?></h1>
</section>

Advanced

Page Templates

By default, Blank will enable sections on the page-sectioned template. You can change this using the fx_section_page_templates filter.

add_filter('fx_section_page_templates', 'fx_register_section_page_templates', 10, 1);

function fx_register_section_page_templates() {
    // Use sections on other page templates as well
    return ['page-sectioned', 'page-other-template'];
}

Once you have registered your page template for sections, use the section loop (templates/sections/loop.php) to render the sections.

Example:

// templates/page-other-template.php
get_header();

if (have_posts()) :
    while (have_posts()) : the_post();

    // Call page content, if there is any?
    the_content();

    // Now the sections
    get_template_part('sections/loop');

    endwhile;
endif;

get_footer();

Note: The sections loop needs to be called inside the post loop, as it relies on the global $post.

Override Existing Sections

When registering a section you have the ability to control how it handles conflicts, i.e. already existing sections. This is useful if you want to override existing sections, for example, the template.

To do so, specify strategy option to the merge_options when calling fx_register_section.

If no strategy is defined, it will default to merge.

Assume the following section has already been registered like so:

fx_register_section('id', [
    'title' => 'Title for the section',
    'template' => 'sections/section-id',
    'inputs' => [
        'title' => [
            'type' => 'textfield',
            'title' => 'My Title',
        ],
    ],
]);

merge

This will merge the new and existing arguments shallowly. This is useful for replacing a single value. If you pass inputs it will replace all of the old inputs, if you want to merge inputs use the merge-deep option.

Example:

fx_register_section('id', [
    'title' => 'New title for the section',
    'inputs' => [
        'description' => [
            'type' => 'textarea',
            'title' => 'My Description',
        ],
    ],
], [
    'strategy' => 'merge',
]);

// Result
[
    'title' => 'New title for the section',
    'template' => 'sections/section-id',
    'inputs' => [
        'description' => [
            'type' => 'textarea',
            'title' => 'My Description',
        ],
    ],
]

merge-deep

This will merge the new and existing arguments recursively. This is useful for updating values inside inputs.

fx_register_section('id', [
    'title' => 'New title for the section',
    'inputs' => [
        'title' => [
            'title' => 'My New Title',
        ],
        'description' => [
            'type' => 'textarea',
            'title' => 'My Description',
        ],
    ],
], [
    'strategy' => 'merge-deep',
]);

// Result
[
    'title' => 'New title for the section',
    'template' => 'sections/section-id',
    'inputs' => [
        'title' => [
            'type' => 'textfield',
            'title' => 'My New Title',
        ],
        'description' => [
            'type' => 'textarea',
            'title' => 'My Description',
        ],
    ],
]

replace

This will replace the old arguments.

Example:

fx_register_section('id', [
    'title' => 'New title for the section',
    'inputs' => [
        'description' => [
            'type' => 'textarea',
            'title' => 'My Description',
        ],
    ],
], [
    'strategy' => 'replace',
]);

// Result
[
    'title' => 'New title for the section',
    // No template was provided in the new arguments, so this is technically broken...
    'template' => '',
    'inputs' => [
        'description' => [
            'type' => 'textarea',
            'title' => 'My Description',
        ],
    ],
]

Disable Sections

You can disable sections all together using the fx_sections_enabled filter.

add_filter('fx_sections_enabled', function() {
    return false;
}, 10, 1);