Tips for creating reusable settings

[FireWire]

Hey there! I posted this before I took advantage of a feature in RockPageBuilder to manage globally sharable settings for blocks in RPB. @bernhard has since added some very nice features that make my tips below a little out of date. I recommend viewing his comment below and taking advantage of RPB's new native solution. Thanks to Bernhard for his ongoing work of making RPB event better for developers and users 👏

----------

Sharing a strategy that I have found useful when working with blocks and block settings.

I use the block settings feature heavily and in many instances most blocks have some of the same settings fields. To help make managing these easier, I created a workflow to help me manage these and it's saved me a good amount of time while being able to reuse settings between projects very easily. In my case, some of these are:

• Spacing between blocks/sections on the page
• Background/accent colors
• Content location within blocks
• Block presentation

My approach is to create a dedicated class with static methods that return a settings array. Example:

<?php
// /site/init.php

/**
 *  This creates a namespace for a /site/templates/RockPageBuilderSupport directory
 */
wire('classLoader')->addNamespace('RockPageBuilderSupport', __DIR__ . '/templates/RockPageBuilderSupport');

This file contains the fast helper methods that create settings fields

<?php

// /site/templates/RockPgeBuilderSupport/BlockSettings.php

namespace RockPageBuilderSupport;

use ProcessWire\RockFieldsField;

/**
 * Reusable block settings
 */
class BlockSettings
{
    public static function sectionPresentation(
        RockFieldsField $field,
        array $config = [],
        array $additionalValues = [],
    ): array {
        $name = 'section_presentation';

        return [
            'name' => $name,
            'label' => 'Section Presentation',
            'value' => $field->input($name, 'select', [
                '*normal' => 'Normal',
                'standalone' => 'Standalone',
                'standalone_drop_shadow' => 'Standalone + Drop Shadow',
                ...$additionalValues,
            ]),
            ...$config,
        ];
    }

    public static function bodyWidth(
        RockFieldsField $field,
        array $config = [],
        array $additionalValues = [],
    ): array {
        $name = 'body_width';

        return [
            'name' => $name,
            'label' => 'Body Width',
            'value' => $field->input($name, 'select', [
                '*constrained' => 'Constrained',
                'full' => 'Full',
                ...$additionalValues,
            ]),
            ...$config,
        ];
    }

    public static function backgroundColor(
        RockFieldsField $field,
        array $config = [],
        array $additionalValues = [],
    ): array {
        $name = 'background_color';

        return [
            'name' => $name,
            'label' => 'Background Color',
            'value' => $field->input($name, 'select', [
                '*white' => 'White',
                'seafoam' => 'Seafoam',
                'champagne' => 'Champagne',
                'none' => 'None',
                ...$additionalValues,
            ]),
            ...$config,
        ];
    }

    // ...as many commonly used settings methods as you need
}

Settings are easily reusable in any block.

<?php

declare(strict_types=1);

namespace RockPageBuilderBlock;

use ProcessWire\RockFieldsField;
use RockPageBuilder\{Block, BlockSettingsArray};
use RockPageBuilderSupport\BlockSettings;

class BlogFeed extends Block {

    const prefix = "rpb_blogfeed_";

    /**
     * Block config info
     */
    public function info(): array
    {
        return [
            'title' => 'News Article Feed',
            'description' => 'An array of blog posts',
            // ...other info
        ];
    }

    /**
     * Runtime block settings
     */
    public function settingsTable(RockFieldsField $field): BlockSettingsArray
    {
        $settings = $this->getDefaultSettings($field);

        $settings->add(
            BlockSettings::bodyWidth($field)
        );

        $settings->add(
            BlockSettings::bodyLocationVertical($field)
        );

        $settings->add(
            BlockSettings::actionLocationVertical($field, config: [
                'label' => "Below 'view all' link"
            ])
        );

        $settings->add(
            BlockSettings::sectionPresentation($field, additionalValues: [
                'full' => 'Full news feed design',
            ])
        );

        return $settings;
    }

    // ... ommitted for brevity
}

This has helped me easily manage common settings for 20 different blocks by editing the settings in one place. By adding the $config and $additionalValues parameters to the BlockSettings methods, overrides can be added when individual blocks need customization. Thanks to the runtime nature of block settings, making these changes on the fly is extremely easy.

This has saved me a lot of time and helps keep things organized. I was able to carry over the bulk of my work with settings from one project to another and it really helped out a lot.

Would love to hear if others out there have developed some tips and tricks that help you build your sites!

Edited Wednesday at 06:25 PM by FireWire
Bernhard made things even more awesome.

[bernhard]

Hey @FireWire thx for sharing! Are you aware of https://www.baumrock.com/en/processwire/modules/rockpagebuilder/docs/settings/#adding-default-settings ?

Nevertheless I see potential in your workflow!

[FireWire]

@bernhard Of course you thought of this... I need to go back and read the docs more ha! I completely missed that.

Everyone save yourself the trouble and RTFM 🤣

[FireWire]

@bernhard Maybe I should mark this post as "solved" 😆

[bernhard]

Ok nice. Just wanted to make sure I understand exactly why you are not using the available approach.

But I like your idea. I'm thinking maybe RPB could load a file like /site/templates/RockPageBuilder/blocksettings.php like this:

<?php
return [
  'foo' => [ ... ],
  'bar' => [ ... ],
  'baz' => [ ... ],
];

Which would make it then possible to set block settings like this:

<?php
public function settingsTable(RockFieldsField $field) {
  $settings = $this->getDefaultSettings();
  $settings
    ->add('foo')
    ->add('baz');
  return $settings;
}

 

[FireWire]

9 minutes ago, bernhard said:

Just wanted to make sure I understand exactly why you are not using the available approach

@bernhard It was completely my oversight, I didn't know that RPB already had a solution for managing settings to be used globally. So it wasn't due to anything other than not knowing about it ahead of time.

9 minutes ago, bernhard said:

Which would make it then possible to set block settings like this:

I like this implementation! Very elegant. Having it in the RPB templates folder is great and that array definition style is really intuitive.

[bernhard]

Give me an hour before you start refactoring... 😉 

[bernhard]

Ok not exactly an hour - took a bit longer than expected... as always 🙈😅

Here you go: Please grab v5.11.0 here https://www.baumrock.com/en/releases/rockpagebuilder/

And RTFM check out the docs here: https://www.baumrock.com/en/processwire/modules/rockpagebuilder/docs/settings/#adding-settings-globally

Thx for the idea! Enjoy! 🙂 

 

[FireWire]

7 hours ago, bernhard said:

Ok not exactly an hour - took a bit longer than expected...

Story of my/our lives. HA.

Thank you for your work on this, it looks great and the syntax is very nice. Excellent work 🙌

[FireWire]

@bernhard Humble suggestion for docs 🙂 Nothing critical but noticed as a regular user of RPB.

<?php

// For global settings, it may be useful to add an example of setting the order when using local settings with prepend().
public function settingsTable(\ProcessWire\RockFieldsField $field)
{
  $settings = $this->getGlobalSettings($field)
    ->use([
      'style',
      'demo-checkbox',
  ]);

  $settings->prepend([
    'name' => 'prepended-custom-checkbox',
    'label' => 'Prepended custom checkbox',
    'value' => $field->input('prepended-custom-checkbox', 'checkbox'),
  ]);

  $settings->add([
    'name' => 'custom-checkbox',
    'label' => 'Custom checkbox',
    'value' => $field->input('custom-checkbox', 'checkbox'),
  ]);

  return $settings;
}

//-----------

// Under the simple checkbox example it shows how to call the add method but doesn't specify where the $settings variable is initialized
$settings->add([
  'name' => 'demo-checkbox',
  'label' => 'Demo Checkbox',
  'value' => $field->input('demo-checkbox', 'checkbox'),
]);

// May be good to show a settings table that doesn't use globals initialize the $settings variable. It's in the default stub, but may be helpful anyway
public function settingsTable(\ProcessWire\RockFieldsField $field)
{
  $settings = $this->getDefaultSettings($field);
  
  $settings->add([
    'name' => 'demo-checkbox',
    'label' => 'Demo Checkbox',
    'value' => $field->input('demo-checkbox', 'checkbox'),
  ]);
  
  return $settings;
}

New settings are working perfectly, love the upgrade 👍

[bernhard]

Thx @FireWire I have updated the docs and expanded your example of add()/prepend() with insertAfter()/insertBefore() https://www.baumrock.com/en/processwire/modules/rockpagebuilder/docs/settings/

[FireWire]

@bernhard Awesome! 🙌

[bernhard]

Thx, oh and I forgot to mention that I changed your example:

On 1/15/2025 at 9:51 PM, FireWire said:

$settings = $this->getDefaultSettings($field);

is now

$settings = $this->getSettings();

Because I think the getDefaultSettings is nothing we should promote any more 🙂 

This change is part of v5.12.0

[FireWire]

Great tweaks, and I just learned about insertBefore()/insertAfter() for the first time. Excellent!

[bernhard]

That's regular WireArray methods, nothing fancy here 🙂 

[bernhard]

Actually there is one detail: When using add/prepend you can provide an array because I implemented those in my settingsarray class. But insertBefore and insertAfter are not implemented, so they will be called directly from the WireArray class, which does not understand adding a plain array. That's why we need the $settings->getItem(...) call before.