Building extensible display options with Selectable Option fields

[MoritzLost]

This will be more of a quick tip, and maybe obvious to many of you, but it's a technique I found very useful when building display options. By display options I mean fields that control how parts of the page are displayed on the frontend, for example background colors, sizing, spacing and alignment of certain elements. I'll also touch on how to make those options intuitive and comfortable to use for clients.

It basically involves setting up option values that can be used directly in CSS classes or as HTML elements and mapping those to CSS styling (which can be quickly generated in a couple of lines using a pre-processor such as SASS). Another important aspect is to keep the option values seperate from their corresponding labels; the former can be technical, the latter should be semantically meaningful. The field type that lends itself to this this seperation of concerns is the Selectable Options field, the following examples mostly use this field type. Note that this module is part of the ProcessWire core, but not installed by default.

The following examples all come from real projects I built (though some are slightly modified to better demonstrate the principle).

#1: Headline levels & semantics

For a project that had many pages with long texts, I used a Repeater field to represent sections of text. Each section has a headline. Those sections may have a hierarchical order, so I used a Selectable Option field to allow setting the headline level for each section (you can guess where this is going). The definition of the options looks something like this (those are all in the format value|label, with each line representing one option, see the blogpost above for details):

h2|Section headline
h3|Sub-section headline

Of course, the PHP code that generates the corresponding HTML can use those values :

// "sections" is the repeater field
foreach ($page->sections as $section) {
    // create an h2 / h3 tag depending on the selected option (called headline_level here)
    echo "<{$section->headline_level->value}>{$section->headline}</{$section->headline_level->value}>";
    echo $section->body;
}

That's a pretty obvious example, but there are two important takeaways:

• I only used two options. Just because there are six levels of headlines in HTML, doesn't mean those are all relevant to the client. The less options there are, the easier it is to understand them, so only the options that are relevant should be provided. In this case, the client had provided detailed, structured documents containing his articles, so I could determine how many levels of hierarchy were actually needed. I also started at h2, since there should be only one h1 per page, so that became it's own field separate from the repeater.
• The two options have a label that is semantically relevant to the client. It's much easier for a client who doesn't know anything about HTML to understand the options "Section headline" and "Sub-section headline" than "h2" and "h3". Sure, it can be cleared up in the field description, but this way it goes from something that's quickly explained to something that needs no explanation at all.

#2: Image width and SASS

In the same project, there was also an image section; in our layout, some images spanned the entire width of the text body, others only half of it. So again, I created an options field:

50|Half width
100|Full width

In this case, I expected the client to request different sizes at some point, so I wanted it to be extensible. Of course, the values could be used to generate inline styles, but that's not a very clean solution (since inline styled break the cascade, and it's not semantic as HTML should be). Instead, I used it to create a class (admittedly, this isn't strictly semantic as well):

<img src="..." class="w-<?= $section->image_width->value ?>"> 

With pure CSS, the amount of code needed to write out those class definitions will increase linearly with the number of options. In SASS however, you only need a couple of lines:

@each $width in (50, 100) {
    .w-#{$width}{
        max-width: percentage($width/100);
    }
}

This way, if you ever need to add other options like 25% or 75%, you only need to add those numbers to the list in parenthesis and you're done. You can even put the definition of the list in a variable that's defined in a central variables.scss file. Something like this also exists in Bootstrap 4 as a utility, by the way.

It also becomes easier to modifiy those all at once. For example, if you decide all images should be full-width on mobile, you only need to add that once, no need to throw around !important's or modify multiple CSS definitions (this is also where the inline styles approach would break down) :

# _variables.scss
$image-widths: (25, 50, 75, 100);
$breakpoint-mobile: 576px;

# _images.scss
@import "variables";
@each $width in $image-widths {
    .w-#{$width}{
        max-width: percentage($width/100);
        @media (max-width: $breakpoint-mobile) {
            max-width: 100%;
        }
    }
}

One important gotcha: It might be tempting to just use an integer field with allowed values between 10 - 100. In fact, the amount of SASS code would be identical with a @for-directive to loop throuh the numbers. But that's exactly what makes point-and-click page builders so terrible for clients: too many options. No client wants to manually set numerical values for size, position and margins for each and every element (looking at you, Visual Composer). In fact, having too many options makes it much harder to create a consistent layout. So in those cases, less is more.

#3: Multiple options in one field

Another example for repeatable page sections, this time for a two-column layout. The design included multiple variants regarding column-span and alignment. Using a 12-column grid, we needed a 6-6 split, a centered 5-5 split, a left-aligned 6-4 split and a right-aligned 4-6 split. I didn't want to litter the repeater items with options, so I decided to put both settings in one field (called something like Column layout) :

center_6_6|6 / 6 (Centered)
center_5_5|5 / 5 (Centered)
left_6_4|6 / 4 (Left-aligned)
right_4_6|4 / 6 (Right-aligned)

As long as the value format is consistent, the individual options can be quickly extracted and applied in PHP:

[$alignment, $width['left'], $width['right']] = explode('_', $section->column_layout->value);
echo '<section class="row justify-content-' . $alignment . '">';
foreach (['left', 'right'] as $side) {
    echo '<div class="col-lg-' . $width[$side] . '">';
    echo $section->get("body_{$side}");
    echo '</div>';
}
echo '</section>';

If you don't recognize the syntax in the first line, it's symmetric array destructuring, introduced in PHP 7.1. For older versions you can use list() instead. This example uses Bootstrap 4 grid classes and flexbox utility classes for alignment. The corresponding CSS can be quickly generated in SASS as well, check the Bootstrap source code for a pointer.

Again, I'm limiting the options to what is actually needed, while keeping it extensible. With this format, I can easily add other column layouts without having to touch the code at all.

#4: Sorting page elements

A final example. In this case I was working on a template for reference projects that had three main content sections in the frontend: A project description, an image gallery and embedded videos (each using their own set of fields). The client requested an option to change the order in which those sections appeared on the page. Had I known this earlier, I maybe would have gone for a Repeater Matrix approach once again, but that would have required restructuring all the fields (and the corresponding code), so instead I used a Selectable Option field (labelled "Display order"). My approach is similar to the one from the last example:

body_gallery_embeds|Description - Gallery - Videos
body_embeds_gallery|Description - Videos - Gallery
gallery_body_embeds|Gallery - Description - Videos
gallery_embeds_body|Gallery - Videos - Description
embeds_body_gallery|Videos - Description - Gallery
embeds_gallery_body|Videos - Gallery - Description

Since there are six possibilities to sort three items, this is the expected number of options. So I decided to include them all, even though some are probably never going to be used. I also tried to use a predictable order for the options (i.e. the options come in pairs, depending on what element is first). And here is the code used on the frontend:

// render the template files for each section and store the result in an associative array
$contents = [
    'body' => wireRenderFile('partials/_section-body.php', $page),
    'gallery' => wireRenderFile('partials/_section-gallery.php', $page),
    'embeds' => wireRenderFile('partials/_section-embeds.php', $page),
];

// e.g. 'gallery_body_embeds' => ['gallery', 'body', 'embeds'];
$order = explode('_', $page->display_order->value);

// echo the contents in the order defined by the option value
foreach ($order as $item) {
   echo $contents[$item];
}

You can see how it will be easy to add an additional section and integrate it into the existing solution. Though a fourth item would result in 4! = 24 possibilities to sort them, so at that point I'd talk to my client about which layouts they actually need ?

Conclusion

I always try to keep my code and the interfaces I create with ProcessWire extensible and intuitive. Those are a couple of solutions I came up with for projects at work. They are certainly not the only approach, and there is nothing super special about those examples, but I found that putting a little more effort into defining options with meaningful labels and using option values that I can use directly in my templates makes the result less verbose and more maintainable. Some or most of this tutorial may be immediately obvious to you, but if you made it this far, hopefully you got something out of it ?

Feel free to share your own methods to create display options, or how you would've approached those problems differently. Thanks for reading!

[kongondo]

As always, excellent write-up! Clear and concise ?. If I had the money and you had the time and interest, I'd pay you to write many more ProcessWire tutorials ?.

[MoritzLost]

22 hours ago, kongondo said:

As always, excellent write-up! Clear and concise ?. If I had the money and you had the time and interest, I'd pay you to write many more ProcessWire tutorials ?.

Thanks ^^ I enjoy writing tutorials, I find it helps to consolidate the experience from my projects into organized knowledge. Most of the time I come across some areas where I'm not sure how something works, so I can look it up and further my own understanding (it's also great to improve my English as a non-native speaker). I think writing this stuff down helps bring out the core ideas or the important takeaways; before I started writing this one, I hadn't really considered the part about semantic/intuitive options, I mostly realized during writing that this was the crux of the matter. So  yeah, I write for my own benefit as much as everyone else's ?

[horst]

Hi Moritz,

big thanks for this one too! ?

I use a similar setup, but with page references instead of option fields.

[MoritzLost]

@horst That looks interesting as well! Of course with pages it's easier to maintain, and clients can their own options. I usually only use pages for larger structures such as taxonomies, and Selectable Options for simpler display options, since it's a bit faster to set up. Maybe I'll try a "pure" setup with only pages for options next time ^^ Hm, this opens up some possibilities, something like creating setting groups or presets containing multiple other options .. I'll definitely play around with that one ?

[horst]

16 hours ago, MoritzLost said:

Maybe I'll try a "pure" setup with only pages for options next time ^^ Hm, this opens up some possibilities

Definetly worth a try! ?

[psy]

@MoritzLost Great tutorial

I often use Repeater Matrix field with an added Fieldset Page containing the styling options for that section. FS page means it's easy to add a single field to different templates. Like you, I only give the client what options they need rather than the complete set. In the example below, the HTML theme is Canvas which is based on Bootstrap.

[Robin S]

On 1/17/2019 at 8:54 AM, MoritzLost said:

and Selectable Options for simpler display options, since it's a bit faster to set up

Check out Adrian's Page Field Select Creator if you haven't already. It makes setting up Page Reference fields just as fast as setting up Options fields.