MB Template
MB Template helps you write configuration for custom fields in the YAML format, which is human-readable and easy to understand.
After installing, please go to Settings → MB Template to add the template for custom meta boxes and custom fields.
Quick sample
Before going into details about using the plugin, let's look at a quick sample to see how it works (screenshot above).
In the plugin settings page, enter the following content written in YAML. This is the settings for a field group. .
title: Laptop details
post_types: laptop
fields:
- name: Brand
type: select
options:
hp: HP
asus: ASUS
dell: Dell
- Model
- name: Images
type: image_advanced
The plugin will parse this content into a PHP array as follows:
[
'title' => 'Laptop details',
'post_types' => 'laptop',
'fields' => [
[
'name' => 'Brand',
'type' => 'select',
'options' => [
'hp' => 'HP',
'asus' => 'ASUS',
'dell' => 'Dell',
],
],
'Model',
[
'name' => 'Images',
'type' => 'image_advanced',
],
],
]
This array will be sent to Meta Box and Meta Box will register a field group with this settings array. The result looks like this:
Now you understand how the plugin works. It's time to get familiar with YAML syntax.
YAML syntax
In YAML, we mostly defines arrays with key: value pairs as you saw above. YAML has different ways to define simple arrays and associated arrays.
Simple arrays
Simple arrays are called sequences in YAML. They use dashes followed by space (- ) to define items:
- Item 1
- Item 2
- Item 3
You can also use short syntax like this:
[Item 1, Item 2, Item 3]
Both are equivalent to the following PHP code:
[ 'Item 1', 'Item 2', 'Item 3' ];
Associated arrays
Associated arrays are called mappings in YAML. They use a colon followed by a space (: ) to define each key/value pair:
key1: value1
key2: value2
key3: value3
alternatively:
{key1: value1, key2: value2, key3: value3}
which is equivalent to this PHP code:
[
'key1' => 'value1',
'key2' => 'value2',
'key3' => 'value3'
]
Nested arrays
Nested arrays (sequences or mappings) can be defined with 1 or more spaces:
fields:
- name: Name
id: name
type: text
- name: Image
id: image
type: image_advanced
which is equivalent to:
[
'fields' => [
[
'name' => 'Name',
'id' => 'name',
'type' => 'text',
],
[
'name' => 'Image',
'id' => 'image',
'type' => 'image_advanced',
],
],
]
- The number of spaces does not matter. But keep the indentation consistent with the same number of spaces.
- Comments can be added by adding
#at the beginning of the line. - YAML accepts all data types string, number, booleans, etc.
For more information about using YAML, the Symfony project wrote a very good guide to follow. If you want the full reference, you can read it at YAML homepage.
Creating field groups
Each field group or custom field has a list of the settings which is written in key: value pairs (associated arrays). We use YAML mapping for these settings.
Please refer to field group settings and field settings when defining keys.
If you register single meta box, then enter field group settings and its fields like this:
title: Profile
post_types: customer
fields:
- name: Title
id: prefix_title
type: radio
options:
mr: Mr.
ms: Ms.
- name: Name
id: name
type: text
- name: DOB
id: dob
type: date
js_options:
dateFormat: 'd-m-y'
If you need to create multiple field groups, use this template:
# First field group.
- title: Profile
post_types: customer
fields:
- name: Title
id: prefix_title
type: radio
options:
mr: Mr.
mrs: Mrs.
ms: Ms.
- name: Name
id: name
type: text
- name: DOB
id: prefix_dob
type: date
js_options:
dateFormat: 'd-m-y'
# Second field group.
- title: Job Description
post_types: [customer, supplier]
fields:
- name: Job Title
id: job_title
type: select_advanced
options:
director: Director
manager: Marketing Manager
tech: Technical Supporter
placeholder: Please select your job title
- name: Job Description
id: job_desc
type: wysiwyg
options:
media_buttons: false
quicktags: false
Config files
The plugin has an option that allows you to read the configuration from a specific file (.yml), not only from manual input.
To do that, in the plugin settings page, enter the absolute path to the configuration file (.yml). You can put the configuration file in any folder of your website. For convenience, the plugin supports the following path variables that you can used in the file paths:
| Name | Description |
|---|---|
%wp-content% | Path to wp-content directory, without trailing slash |
%plugins% | Path to wp-content/plugins directory, without trailing slash |
%themes% | Path to wp-content/themes directory. Same as get_theme_root() function, without trailing slash |
%template% | Path to current theme directory. Same as get_template_directory() function, without trailing slash |
%stylesheet% | Path to current child theme directory. Same as get_stylesheet_directory() function, without trailing slash |
For example, if you put the config files in the theme's meta-box folder, then you can enter the following path:
%stylesheet%/meta-box/
If you put in the wp-content/meta-box-yml folder as well, then you can use both locations as follows:
%stylesheet%/meta-box/, %wp-content%/meta-box-yml/
You can put multiple files in multiple folders. The plugin will read and parse them all. This process is real-time, which means if you make any changes, they will affect immediately. This is convenient if you want to keep all your configuration files in one place and put them under version control like Git.
Hooks
meta_box_template_files
This filter allows developers to register paths to files and folders to parse YAML files. It accepts one parameters: an array of files/folders.
For example, if you want to add folder(s), which contains your YAML config files, use the following code:
add_filter( 'meta_box_template_files', function( $files ) {
$files[] = get_template_directory() . '/meta-box-yml';
$files[] = '/path/to/your/yml/file-or-folder';
return $files;
} );