Cuisine Sections allows you to add custom meta-data to each section. We do this with settings panels. These show up as little tooltipped icons next to a sections title:
On this page we’ll handle the following topics:
All panel data gets saved with the field name as it’s key. So retrieving data to use in your templates is quite easy:
if( $section->getProperty('hide_container') == false )
echo '<div class="container">';
The example above checks for the default panel data called “hide_container” and echoes a container div in the section’s template depending on wether this checkbox was selected. If you’re going to use custom panel data, we highly recommend you overwrite the default templates provided by the plugin and use your own
The standard settings-panel in Cuisine Settings has a few tricks up it’s sleeve for extending functionality.
You can add or remove regular Cuisine Core Field Objects via a filter for the default settings panel. The regular panel contains the following three fields:
Adding another field is quite easy:
add_filter( 'cuisine_sections_setting_fields', function( $fields ){
$alignment = [
'top center' => 'Top, center',
'center center' => 'Center, center',
'bottom center' => 'Bottom, center'
];
//add the fields:
$fields[] = Field::image( 'background_image', __( 'Background Image' ) );
$fields[] = Field::select( 'background_align', __( 'Background Align' ), $aligment );
return $fields;
});
The example above adds two fields to the default settings panel allowing the user to pick an image and a way that image is aligned. The idea being that we can use this data in our template to add a background image the user chose.
To change the default arguments for a panel (like the icon or the position) you can use this filter tied to the default settings panel:
add_filter( 'cuisine_sections_base_panel_args', function( $args ){
$args['position'] = 10; //set the position at 10 instead of the default -1
$args['icon'] = 'dashicons-camera'; //replace the default gear with a camera icon
return $args;
});
Currently these are the only settings you’ll be able to change in the standard settings panel.
The goal for creating Cuisine and all it’s subsequent tools is to unify the way you create your WordPress websites and plugins. This is why creating a Sections’ Setting Panel is exactly the same as creating a Metabox in Cuisine. All you need is an array of Cuisine Field objects. The example below shows you just how to create a new settings panel. It uses the SettingsPanel class found in Sections’s wrapper system, which you can include as follows:
use ChefSections\Wrappers\SettingsPanel
$fields = [
Field::text( 'test', __( 'Test field' ) ),
Field::text( 'test2', __( 'Test 2 field' ), [ 'placeholder' => __( 'type something...' ) ] )
];
SettingsPanel::make(
'My Settings Panel'
'my-settings',
[ 'icon' => 'dashicons-admin-site' ]
)->set( $fields );
This example creates a settings panel with two text fields. Let’s break the arguments down:
1: the label My Settings Panel This is the title of the panel. It will show up at the top of your panel and as a tooltip on the icon when hovering over the icon.
2: the slug my-settings This is a simple slug to make sure your settings panel is unique.
3: the arguments This is an array of arguments. In the example above we’ve chosen to just add an icon (which can be any dashicon WordPress offers). Possible arguments are:
Icon: can be any valid dashicon or url to an image.
Position: determine where this panel will sit compared to other settings panels
Rules: when this panel might show up (and at what section). More on this later.
Sometimes you want to restrict the amount of sections a settings panel is for. For example; if you are creating a custom Container section to which you plan to add a slider script, you might want users to select how fast that slider should go and if the slider should contain controls. In that case, you wouldn’t want the panel to show up in regular sections, just your custom container type. So consider this example:
$fields = [
Field::checkbox(
'auto_play',
__( 'Play automatically (be careful!)' ),
[ 'defaultValue' => false ]
),
Field::number(
'speed',
__( 'Slider speed' ),
[ 'defaultValue' => 3000 ]
)
];
SettingsPanel::make(
__( 'Slider settings' ),
'slider_settings',
[
'rules' => [
'containerType' => 'slider',
'userRole' => 'administrator'
]
]
)->set( $fields );
In this example we set two fields: an auto-play checkbox and a speed field. Then we create our settings-panel where we add two rules:
These rules will get checked before the panel gets rendered and if the section isn’t a container or isn’t of the type ‘slider’, it won’t render. If the logged in user doesn’t have the role ‘administrator’ it won’t render as well.
Here’s an example with all rules set:
SettingsPanel::make(
__( 'My settings panel' ),
'my-settings-panel',
[
'rules' => [
'sectionTypes' => ['content', 'container'],
'sectionView' => 'fullwidth',
'inContainer' => false,
'containerType' => false,
'userCap' => 'edit-sections',
'userRole' => ['administrator', 'editor']
]
]
)->set( $fields );
Here’s a break down:
sectionType: Array/String. Can be any of the registered section types
sectionView: Array/String. Can be any of the [section views(/sections/extending/views)]
inContainer: Boolean/String. True/false for all containers. String for a specific container; targets sections inside a container
containerType: Array/String. Can be any registered container type
userCap: Array/String. Can be any registered WordPress user capability. Applies to the logged-in user.
userRole: Array/String. Can be any registered WordPress user role. Applies to the logged-in user.