Modules and heros in WP

Modules and heros in WordPress

To make dynamically set-up pages we use what we call modules and heros. These are reusable components that the web admin can place at any page they create. This makes it easier for them to customise their website and add or take out components from any of their pages.

On our side, we have two key elements to make this work: ACF and our code. With the help of the design and front-end teams, we will set up a series of modular components that will fall into one of these two categories and will be controlled via ACF in the WP-admin dashboard.

1. Set up in ACF

We typically create two sections (Flexible modules and Flexible heros) and use the ‘Flexible Content’ field type in them, so we can create all of our layouts inside each of them. That will look something like this:

Each module here will have its own custom fields, that will range from writing the title or the description to controlling the spacings between that module and the ones around it, changing its background color or font size… Anything we need to personalize the module will be contained inside its ACF fields.

2. Receive the information in the code

We have a page-modules.php file where we will receive all modules and heros from the backend using ACF’s get_field() function and a simple loop:

/*
Template Name: Modules
*/
?>
<?php get_header() ?>


<?php $heros = get_field('heros');
if ($heros) {
    foreach ($heros as $keyIndexHero => $hero):
       include(locate_template('flexible/hero/index.php', false, false));
    endforeach;
} ?>

<?php $modules = get_field('modules');
if ($modules) {
    foreach ($modules as $keyIndexModule => $module):
       include(locate_template('flexible/module/index.php', false, false));
    endforeach;
} ?>

<?php get_footer()

Each of these loops makes an include of an index that contains all modules and includes the templates for each of the modules that are received from the ACF:

switch ($module['acf_fc_layout']) {
    case 'short_banner':
        include(locate_template('flexible/module/short-banner.php', false, false));
        break;
    case 'small_heading_paragraph_button':
        include(locate_template('flexible/module/small-heading-paragraph-button.php', false, false));
        break;
    case 'slider':
        include(locate_template('flexible/module/slider.php', false, false));
        break;
}

3. Defining variables in modules

As you can see, we are working with ìnclude to introduce the templates we want. What this essentially does is paste all the code inside that file on the line of the include, so we have to imagine that every module or hero we include is just pasting that PHP code below the code we already had, creating a big, continuous file with all of the heros and modules included in it below one another.

This could get to some issues where variables exist where they should not or get accidentally replaced, so we need to be careful when setting and unsetting them so they do not affect the modules we are not working on.

This is especially true for variables that we use in almost every module, such as $customClass, $spacing or $backgroundColor. These are the variables that will be receiving the formatting information from the ACF and, as such, will be present in many of our files.

For instance, if the background color of a module is set to be either white or green and white would be the default way the file is styled, if the admin chooses green, we could apply a $customClass = --second to the module so the styling changes accordingly. This would be done in accord with the front-end team, who will provide all necessary classes to apply to each module in each of its variants.

This would be an example of a block of variable declarations containing several conditionals:

<?php
$backgroundColor = $hero['background_color'];
if($backgroundColor === 'sand') {
    $customClass = 'c--hero-b--background-second';
}
$title = $hero['title'];
$titleFontSize = $hero['font_size'];
if($titleFontSize === 'small') {
    $customClass = $customClass . ' c--hero-b--font-second';
}
$subtitle = $hero['subtitle'];
$includeButton = $hero['include_button'];
if($includeButton) {
    $button = $hero['button'];
}
?>

These would later translate to the component file like this:

<section class="c--hero-b <?php if($customClass) echo $customClass; ?>">

For neatness and consistency purposes, in our module files we will always have a variable declarations block at the very top and a variable unsets block at the very bottom, so we can ensure that every variable used by that module is contained within it and does not affect any others that can be placed in the same page.

<?php
$backgroundColor = $hero['background_color'];
if($backgroundColor === 'sand') {
    $customClass = 'c--hero-b--background-second';
}
$title = $hero['title'];
$titleFontSize = $hero['font_size'];
if($titleFontSize === 'small') {
    $customClass = $customClass . ' c--hero-b--font-second';
}
$subtitle = $hero['subtitle'];
$includeButton = $hero['include_button'];
if($includeButton) {
    $button = $hero['button'];
}

?>

<?php include(locate_template('components/hero/hero-b.php', false, false)); ?>

<?php
unset($backgroundColor);
unset($title);
unset($titleFontSize);
unset($subtitle);
unset($includeButton);
unset($button);
unset($customClass);
?>