Getting Started
Features
- API
- Blocks
- Blocks with JS
- Helper Classes
- Block Fields
- Accessing Fields
- Text Margin
- Presets
- Block Settings
- Drag & Drop Sortable
- Block Spacings
- Custom Block Stubs
- Widgets
Requirements
PHP>=8.0ProcessWire>=3.0.227RockMigrations>=3.30.0RockFrontend>=3.6.0- API
Block Settings
It's very common that you want to provide some options for your block, for example for choosing between different layout variations or for changing the size of the preview thumbnails of an image gallery block.
RockFields
You can create a field for all those settings, if you want. But the better option is to use the RockFields
module that ships with RockPageBuilder.
It allows you to create several fields at runtime without creating those fields in the database. Neat!
A simple checkbox would look like this:
[
'name' => 'demo-checkbox',
'label' => 'Demo Checkbox',
'value' => $field->input('demo-checkbox', 'checkbox'),
]
Adding Settings (Globally)
A setting that you add to one block is often also needed by other blocks. That's why we recommend that you define your settings globally and then just add them to your blocks as needed.
To add global settings, create the file /site/templates/RockPageBuilder/settings.php
with content like this:
<?php
namespace ProcessWire;
return [
[
'name' => 'demo-checkbox',
'label' => 'Demo Checkbox',
'value' => $field->input('demo-checkbox', 'checkbox'),
],
[
'name' => 'style',
'label' => 'Style Variation',
'value' => $field->input('style', 'select', [
'*one' => 'Style One (image in the background)',
'two' => 'Style Two (image on the right)',
'three' => 'Style Three (centered)',
]),
]
];
Adding Global Settings to a Block
Every Block can then use
any of the globally defined settings like this:
public function settingsTable(\ProcessWire\RockFieldsField $field)
{
return $this->getGlobalSettings($field)
->use([
'style',
'demo-checkbox',
]);
}
Please note that by defining a different order in the use
method we flipped the order of the settings! Settings will always be rendered in the order that you define in the use
method, not in the order how they are defined in the PHP file.
Adding Custom Settings to a Block
You can combine global settings with custom settings by using the add
method:
public function settingsTable(\ProcessWire\RockFieldsField $field)
{
$settings = $this->getGlobalSettings($field)
->use([
'style',
'demo-checkbox',
]);
// add: add a new settings field at the end
$settings->add([
'name' => 'custom-checkbox',
'label' => 'Custom checkbox',
'value' => $field->input('custom-checkbox', 'checkbox'),
]);
// prepend: add checkbox at first position
$settings->prepend([
'name' => 'prepended-custom-checkbox',
'label' => 'Prepended custom checkbox',
'value' => $field->input('prepended-custom-checkbox', 'checkbox'),
]);
// insertAfter/insertBefore: add checkbox after/before other setting
$newItem = $settings->getItem([
'name' => 'inserted-custom-checkbox',
'label' => 'Inserted custom checkbox',
'value' => $field->input('inserted-custom-checkbox', 'checkbox'),
]);
$settings->insertAfter($newItem, $settings->get('style'));
return $settings;
}
Using non-global settings
public function settingsTable(\ProcessWire\RockFieldsField $field)
{
$settings = $this->getSettings();
$settings->add([
'name' => 'demo-checkbox',
'label' => 'Demo Checkbox',
'value' => $field->input('demo-checkbox', 'checkbox'),
]);
return $settings;
}
Multilingual Settings
Of course you can also have multilingual settings. The only thing to make sure is that only the labels are translated and the values are unique:
$settings->add([
'name' => 'demo-select',
'label' => __('Demo Select Field'),
'value' => $field->input('demo-select', 'select', [
'foo' => __('foo value label'),
'bar' => __('bar value label'),
]),
]);
Custom Settings Wrapper
You can set options for the wrapping Inputfield in the info() method of your block:
public function info() {
return [
...
'settings' => [
'label' => 'Settings for this block',
'icon' => 'check',
'collapsed' => Inputfield::collapsedYes,
],
];
}
Conditionals (showIf)
The showIf
feature allows you to conditionally display settings based on the value of other settings within the same block. This can be particularly useful for creating dynamic and interactive settings interfaces where the visibility of certain options depends on the configuration of others.
To use showIf
, you need to specify it as an attribute in the settings array of your block's settingsTable
method. The showIf
attribute takes a string that represents a condition. This condition is composed of the name of the setting to watch, an equals sign =
, and the value that triggers the visibility of the current setting.
public function settingsTable(\ProcessWire\RockFieldsField $field)
{
return $this->getDefaultSettings($field)
->add([
'name' => 'showImages',
'label' => 'Show Items with Images',
'value' => $field->input('showImages', 'checkbox'),
])->add([
'name' => 'noBackground',
'label' => 'Do not add blurred background behind images',
'value' => $field->input('noBackground', 'checkbox'),
'showIf' => 'showImages=1',
]);
}
Example Settings
settings.php
return [
[
'name' => 'demo-checkbox',
'label' => 'Demo Checkbox',
'value' => $field->input('demo-checkbox', 'checkbox'),
],
[
'name' => 'demo-text',
'label' => 'Demo Text Field',
'value' => $field->input('demo-text', 'text'),
],
[
'name' => 'demo-select',
'label' => 'Demo Select Field',
'value' => $field->input('demo-select', 'select', [
'foo' => 'foo value', // the star marks the default option
'bar' => 'bar value',
]),
],
[
'name' => 'demo-radios',
'label' => 'Demo Radios Field',
'value' => $field->input(
'demo-radios',
// use either "radios" or "radios-inline"
'radios', [
'foo' => 'foo value', // the star marks the default option
'*bar' => 'bar value',
]
),
],
// The multi-checkbox field as a slightly different api on the frontend
// because it can hold multiple values at once. For easier access the plain
// array is converted to a WireData() object and you can use PHP8 syntax
// to check for selected state:
// $data = $block->settings('demo-checkboxes');
// if $data?->foo echo "foo checkbox is selected";
// if $data?->bar echo "bar checkbox is selected";
[
'name' => 'demo-checkboxes',
'label' => 'Demo Checkboxes Field',
'value' => $field->input(
'demo-checkboxes',
// use either "checkboxes" or "checkboxes-inline"
'checkboxes', [
'foo' => 'foo value', // the star marks the default option
'*bar' => 'bar value',
]
),
],
];
Adding default settings (DEPRECATED)
Sometimes you want to have the same setting on all or almost all blocks of your project. Rather than copy and pasting the same settings from block to block you can define global settings for all blocks and add additional settings to some blocks later:
// in site/ready.php
use RockPageBuilder\Block;
use RockPageBuilder\BlockSettingsArray;
/** @var RockPageBuilder $rpb */
$rpb = $this->wire->modules->get('RockPageBuilder');
$rpb->defaultSettings(
function (BlockSettingsArray $settings, RockFieldsField $field, Block $block) {
$settings->add([
'name' => 'bgmuted',
'label' => 'Add muted background',
'value' => $field->input('bgmuted', 'checkbox'),
]);
if($block->template == 'your-block-type-template') {
$settings->add(...);
}
}
);
Instead of if/else in the default settings callback you can also remove default settings in a specific block:
// add this to your block's php file
public function settingsTable(RockFieldsField $field) {
$settings = $this->getDefaultSettings();
// hide one of the global settings
$settings->remove('name=foo');
// add a custom setting to this block
$settings->add([
'name' => 'bar',
'label' => 'BAR-setting',
'value' => $field->input('bar', 'select', [...]),
]);
// you can also add settings on top:
$settings->prepend([
'name' => 'baz',
'label' => 'BAZ-setting',
'value' => $field->input('baz', 'select', [...]),
]);
return $settings;
}