# Meta Box 开发者文档
Meta Box 开发者文档，介绍自定义字段与扩展。
# Abilities
import LiteYouTubeEmbed from 'react-lite-youtube-embed';
import 'react-lite-youtube-embed/dist/LiteYouTubeEmbed.css';
The abilities from Meta Box are built on the [WordPress Abilities API](https://developer.wordpress.org/apis/abilities-api/) to let AI agents - such as Claude or Cursor - perform actions on your site's content. To handle the communication, Meta Box uses the official [MCP Adapter plugin](https://github.com/WordPress/mcp-adapter), which translates WordPress abilities into the Model Context Protocol (MCP) that AI agents understand.
Depending on which abilities are enabled, AI agents can get, create, update, or delete custom post types, taxonomies, posts, terms, field groups, custom fields, and field values that Meta Box supports.
## Connecting AI agents to WordPress
First, connect WordPress to an AI agent via the [MCP Adapter plugin](https://github.com/WordPress/mcp-adapter). It exposes WordPress as an MCP server that AI agents can connect to.
### 1. Install MCP Adapter plugin
1. Download the [latest release of MCP Adapter](https://github.com/WordPress/mcp-adapter/releases) from GitHub
2. Go to **Plugins → Add New → Upload Plugin**, select the ZIP file, then install and activate the plugin
### 2. Generate application password
MCP Adapter uses Application Passwords for authentication (not your account password).
1. Go to **Users → Profile**
2. Scroll to the **Application Passwords** section
3. Enter a name (e.g. "MCP Agent"), then click **Add New Application Password**
4. Copy the generated password - it is shown only once
:::warning
An application password grants the same capabilities as the user account it belongs to. To restrict permissions, create a dedicated WordPress user with an appropriate role (e.g. Editor or Author) first, then generate an application password under that user.
:::
### 3. Configure MCP clients
Configure MCP clients (Claude Desktop, Claude Code, Cursor, etc.) to connect to your WordPress MCP server using HTTP transport via a proxy. Use `@automattic/mcp-wordpress-remote` to bridge local stdio to remote WordPress HTTP:
```json
{
"mcpServers": {
"wordpress-http": {
"command": "npx",
"args": [
"-y",
"@automattic/mcp-wordpress-remote@latest"
],
"env": {
"WP_API_URL": "http://your-site.com/wp-json/mcp/mcp-adapter-default-server",
"LOG_FILE": "/path/to/logs/mcp-adapter.log",
"WP_API_USERNAME": "your-username",
"WP_API_PASSWORD": "your-application-password"
}
}
}
}
```
Replace:
- The domain in `WP_API_URL` with your site domain
- `WP_API_USERNAME` with your WordPress username
- `WP_API_PASSWORD` with the Application Password from Step 2
- `LOG_FILE` with the path where logs should be written
For more details, follow the instructions in the [MCP Adapter plugin's GitHub repository](https://github.com/WordPress/mcp-adapter).
## Post type abilities
:::info Technical information
These abilities are available in the [MB Custom Post Types & Custom Taxonomies](/extensions/mb-custom-post-type/) extension, which is bundled in [Meta Box Lite](https://metabox.io/lite/) (free) and [Meta Box AIO](https://metabox.io/aio/) (paid) plugins.
:::
### Creating and managing custom post types
To create a new custom post type, describe the structure you want in natural language. For example:
> *Create a custom post type named Event, set the menu icon to "calendar", enable the "Enable abilities" option in the Features tab, and enable all abilities available under that option.*
Within seconds, you should have the post type you asked for:
You can also ask your AI agent to update post type settings, such as enabling a hierarchical structure or changing the menu icon.
### Abilities for posts
To enable abilities for posts of a custom post type, go to the **Features** tab when creating or editing a post type, then turn on **Enable abilities**. Available actions include:
- Getting post type data (the definition)
- Getting, creating, updating, and deleting posts under that post type
You can enable or disable each ability independently. Once enabled, compatible AI agents can invoke these abilities through the Abilities API.
For example, after creating an Event post type, you can ask the AI agent to generate posts for it:
> *Find 5 latest WordPress events in the world. They're posts of the event post type*
The agent creates the posts without manual entry:
You can also update posts. For example:
> *Update the status of the posts to published.*
Or delete posts with a simple prompt:
> *Delete the events in Asia.*
The posts are updated or deleted according to your request.
## Taxonomy abilities
:::info Technical information
These abilities are available in the [MB Custom Post Types & Custom Taxonomies](/extensions/mb-custom-post-type/) extension, which is bundled in [Meta Box Lite](https://metabox.io/lite/) (free) and [Meta Box AIO](https://metabox.io/aio/) (paid) plugins.
:::
### Creating and managing custom taxonomies
The plugin also lets you create, update, and delete custom taxonomies, as well as manage the terms within them.
Start by creating a new custom taxonomy:
> *Create a custom taxonomy named "location" and assign it to the Event custom post type.*
When you need to update the taxonomy, describe the change you want:
> *Enable the Re-order terms feature for this taxonomy.*
### Abilities for terms
Taxonomy abilities are configured the same way as post type abilities. You can:
- Get taxonomy data (the definition)
- Get, create, update, and delete terms in that taxonomy
You can then give AI agents prompts like this:
> *Update locations: remove cities and keep only countries.*
Or delete specific terms:
> *Delete the locations in Asia.*
The result:
## Field group abilities
:::info Technical information
These abilities are available in the [MB Builder](/extensions/meta-box-builder/) extension, which is bundled in [Meta Box Lite](https://metabox.io/lite/) (free) and [Meta Box AIO](https://metabox.io/aio/) (paid) plugins.
:::
Field group abilities let AI agents register and manage field groups and fields. They are built into Meta Box and available by default - you do not need to enable them before using them with compatible AI agents.
With these abilities, AI agents can:
* Create field groups
* Update (edit) field groups
* Delete field groups
* Add or remove fields
* Update field settings, such as labels, IDs, and types
* Move fields up or down
For example, to create a field group for the `event` post type, use a prompt like this:
> *Create a field group Event Details for the event post type. That field group includes 2 fields: Address (type: text, ID: address). Date and Time (type: Datetime, ID: datetime).*
Result:
You can also update the field group - for example, by changing a field ID, setting text length limits, or adding a new field:
> *Add a Map field (type: Open Street Map) below the Address field, and set the address field ID to `address`.*
Or:
> *Move the Date and Time field to the top of the field group.*
If you are not sure which fields to add, AI agents can suggest suitable ones based on your requirements.
## Field value abilities
:::info Technical information
These abilities are available in the **Meta Box** plugin (free), which is bundled in [Meta Box Lite](https://metabox.io/lite/) (free) and [Meta Box AIO](https://metabox.io/aio/) (paid) plugins.
:::
Similar to other objects, the plugin lets you:
* Get field values
* Set values for custom fields
* Edit field values
* Delete field values
This is especially useful when importing structured data from external sources.
Here is an example of automatically finding information and filling in custom fields:
> *Search details for the 5 latest WordPress events you provided, then fill in all the custom fields of those events.*
In the post editor, the fields are populated:
You can also edit field values. For example:
> *Update the date format to Jul 4th, 2026.*
Or remove all stored values:
> *Delete all data in the custom fields.*
The Meta Box performs the requested action.
## Video tutorial
The video below shows examples of using the Meta Box abilities to create and manage custom post types, taxonomies, posts, terms, fields, and field values:
# Block bindings
Custom fields store structured data - event dates, subtitles, cover images, prices - but that data does not appear on the front end by itself. You still need a way to [display it](/custom-fields/#displaying-fields).
[Block bindings](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-bindings/) do that in Gutenberg. Like **dynamic data** in page builders, they connect a Meta Box field to a core block - a Paragraph shows your subtitle, an Image block shows your cover photo. Meta Box registers your fields as block binding sources by default, so you can use them in Gutenberg without PHP templates or a custom block.
## Why use block bindings?
Block bindings bring Meta Box field data into Gutenberg - connect fields from posts, terms, authors, or settings pages to Paragraph, Heading, Image, Button, and other core blocks, right in the editor.
- **Like dynamic data, but for Gutenberg** - pick a field, and the block shows its value on the front end.
- **No extra code** - bind a Paragraph or Image block directly to a field.
- **Single source of truth** - update the field once. Every bound block reflects the change.
- **Native block styling** - use core blocks with full typography, spacing, and layout controls.
They work in post content, block templates, and synced patterns - alongside [other ways to display fields](/custom-fields/#displaying-fields) when you need them.
This feature requires **WordPress 6.5+**. The **Attributes** panel in the block editor (to pick a field visually) requires **WordPress 6.9+**.
## Binding sources
Meta Box registers a separate source for each object type:
Source | Label | Available with
---|---|---
`meta-box/post-field` | **Meta Box Post Field** | Meta Box (posts and custom post types)
`meta-box/term-field` | **Meta Box Term Field** | [MB Term Meta](/extensions/mb-term-meta/)
`meta-box/author-field` | **Meta Box Author Field** | [MB User Meta](/extensions/mb-user-meta/)
`meta-box/setting-field` | **Meta Box Setting Field** | [MB Settings Page](/extensions/mb-settings-page/)
In the block editor, pick the source that matches where your field is stored, then choose the field (or a field property for structured fields).
## Hiding a field from block bindings
By default, Meta Box makes fields available for block bindings. If you do not want a field to appear in the block editor bindings UI, you can hide it.
### Using MB Builder
1. Edit a field.
2. Open the **Advanced** tab in field settings panel.
3. Turn on **Hide from block bindings?**.
:::info
The instruction above uses [MB Builder](/extensions/meta-box-builder/), an extension providing the UI to create fields, and is already bundled in [Meta Box Lite](https://metabox.io/lite/) and [Meta Box AIO](https://metabox.io/aio/). If you prefer to use code, please see below.
:::
### Using code
Add `'hide_from_block_bindings' => true` to the [field settings](/creating-fields-with-code/#fields):
```php
add_filter( 'rwmb_meta_boxes', function ( $meta_boxes ) {
$meta_boxes[] = [
'title' => 'Movie Details',
'post_types' => 'movie',
'fields' => [
[
'name' => 'IMDB Rating',
'id' => 'imdb_rating',
'type' => 'number',
'min' => 0,
'max' => 10,
'step' => 0.1,
// highlight-next-line
'hide_from_block_bindings' => true,
],
],
];
return $meta_boxes;
} );
```
## Binding a block to a field
1. Edit a post, template, or pattern in the block editor.
2. Select a block that supports bindings (for example Paragraph, Heading, Button, or Image).
3. In the block settings sidebar, open the **Attributes** panel.
4. Choose the attribute to bind (for example **Content** for a paragraph, or **URL** for an image).
5. Select the Meta Box source for your field type (for example **Meta Box Post Field**), then pick your field (or a field property for structured fields).
The bound attribute uses the field value when the content is rendered on the front end.
:::tip Binding without the UI
The **Attributes** panel is available from **WordPress 6.9** onward. On **WordPress 6.5 to 6.8**, you can still bind attributes in the **Code editor**. Example for a paragraph bound to an `imdb_rating` post field:
```html
Fallback text
```
Use `meta-box/term-field`, `meta-box/author-field`, or `meta-box/setting-field` for fields on terms, authors, or settings pages.
:::
## Structured fields
Scalar fields ([text](/fields/text/), [number](/fields/number/), [email](/fields/email/), and similar) expose a single binding option: the field value as a string.
Structured fields expose **properties** you can bind separately. In the UI they appear as labels like `Poster Image: URL` or `Poster Image: Alt Text`. In code, pass a `key` in the binding args:
```html
```
Supported properties by field type:
Field type | Properties (`key`)
---|---
`single_image`, `image`, `image_advanced`, `image_upload` | `url`, `alt`, `title`, `caption`, `description`
`file`, `file_advanced`, `file_upload` | `url`, `title`
`background` | `image`
`link` | `url`, `title`, `target`
`map`, `osm` | `latitude`, `longitude`
`post` | `post_title`, `post_excerpt`, `post_content`, `post_date`, `post_modified`, `post_author`, `url`
`taxonomy`, `taxonomy_advanced` | `name`, `slug`, `description`, `url`
`user` | `display_name`, `user_url`
`video` | `src`, `title`, `caption`, `description`
`fieldset_text` | Each option key from the field's `options`
If `key` is omitted, Meta Box falls back to the bound block attribute name (for example, an Image block's `url` attribute).
## Limitations
- **[Groups](/extensions/meta-box-group/) are not supported.** Block bindings map one block attribute to one value (a string, URL, and similar). A group stores nested fields as a structured set of values, so it cannot bind cleanly to a single Paragraph, Heading, or Image attribute. For group-based layouts, use [MB Views](/extensions/mb-views/) or [MB Blocks](/extensions/mb-blocks/) instead.
- **One value only.** If a field is [cloneable](/cloning-fields/) or stores multiple values (for example a multi-select or checkbox list), the binding uses only the **first** value.
- **Editor preview.** Bound attributes are resolved on the front end. The editor lists available fields for binding but does not show live field values in the canvas, and bound values are not editable from the block.
- **Access.** Bound values are only returned when the visitor can view the related object. For posts, that means password-protected or private content stays hidden from unauthorized visitors. For non-public taxonomies, term fields follow the same idea.
# Bundling Meta Box
import FAQ from '@site/src/components/FAQ';
Meta Box and extensions can be used as standalone plugins or bundled within other themes or plugins.
:::warning Licensing
1. If you want to bundle Meta Box into other products or services (plugins, themes, solutions, hosting providers, SASS companies, site maintenance providers, etc.) that sell to other people, please [contact us](https://metabox.io/contact/) for a custom pricing plan.
2. You are **not allowed** to use premium extensions in your free products, like plugins and themes on WordPress.org.
:::
## Using TGM Plugin Activation
It is recommended to use the [TGM Plugin Activation](http://tgmpluginactivation.com) to declare Meta Box and free extensions as dependencies for your themes or plugins. This way, Meta Box and the extensions can be auto-updated to the latest version.
To use the, follow these steps:
1. Download [TGMPA Plugin Activation](http://tgmpluginactivation.com/download/). For **I'm going to use TGMPA in a:** select **Plugin**.
1. Extract the downloaded `.zip` file and copy the file `class-tgm-plugin-activation.php` and `example.php` to your theme/plugin folder.
1. Open the `example.php` file and add Meta Box to the required plugin list:
```php
require_once __DIR__ . '/class-tgm-plugin-activation.php';
add_action( 'tgmpa_register', 'prefix_register_required_plugins' );
function prefix_register_required_plugins() {
$plugins = [
// highlight-start
[
'name' => 'Meta Box',
'slug' => 'meta-box',
'required' => true,
],
// highlight-end
];
$config = [
'id' => 'your-id',
];
tgmpa( $plugins, $config );
}
```
Then, include the `example.php` file in your theme's `functions.php` or your plugin's main file.
## Directly including extensions
:::danger Not recommended
This method disables the auto update mechanism and sometimes causes conflicts with the latest versions of WordPress, or with other plugins that use other versions of Meta Box and extensions. And you have to update extensions manually. You should consider using TGMPA Activation class as described above first, and only use this method if you have no other choice.
:::
Bundling extensions means you include extensions directly in your products and use them as a library.
1. Copy the extension folder to your theme or plugin. You can put it in the theme root folder or a subfolder.
1. Include the extension's main file in the `functions.php` of your theme or your plugin's file:
```php
require get_template_directory() . '/mb-settings-page/mb-settings-page.php';
```
# Cloning fields
The clone feature of Meta Box allows you to create multiple inputs from a text, textarea, select, ... fields without declaring many fields in the code. Combining the clone feature with [groups](/extensions/meta-box-group/) gives you a flexible way to define repeatable content.
:::info Clone is a feature
The difference between Meta Box and other plugins is that the clone feature can be applied to **all field types**. And **it is a feature, not a field type**. Then, every field or group can be cloneable or repeater. They are called cloneable fields or cloneable groups.
:::
## Making a field cloneable
When editing a field, turn on this **Cloneable** option in the settings of the field:
After turning on the Cloneable option, other clone settings will appear.
:::info
The instruction above uses [MB Builder](/extensions/meta-box-builder/), an extension providing the UI to create fields, and is already bundled in [Meta Box Lite](https://metabox.io/lite/) and [Meta Box AIO](/extensions/meta-box-aio/). If you prefer to use code, please see below.
:::
No matter what you are using the UI or code, this is a brief description of the clone settings. The keys are for reference in code.
Settings|Key|Description
---|---|---
Cloneable|`clone`|Make the field cloneable? `true` or `false` (default). Optional.
Sortable|`sort_clone`|Allow to drag-and-drop sort clones. `true` or `false` (default).
Clone default value|`clone_default`|Clone the default value of the field? `true` or `false` (default).
Clone as multiple|`clone_as_multiple`| Whether to store cloned values in multiple rows in the database
Max number of clones|`max_clone`|Limit the number of clones. Must be greater than 2. Optional.
Min number of clones|`min_clone`|Minimum number of clones. Optional.
Add more text|`add_button`|The text for **Add more** clone button. Optional. Default "+ Add more".
Clone empty start|`clone_empty_start`|Allows no fields except the **Add more** button to show up. `true` or `false` (default). Optional.
After saving the field group, in the post editor, you will see an **+ Add more** button below the field input. Clicking it allows you to enter more values:
If you are a developer and want to use code, then you need to add the clone settings into the [field settings](/creating-fields-with-code/#fields):
```php
add_filter( 'rwmb_meta_boxes', function ( $meta_boxes ) {
$meta_boxes[] = [
'title' => 'Event details',
'post_types' => 'event',
'fields' => [
[
'name' => 'Date and time',
'id' => 'datetime',
'type' => 'datetime',
// highlight-start
'clone' => true,
// Other clone settings
// highlight-end
],
[
'name' => 'Location',
'id' => 'location',
'type' => 'text',
],
[
'name' => 'Map',
'id' => 'map',
'type' => 'osm',
'address_field' => 'location',
],
],
];
return $meta_boxes;
} );
```
## Data of cloneable fields
For cloneable fields, values are stored as a serialized array in a single row in the database, unless you set `'clone_as_multiple' => true`.
Using serialized data has some benefits:
- Works for all field types, including nested groups.
- Works perfectly with the helper function or with WordPress's `get_post_meta` function (WordPress automatically deserializes string and returns an array).
- Reduces the database size (number of rows), especially when you have nested groups of many fields.
## Query posts by cloneable fields
By default, cloned values are stored as a serialized array, which does not allow you to query posts by these values. For example, if you have a cloneable field `start_date` for the `event` post type, and you want to query events in May 2019 like this:
```php
$args = [
'post_type' => 'event',
'meta_query' => [
// highlight-start
[
'key' => 'start_date', // This field is cloneable
'value' => ['2019-05-01', '2019-05-31']
'compare' => 'BETWEEN',
],
// highlight-end
],
];
$query = new WP_Query( $args );
```
Then it does not work.
To solve this problem, you need to enable the **Clone as multiple** settings for the field.
With that, Meta Box will **save cloneable values in multiple rows in the database**, where each row contains one value. That means if `start_date` has 2 values `['2019-05-01', '2019-04-30']`, it will be saved in 2 rows in the database, one for `2019-05-01` and one for `2019-04-30`. The data is **not serialized** anymore. And thus, your above query will work!
## Default values
When making a field cloneable, its data is an array of cloned values. So, the `std` parameter (default value) should represent this structure, e.g. an array of cloned values.
```php
add_filter( 'rwmb_meta_boxes', function ( $meta_boxes ) {
$meta_boxes[] = [
'title' => 'Event details',
'post_types' => 'event',
'fields' => [
[
'name' => 'Date and time',
'id' => 'datetime',
'type' => 'datetime',
'clone' => true,
// highlight-start
'std' => [
'2022-04-20',
'2022-04-21',
],
// highlight-end
],
[
'name' => 'Location',
'id' => 'location',
'type' => 'text',
],
[
'name' => 'Map',
'id' => 'map',
'type' => 'osm',
'address_field' => 'location',
],
],
];
return $meta_boxes;
} );
```
# Composer
import FAQ from '@site/src/components/FAQ';
This docs shows you how to use [Composer](https://getcomposer.org/) to install and update Meta Box and its extensions.
:::warning Licensing
1. If you want to bundle **premium extensions** into other products or services (plugins, themes, solutions, hosting providers, SASS companies, site maintenance providers, etc.) that sell to other people, please [contact us](https://metabox.io/contact/) for a custom pricing plan.
2. You are **not allowed** to use **premium extensions** in your free products, like plugins and themes on WordPress.org.
:::
## Meta Box and free extensions
Meta Box and all free extensions are [available on Packagist](https://packagist.org/packages/wpmetabox/).
To use them in your project, simply run:
```bash
composer require wpmetabox/meta-box // For Meta Box
composer require wpmetabox/mb-rest-api // For MB Rest API
composer require wpmetabox/meta-box-lite // Or use Meta Box Lite, which includes Meta Box and all free extensions
```
## Premium extensions
To use Composer to install paid extensions, add `repositories` rule to your `composer.json`:
```json
"repositories":[
{
"type": "composer",
"url": "https://packages.metabox.io/YOUR_LICENSE_KEY"
}
],
```
Then you can install paid extensions with:
```bash
composer require meta-box/mb-settings-page:dev-master
composer require meta-box/meta-box-group:dev-master
```
Notes:
- The version of premium extensions specified in `composer.json` **must be `dev-master`**. We do not support version constraints for premium extensions yet. You always use the latest version.
- Extensions are **not autoloaded** by default. You can manually load them or autoload by adding extensions' main files to the `autoload` array in `composer.json`.
- Extensions then will be installed in WordPress's `wp-content/plugins` folder thanks to [composer/installers](https://github.com/composer/installers). To move them to the traditional `vendor` folder, add `installer-paths` to your `composer.json` file as follows:
```json
{
"repositories": [
{
"type": "composer",
"url": "https://packages.metabox.io/YOUR_LICENSE_KEY"
}
],
"require": {
"wpmetabox/mb-custom-post-type": "^2.3",
"meta-box/meta-box-group": "dev-master",
"meta-box/mb-settings-page": "dev-master"
},
// highlight-start
"extra": {
"installer-paths": {
"vendor/meta-box/{$name}": [
"vendor:wpmetabox",
"vendor:meta-box"
]
},
},
// highlight-end
"autoload": {
"files": [
"vendor/wpmetabox/mb-custom-post-type/mb-custom-post-type.php",
"vendor/meta-box/mb-settings-page/mb-settings-page.php",
"vendor/meta-box/meta-box-group/meta-box-group.php"
]
}
}
```
To make the extensions work, load Composer's autoload file:
```php
require 'vendor/autoload.php';
```
Now you can start using Meta Box extensions in your products!
To make it easier for you, we have created a [`composer.json`](https://github.com/wpmetabox/library/blob/master/composer/composer.json) file, which contains a full list of extensions, free and premium. You can use it as a boilerplate and remove the extensions you do not want to use.
Because we use `dev-master` version, Composer cannot load versions to check when running `composer update`. To fix this, run the following command:
```bash
rm -rf vendor && composer clear-cache && composer install
```
:::danger Not recommended
This method disables the auto update mechanism and sometimes causes conflicts with the latest versions of WordPress, or with other plugins that use other versions of Meta Box and extensions. And you have to update extensions manually.
:::
# Creating fields with code
import LiteYouTubeEmbed from 'react-lite-youtube-embed';
import 'react-lite-youtube-embed/dist/LiteYouTubeEmbed.css';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import FAQ from '@site/src/components/FAQ';
Creating custom fields with code is suitable if you want to keep everything in your themes or plugins. This way, you can re-use them in many websites and put them under a version control like Git.
## Registering custom fields with PHP
To create custom fields, you will need to use the filter `rwmb_meta_boxes` to register field groups. This filter accepts one parameter - the array of field groups:
```php
add_filter( 'rwmb_meta_boxes', function ( $meta_boxes ) {
$meta_boxes[] = [
'title' => 'Event details',
'post_types' => 'event',
'fields' => [
[
'name' => 'Date and time',
'id' => 'datetime',
'type' => 'datetime',
],
[
'name' => 'Location',
'id' => 'location',
'type' => 'text',
],
[
'name' => 'Map',
'id' => 'map',
'type' => 'osm',
'address_field' => 'location',
],
],
];
// Add more field groups if you want
// $meta_boxes[] = ...
return $meta_boxes;
} );
```
Each field group has several settings and a list of fields, which we will cover below.
## Field group settings
Each field group has several settings for the location or appearance. Please see the list below:
Name|Description
--|--
`id`|ID, must be unique. Optional. If it is absent, it will be generated from the title.
`title`| The field group title. Required.
`post_types`|Custom post types which the field group is for. It can be a string or an array of slugs. Must be in lowercase (like the slug). Optional. Default: `post`.
`context`|Where the field group is displayed. See below for a list of field group contexts. Optional.
`style`|Whether to keep the default WordPress field group style (`default`) or remove the wrapper box and display the fields seamlessly (`seamless`).
`closed`|Whether to collapse the field group when the page loads? Optional. Default: `false`.
`priority`|Priority within the context where the box is displayed (`high` or `low`). Optional. Default: `high`.
`default_hidden`|Hide the field group by default (`true` or `false`)? The field group can be toggled using the checkbox option in screen Help (on the top right). Optional. Default `false`.
`autosave`|Auto save the custom fields' values (like post content and title)? Optional. Default: `false`.
`media_modal`|Add custom fields to media modal when viewing/editing an attachment. Works only when `post_types` is or contains `attachment`. Optional. Default `false`.
`class`|Custom CSS class for the field group wrapper. Optional.
:::info Media modal limitation
Only simple fields such as text, select, radio, checkbox work in the media modal. Other fields that require custom JavaScript do not work.
:::
### Contexts
The plugin supports the following contexts (locations) where a field group can appear:
Name|Description
---|---
`normal`|Below the post editor. This is the default value.
`advanced`|Below the `normal` section.
`side`|On the right sidebar.
`form_top`|Top of the post form, before the post title
`after_title`|After post title
`after_editor`|After the post content editor, but before `normal` section
`before_permalink`|Before permalink
:::warning Gutenberg
Gutenberg editor only supports `normal` and `side` contexts. Other extra contexts are not supported.
:::
## Fields
Fields are added to a field group via the key `fields`. Each field is an array of settings.
Meta Box supports more than 40 field types. They share some common settings but also offer unique settings per field type.
### Field types
When adding a field, you need to know what type it is and how it works. Understanding that helps you choose the right type of field and, therefore, the right type of data that you want to add to your posts.
Below is the list of supported field types in alphabetical order with a brief description. The field type key is used for reference in code. For how they look like and how to use them, please see details in the [Field types](/fields/) menu.
These are the basic and most used field types that do not require any extra library. The UI of these fields is WordPress-native.
Type | Key | Description
--- | --- | ---
Checkbox | `checkbox` | A simple checkbox, usually used for Yes/No question
Checkbox list | `checkbox_list` | A list of checkboxes where you can select multiple choices
Radio | `radio` | Radio input where you can select only one choice
Select | `select` | Select dropdown where you can select one or multiple choice
Text | `text` | A single-line text input
Textarea | `textarea` | A paragraph text input
These are the advanced field types that usually need an additional library to provide a user-friendly UI.
Type | Key | Description
--- | --- | ---
Background | `background` | Set background properties
Button | `button` | A simple button, usually used for JavaScript triggers
Button group | `button_group` | Select one or multiple choices by enabling button(s) from a group
Color picker | `color` | Color picker
Custom HTML | `custom_html` | Output custom HTML content
Date picker | `date` | Date picker
Datetime picker | `datetime` | Date and time picker
Hidden | `hidden` | For storing a default hidden value
Image Select | `image_select` | Select a choice with images
Key Value | `key_value` | Add an unlimited group of key-value pairs
Google maps | `map` | Google Maps
oEmbed | `oembed` | Input for media from Youtube, Vimeo, and all [supported sites](https://wordpress.org/support/article/embeds/) by WordPress
Open Street Maps | `osm` | Open Street Maps
Password | `password` | For entering a password
Select advanced | `select_advanced` | Beautiful select dropdown using [select2](https://select2.github.io) library
Slider | `slider` | jQuery UI slider
Switch | `switch` | On/off switch with iOS style
Time picker | `time` | Time picker
WYSIWYG editor | `wysiwyg` | WordPress editor
Besides, some field types that are rarely used and we would not recommend using them because their UI is not as good and native as other fields.
Type | Key | Description
--- | --- | ---
Autocomplete | `autocomplete` | Text input that uses an autocomplete library to suggest user input. Not recommended. Use the Select or Select advanced field type instead.
Fieldset text | `fieldset_text` | Group of text inputs. Not recommended. Use the Group field type instead.
Text list | `text_list` | Group of text inputs. Similar to Fieldset text, but has a different UI. Not recommended. Use the Group field type instead.
:::warning
These are field types that use the built-in browser UI without extra libraries. The UI might be different across operating systems and browsers. Please use with care.
:::
Type | Key | Description
--- | --- | ---
Email | `email` | For entering an email address with browser validation
Number | `number` | For entering a number with browser validation
Range | `range` | A slider for selecting a number
URL | `url` | An input for URL with browser validation
These are field types that help you select a WordPress object.
Type | Key | Description
--- | --- | ---
Post | `post` | For selecting posts
Sidebar | `sidebar` | For selecting sidebars
Taxonomy | `taxonomy` | For selecting taxonomy terms. Does not save term IDs in post meta, but sets post terms.
Taxonomy advanced | `taxonomy_advanced` | For selecting taxonomy terms and saving term IDs in post meta as a comma-separated string. It does not set post terms.
User | `user` | For selecting users
These are field types that help you upload media files.
Type | Key | Description
--- | --- | ---
File | `file` | Simple file upload with default UI like ``. Not recommended. Use File advanced instead.
File advanced | `file_advanced` | Multiple file uploads with WordPress media popup
File input | `file_input` | A text input for entering a file URL with the ability to select a file from the Media Library
File upload | `file_upload` | Multiple file uploads with a drag and drop area
Image | `image` | Simple image upload with default UI like ``. Not recommended. Use Image advanced instead.
Image advanced | `image_advanced` | Multiple image uploads with WordPress media popup, usually used for a gallery
Image upload | `image_upload` | Multiple image uploads with a drag and drop area
Single image | `single_image` | Single image upload with WordPress media popup
Video | `video` | Multiple video uploads with WordPress media popup
These are field types that help you organize and improve the UI of the fields.
Type | Key | Description
--- | --- | ---
Divider | `divider` | Simple horizontal line
Heading | `heading` | Heading text
Group | `group` | For creating nesting groups of fields. Requires [MB Group](/extensions/meta-box-group/) extension.
Tab | `tab` | For organizing fields in tabs. Requires [MB Tabs](/extensions/meta-box-tabs/) extension.
### Field settings
Each field contains settings to determine where and how data is loaded and saved. All fields share some common settings, but also offer unique settings per field type. There are also settings from extensions which are explained on each extension docs.
Below is the list of settings with a brief description. The keys are for reference in code.
Name | Key | Description
--- | --- | ---
Label | `name` | Field label. Optional. If empty, the field input is 100% width.
ID | `id` | Field ID. Required and must be unique. **It will be used as `meta_key` when saving to the database**. Use only numbers, letters, and underscores (and rarely dashes).
Type | `type` | Field type. Required.
Label description | `label_description` | Label description, displayed below the field label. Optional.
Input description | `desc` | Field description, displayed below the field input. Optional.
Default value | `std` | Default value. Optional.
Placeholder | `placeholder` | Placeholder text for the input or select box. Optional.
Required | `required` | Whether the field is required (`true` or `false`). Optional. Default `false`.
Disabled | `disabled` | Whether the field is disabled (`true` or `false`). Optional. Default `false`.
Read only | `readonly` | Whether the field is read only (`true` or `false`). Optional. Default `false`.
Multiple | `multiple`|Does the field have multiple values (like the `select` field)? Optional. Default `false`.
Cloneable | `clone` | Is the field clonable (repeatable)? `true` or `false`. Optional. Default `false`.
Sortable | `sort_clone`|Ability to drag-and-drop reorder clones (`true` or `false`). Optional. Default `false`.
Clone default value | `clone_default`|Clone the default value of fields? `true` or `false` (default).
Clone as multiple | `clone_as_multiple`|Whether to store clone values in multiple rows in the database? Optional. Default `false`.
Max number of clones | `max_clone`|Maximum number of clones. Optional. Default `0` (unlimited).
Min number of clones | `min_clone`|Minimum number of clones. Optional. Default `0`.
Add more text | `add_button`|The text for **Add more** clone button. Optional. Default "+ Add more".
Name | Key | Description
--- | --- | ---
Before | `before` | Custom HTML outputted before field's HTML.
After | `after` | Custom HTML outputted after field's HTML.
Custom CSS class | `class` | Custom CSS class, in case you want to customize the field. Optional.
Custom sanitize callback | `sanitize_callback` | Custom PHP callback for sanitizing field value before saving into the database. Set it to `none` to bypass the sanitization. See [more details](/sanitization/).
Save field value | `save_field` | Whether to save field value. Optional. Default `true`. This option does not work in the block editor (Gutenberg).
Hide from block bindings? | `hide_from_block_bindings` | Hide this field from the block editor bindings UI. Optional. Default `false`. See [more details](/block-bindings/).
Custom HTML5 attributes | `attributes` | Custom attributes for inputs. See [more details](/custom-attributes/).
Validation | `validation` | Validation rules for fields. Optional. See [more details](/validation/).
Custom settings | N/A | Custom field settings, useful when you want to add your settings to fields.
:::tip Field ID prefix
You can add a prefix to field IDs to prevent using the same ID with other scripts. If you want to hide the fields in the default WordPress **Custom Fields** meta box, use underscore (`_`) as the prefix.
:::
### Field-specific settings
Besides all common settings, each field type can have its own settings. Please see more details for each field type on the left menu.
:::tip Code examples
To save time reading and writing settings for fields, we have already prepared some code examples that you can get from [Meta Box Code Snippet Library](https://github.com/wpmetabox/library/).
:::
### Shorthand syntax
For **text** field type, you can omit the `type` settings, like this:
```php
add_filter( 'rwmb_meta_boxes', function ( $meta_boxes ) {
$meta_boxes[] = [
'title' => 'Event details',
'post_types' => 'event',
'fields' => [
[
'name' => 'Date and time',
'id' => 'datetime',
'type' => 'datetime',
],
// highlight-start
[
'name' => 'Location',
'id' => 'location',
],
// highlight-end
[
'name' => 'Map',
'id' => 'map',
'type' => 'osm',
'address_field' => 'location',
],
],
];
return $meta_boxes;
} );
```
And if the `id` of the field can be auto-generated from the field name, you can omit it and **define the field as a simple string**:
```php
add_filter( 'rwmb_meta_boxes', function ( $meta_boxes ) {
$meta_boxes[] = [
'title' => 'Event details',
'post_types' => 'event',
'fields' => [
[
'name' => 'Date and time',
'id' => 'datetime',
'type' => 'datetime',
],
// highlight-next-line
'Location',
[
'name' => 'Map',
'id' => 'map',
'type' => 'osm',
'address_field' => 'location',
],
],
];
return $meta_boxes;
} );
```
## Video tutorial
This video shows you all the field types and field settings:
## FAQ
The mechanism of `std` in Meta Box works only if the **field group has not been saved before**. It means all fields in that field group, not just the specific field that you set the `std` for. So if there is any field that already has value, then `std` will not work for other fields, even new fields you have just added.
Examples:
When you create a new post, then no fields have values (of course), then `std` works for all fields.
When you edit an existing post that has a field group, then some fields might have values. Therefore, `std` does not work for all fields. In this case, if you edit the field group and add a new field, `std` still does not work for that new field (even it has no value before), because the field group has been saved before.
There are some situations where the context does not work as expected. That is probably because you have dragged and dropped the field groups to reorder them. If you have, then WordPress will save the position/location of them and use the saved position instead of the value in the `context` parameter. The order of field groups is saved in the user meta `meta-box-order_{screen id}` as follows:
In this case, deleting this user meta from the database will make the context work again.
# Creating new field types
If the existing Meta Box field types do not quite fit your needs, you can create your own. In this guide, we will walk through how to create a custom field type called `phone`, which only accepts phone numbers in the format `xxx-xxx-xxxx`.
## 1. Create a new field class
All custom fields in Meta Box are defined as classes. To create a new field type, define a class named `RWMB_{$field_type}_Field` that extends the base `RWMB_Field` class. For our `phone` field, the class name will be `RWMB_Phone_Field`.
```php
class RWMB_Phone_Field extends RWMB_Field {
// Code for the field goes here
}
```
Save this class into a PHP file (for example: `field-phone.php`) and include it in your theme's `functions.php` file or in your custom plugin:
```php
add_action( 'init', function () {
require 'path/to/field-phone.php';
} );
```
:::info Why use the `init` hook?
We hook into `init` to make sure all Meta Box files are fully loaded and the `RWMB_Field` class is available.
:::
## 2. Output the field HTML
To display the field so users can enter data, define the `html` method inside your field class:
```php
public static function html( $meta, $field ) {
return sprintf(
'',
$field['field_name'],
$field['id'],
$meta
);
}
```
Here we are using the `pattern` attribute to ensure that users enter a phone number in the format `xxx-xxx-xxxx`.
:::info
Good news: you do not need to handle saving, retrieving, or enqueueing scripts/styles manually. Meta Box takes care of that automatically.
:::
Full class example:
```php
class RWMB_Phone_Field extends RWMB_Field {
public static function html( $meta, $field ) {
return sprintf(
'',
$field['field_name'],
$field['id'],
$meta
);
}
}
```
:::info Inherited methods
This class inherits all methods from the `RWMB_Field` class. See the **method reference** below for details.
:::
## 3. Add the field to the builder (optional)
If you want to use your custom field in the [builder](/extensions/meta-box-builder/), you need to register it via the `mbb_field_types` filter:
```php
use MBB\Control;
add_filter( 'mbb_field_types', function ( $field_types ) {
$field_types['phone'] = [
'title' => __( 'Phone', 'your-text-domain' ),
'icon' => 'phone',
'category' => 'advanced',
'controls' => [
'name', 'id', 'type', 'label_description', 'desc',
Control::Select( 'icon_type', [
'label' => __( 'Icon type', 'your-text-domain' ),
'options' => [
'dashicons' => __( 'Dashicons', 'your-text-domain' ),
'fontawesome' => __( 'Font Awesome', 'your-text-domain' ),
'url' => __( 'Custom URL', 'your-text-domain' ),
],
], 'dashicons' ),
Control::Input( 'icon', [
'label' => __( 'Icon', 'your-text-domain' ),
'dependency' => 'icon_type:dashicons',
] ),
Control::Input( 'icon_fa', [
'label' => '' . __( 'FontAwesome icon class', 'your-text-domain' ) . '',
'dependency' => 'icon_type:fontawesome',
] ),
Control::Input( 'icon_url', [
'label' => __( 'Icon URL', 'your-text-domain' ),
'dependency' => 'icon_type:url',
] ),
'clone_settings',
'before', 'after', 'class', 'save_field', 'sanitize_callback', 'attributes', 'custom_settings',
],
];
return $field_types;
} );
```
This code registers a `phone` field type under the **Advanced** category with several available controls.
When you click **+ Add field** in the builder, it will appear like this:
**Field type parameters:**
The `mbb_field_types` filter accepts a single parameter: an associative array of field types. Each type supports these parameters:
- `title`: The field type's display title.
- `icon`: The icon for the field (Dashicons only).
- `category`: The inserter popup category (options: `basic`, `advanced`, `html5`, `wordpress`, `upload`, `layout`).
- `controls`: The available controls in the builder. These can be:
- Simple strings (`name`, `id`, `type`).
- Control objects like `MBB\Control::Input` or `MBB\Control::Select`.
Each control has a specific type and several parameters:
1. Setting name
1. Control properties, which is an array:
- `label`: Control label text.
- `tooltip`: Helper text shown as a tooltip.
- `options`: For select-type controls, in the format `'value' => 'label'`.
- `dependency`: Show this control only when another control has a certain value (e.g. `{$other_control_setting_name}:{$value}`). Optional.
1. Default value. Optional.
1. Settings tab: `general` (default), `appearance`, or `advanced`. Optional.
In case your control has only `label` property, you can set the property as a string.
**Supported control types:**
| Control Type | Description |
| -------------------------- | -------------------------------------------------------------------------- |
| `MBB\Control::Checkbox` | A simple checkbox. |
| `MBB\Control::Input` | A text input. Add `'type' => 'number'` to accept only numbers. |
| `MBB\Control::Select` | A single-select dropdown. Requires an `options` array. |
| `MBB\Control::ReactSelect` | A multi-select dropdown. Requires `options`, and default must be an array. |
| `MBB\Control::Textarea` | A textarea input. |
## 4. Use the new field
Once registered, you can use the new `phone` field type like any other:
```php
add_filter( 'rwmb_meta_boxes', function ( $meta_boxes ) {
$meta_boxes[] = [
'title' => 'Profile',
'post_types' => 'speaker',
'fields' => [
'Name',
// highlight-start
[
'name' => 'Hotline',
'id' => 'hotline',
'type' => 'phone',
],
// highlight-end
],
];
return $meta_boxes;
} );
```
When you edit a post, you will see the new field:
:::info
For more complex fields, you can override additional methods from the `RWMB_Field` class. You may want to enqueue scripts, styles, or sanitize values before saving. See the **methods reference** below for details.
:::
:::warning Cloneable fields
If your field should support [cloning](/cloning-fields/), make sure your inputs have a CSS class starting with `rwmb`. The cloning script automatically detects these inputs and updates their `id` and `name` attributes correctly.
:::
## `RWMB_Field` Class Methods
All methods in `RWMB_Field` (and child classes) are **static**. This design improves performance by reusing the same code for all fields instead of creating new instances.
Here is a quick overview of the most important methods:
### `add_actions`
This method allows a field to add custom hooks for its needs. For example: callbacks for ajax call ([like `file`](https://github.com/wpmetabox/meta-box/blob/master/inc/fields/file.php#L36)), add hooks to output custom content in admin footer ([like `file_advanced`](https://github.com/wpmetabox/meta-box/blob/master/inc/fields/media.php#L51)), etc. This method is called when the meta box is loaded. You can also add custom code to this method or calls to other functions which need to run when code is loaded. This method does not have any arguments.
### `admin_enqueue_scripts`
This method allows you to enqueue scripts and styles for a field. This method does not have any arguments.
### `show`
This method outputs the field's HTML markup. Fields should **not** overwrite this method to output custom HTML. Instead of that, overwrite methods `html`, `begin_html`, `end_html` described below. This method has 2 arguments:
- `$field`: array of field arguments
- `$saved`: a param used to detect whether this meta box is saved into database or not
- `$post_id`: the current post ID
### `html`
This method returns (not echoes, only returns) field's HTML markup. This is the input controls of the field and is put inside `.rwmb-input` CSS class. Each field **must** overwrite this method to return its HTML for inputs. This method has 2 arguments:
- `$meta`: field meta value
- `$field`: array of field arguments
### `begin_html`
This method returns the beginning HTML output of a field. The beginning HTML output contains field name and opening tag for inputs. By default it is:
```php
```
This method should **not** be overwritten by field's class, unless it is needed to do so ([like `heading` field](https://github.com/wpmetabox/meta-box/blob/master/inc/fields/heading.php#L27)). This method has 2 arguments:
- `$meta`: field meta value
- `$field`: array of field arguments
### `end_html`
This method returns the ending HTML output of a field. The ending HTML output contains clone button, field description and closing tag for inputs. By default it is:
```php
{$clone_button}
{$field_description}
```
This method should **not** be overwritten by field's class, unless it is needed to do so ([like `heading` field](https://github.com/wpmetabox/meta-box/blob/master/inc/fields/heading.php#L40)). This method has 2 arguments:
- `$meta`: field meta value
- `$field`: array of field arguments
### `meta`
This method retrieves meta value for a field. In most cases, this method does all the job of retrieving meta value of a field. But in some cases, a descendant class may overwrite this method to retrieve meta value for more complicated logic. This method has 3 parameters:
- `$post_id`: current post ID, from which we retrieve meta value
- `$saved`: a param used to detect whether this meta box is saved into database or not
- `$field`: array of field arguments
### `value`
This method sets field meta value before saving in database. By default it just returns the value from `$_POST`. Field class can overwrite this method to set meta value for more complicated logic ([like `taxonomy_advanced`](https://github.com/wpmetabox/meta-box/blob/master/inc/fields/taxonomy-advanced.php#L22)). This method has 4 parameters:
- `$new`: field meta value which will be saved in the database
- `$old`: old meta value of field
- `$post_id`: current post ID, from which we retrieve meta value
- `$field`: array of field arguments
### `save`
This method saves field meta value in database. In most cases, this method does all the job of saving meta value of a field to database. But in some cases, a descendant class may overwrite this method to handle saving itself ([like `taxonomy` field](https://github.com/wpmetabox/meta-box/blob/master/inc/fields/taxonomy.php#L194)). This method has 4 parameters:
- `$new`: field meta value which will be saved in the database
- `$old`: old meta value of field
- `$post_id`: current post ID, from which we retrieve meta value
- `$field`: array of field arguments
### `normalize_field`
This method normalizes field arguments, adds missing arguments, adds default value for fields, etc. Depending on field type, each field class can overwrite this method to define its own default value. This method has 1 parameter:
- `$field`: array of field arguments
# Custom attributes
With Meta Box, you can add custom attributes for inputs like text, URL, email field. This feature is very helpful if developers want to add HTML5 attributes or something like `data-*` attribute for their custom JavaScript code.
## How to add custom attributes to fields
To add custom attributes to the fields, click the **Advanced** tab in the field settings, and click the **Add New** button under **Custom HTML5 Attributes**:
Then add your attribute name and value.
:::info
The instruction above uses [MB Builder](/extensions/meta-box-builder/), an extension providing the UI to create fields, and is already bundled in [Meta Box Lite](https://metabox.io/lite/) and [Meta Box AIO](/extensions/meta-box-aio/). If you prefer to use code, please see below.
:::
Currently, this feature is supported in text, URL, email, checkbox, radio, date, time, datetime fields.
:::info Complex values
By default, custom attributes accept strings as keys and values. If you want to enter complex values, like array, please use the [dot notation](/extensions/meta-box-builder/#dot-notation) or [JSON notation](/extensions/meta-box-builder/#json-notation).
:::
## Adding custom attributes with code
Custom attributes are registered as an array `attributes` in the field settings, in format `'key' => 'value'` like this:
```php
'fields' => [
[
'name' => 'Username',
'id' => 'text',
'type' => 'text',
// highlight-start
'attributes' => [
'required' => true,
'minlength' => 10,
],
// highlight-end
],
],
```
If you want to add a custom `data-*` attribute, you can add it like this:
```php
'attributes' => [
// highlight-start
// Simple value
'data-option1' => 'value1',
// Array of values
'data-option2' => json_encode( ['key1' => 'value1', 'key2' => 'value2'] ),
// highlight-end
],
```
### Common attributes
There are several attributes that you can set under the `attributes` array, or directly in the field settings (e.g. outside the `attributes` array).
So, you can write like this:
```php
'fields' => [
[
'name' => 'Username',
'id' => 'text',
'type' => 'text',
// highlight-start
'attributes' => [
'required' => true,
'minlength' => 10,
],
// highlight-end
],
],
```
Or like this:
```php
'fields' => [
[
'name' => 'Username',
'id' => 'text',
'type' => 'text',
// highlight-start
'required' => true,
'minlength' => 10,
// highlight-end
],
],
```
Here is the list of common attributes:
- disabled
- required
- autofocus
- readonly
- maxlength
- minlength
- pattern
# Custom fields
After creating custom post types and custom taxonomies, you will need to add more details to your posts. For example, you will need "date" and "location" for the "event" post type. Such details are called custom fields and that is the main thing that Meta Box does for you.
## What are custom fields?
Custom fields, also called metadata, are arbitrary extra data attached to posts to provide more information about the posts.
Custom fields are a very important feature of WordPress and make WordPress a powerful CMS. You will see custom fields everywhere, for example:
- On a hotel booking website: custom fields are used to add information for address, rating, or price
- On an e-commerce website: they are used to add details for price, quantity, or size. FYI, WooCommerce uses custom fields to store this data.
## How to create custom fields?
To create custom fields, you should use the [**MB Builder**](/extensions/meta-box-builder/) extension to have an intuitive interface. This extension is already bundled in [**Meta Box Lite**](https://metabox.io/lite/) so you can use it right away.
Custom fields are organized in groups. Each group is displayed as a collapsible panel below the post editor.
Go to **Meta Box » Custom Fields** and click **Add New**. You will see a screen to add fields to the group:
Enter the field group title at the top and then click the **+ Add Field** button and select a field type to add to the group. Meta Box provides [40+ field types](/fields/) for all of your data types.
After that, a new field will appear in the field list. Clicking on the field bar will open the field settings panel in the left sidebar, where you can edit settings for the field, such as title or default value.
Each setting is clearly labeled, with tooltips available for extra guidance. To know more about field settings, please see [this docs](/field-settings/).
When finishing adding fields, click the **Settings** icon and select the post type where the fields are displayed for.
After that click the **Save Changes** button to finish.
Now go to your post type and add a new post. You will see the field group with custom fields displayed below the editor where you can enter the data you want:
In the case that you do not want to use [Meta Box Lite](https://metabox.io/lite/), you have two ways to have MB Builder:
* Get [MB Builder](https://metabox.io/plugins/meta-box-builder/) individually. In this case, the Meta Box plugin is required to be installed.
* Purchase a [premium plan](https://metabox.io/pricing/) to use **Meta Box AIO** that includes all extensions, including MB Builder.
:::info Do you know?
The technical term of field groups in WordPress is "meta box". You will see them via WordPress functions like `add_meta_box` or `remove_meta_box`. That is why we name our brand **Meta Box**!
:::
:::tip For developers
You can also [create custom fields with code](/creating-fields-with-code/), which is suitable if you want to keep everything in your themes or plugins.
:::
## Displaying fields
After having all the data for custom fields, it is time to show them on the front end.
We will display the event details for the event post type that we created in the previous steps for example. This is the single event page on the front end, and we will display the event details below the event description:
To do that, we will use the [MB Views](/extensions/mb-views/) extension, which offers a powerful and flexible way to select and display fields.
:::info Don't have a license?
MB Views is a premium extension and is available for [premium licenses](https://metabox.io/pricing/) only. If you do not own the right license, please purchase one.
:::
To begin, we need to create a "view". A "view" is a template where we show our fields. To create a view, go to **Meta Box » Views** and click **Add New** button.
On the edit view screen, enter the view title. To insert a field to the template, click the **Insert Field** button, which opens a panel with all the available fields:
You will see other WordPress fields as well such as post title or post content. For the custom fields we created, just choose one and click on its name on the list.
For some kinds of data, Meta Box may offer some options for the output. It will show a popup asking for the output format as follows:
Choose an output format from the dropdown and click the Insert button to insert the field to the template. After that, you will see the template now has the following text:
```html
{{ post.datetime | date( 'F j, Y' ) }}
```
That is the value of the field which will be displayed on the front end. However, displaying only text might be confusing, so we will add a label for it by adding the `Date and time:` before the text and wrap it in a paragraph (between `
` and `
` tags) to add some space. The template now looks like:
```html
Date and time: {{ post.datetime | date( 'F j, Y' ) }}
```
:::tip
You can use any HTML tags and/or WordPress shortcodes in the view template.
:::
Now repeat the process for other fields: location and map. For map, as it is displayed as an Open Street Maps, we will need to change the HTML a little bit to put it below the label:
Now you need to set up the view to display below the post content of the event page in the **Settings** box as follows:
Finally, click the **Publish** button to finish.
Now go to the event page on the front end and you will see the custom fields that we created:
:::info
If you use a page builder to display the data, you can refer to the [tutorials](https://docs.metabox.io/tutorials/builders/) for usage in real cases.
:::
:::tip For developers
You can also [display custom fields with code](/displaying-fields-with-code/), which is suitable if you want to keep everything in your themes or plugins.
:::
## Next steps
Now you know all the basics for working with custom fields in Meta Box. Depending on your needs, I would suggest you take a look at:
- [Advanced topics](/category/advanced/), or
- Explore the [field type gallery](/fields/) to know which fields are suitable for your needs, or
- Explore more features provided by [extensions](/extensions/)
If you have any questions, feel free to ask in the [support forum](https://support.metabox.io/) or discuss in the [Facebook community group](https://www.facebook.com/groups/metaboxusers).
Thanks for using Meta Box and happy building websites!
# Custom post types
import LiteYouTubeEmbed from 'react-lite-youtube-embed';
import 'react-lite-youtube-embed/dist/LiteYouTubeEmbed.css';
When building a website, there may be sections such as events and projects where the content and appearance are very different from posts and pages. That is when you need custom post types.
## What are custom post types?
Custom post types are different types of content in WordPress. You should consider creating a custom post type for a particular content type if:
- It needs to be displayed differently from posts and pages, or
- It does not look and feel like a post or a page, or
- It needs some additional fields and characteristics
## How to create a custom post type?
Creating custom post types is done easily with the [MB Custom Post Types & Custom Taxonomies](/extensions/mb-custom-post-type/) extension. This extension is already bundled in [Meta Box Lite](https://metabox.io/lite/), [Meta Box AIO](/extensions/meta-box-aio/), or you can install it for free from [WordPress.org](https://wordpress.org/plugins/mb-custom-post-type/).
To create a new custom post type, go to **Meta Box** » **Post Types** » **New Post Type**:
There are several settings divided into tabs. In most cases, you only need to enter the plural name, singular name, and slug in the **General** tab and click the **Publish** button to register the post type.
:::info Settings
To understand the settings in detail, [see the docs](/extensions/mb-custom-post-type/#post-type-settings) for the MB Custom Post Types & Custom Taxonomies extension.
:::
## Creating custom taxonomies
When you have a lot of posts of a custom post type, you might want to categorize them. For example, categorize music albums by genre or artist. To categorize posts like that, you need custom taxonomies.
Taxonomies in WordPress are a mechanism for grouping posts, like category and tag. In the example above, "genre" and "artist" are custom taxonomies for the custom post type "music album".
To create a new custom taxonomy, go to **Meta Box » Taxonomies** and click **Add New**:
There are several settings divided into tabs. In most cases, you only need to enter the plural name, singular name, and slug in the **General** tab and click the **Publish** button to register the taxonomy.
:::info Settings
To understand the settings in detail, [see the docs](/extensions/mb-custom-post-type/#taxonomy-settings) for the MB Custom Post Types & Custom Taxonomies extension.
:::
## Video tutorial
The video below shows you the steps and explains the settings for a custom post type and a custom taxonomy:
## Next steps
After creating a custom post type, [add custom fields](/custom-fields/) to add more details for posts of that post type! That is the most important part of the whole process and is the heart of Meta Box.
# Custom Select / Checkbox Tree
If you have used the [taxonomy field](/fields/taxonomy/), you will see it has an option to display options in a checkbox / select tree. When users select a parent item, it will show children items. It is quite a nice feature for users. But how to do that with normal checkbox list or select field types?
The answer is simple: it is already supported. You need to register options for these fields with code like this:
```php
add_filter( 'rwmb_meta_boxes', function ( $meta_boxes ) {
$meta_boxes[] = [
'title' => 'Test',
'fields' => [
[
'type' => 'select_tree', // or checkbox_list
'id' => 'cb',
'name' => 'Hierarchical checkboxes',
'options' => [
[ 'value' => 'value1', 'label' => 'label 1' ],
[ 'value' => 'value2', 'label' => 'label 2' ],
// highlight-start
[ 'value' => 'sub1', 'label' => 'Sub 1', 'parent' => 'value1' ],
[ 'value' => 'sub2', 'label' => 'Sub 2', 'parent' => 'value1' ],
// highlight-end
],
'placeholder' => 'Select an item',
'flatten' => false,
],
],
];
return $meta_boxes;
} );
```
To enable select/checkbox tree, you need to:
- Set the option in format of `[ 'value' => 'Your value', 'label' => 'Your label' ]`
- For child items, add `'parent' => 'parent_value'`
- Set `'flatten' => false` for the field
- Set the field type `checkbox_list` if you want a checkbox tree or `select_tree` if you want a select tree.
# Database
Wondering how the Meta Box stores custom fields in the database? Understanding this can help you get the custom fields easily and understand the returned value from `get_post_meta` or helper functions.
## How fields are saved in the database?
In general, each custom field is saved as **one row** in the database, where the field `id` will be the `meta_key` and the value will be the `meta_value` in the meta table. This is the same way that WordPress saves data with `add_post_meta` or `update_post_meta` function.
- If you use [custom tables](/extensions/mb-custom-table/), the field value will be saved in the column with the name equal to the field `id`.
- If you create a field for a [settings page](/extensions/mb-settings-page/), the whole data for the settings page will be saved as an array in an option in the format of `['field_id' => 'field_value']`.
The sections below describe how field values are formatted.
## Non-cloneable fields
For non-cloneable fields, the plugin stores field value in the database in a WordPress-compatible way as follows:
- If a field has a single value, it will be saved in a single row in the post meta table.
- If a field has multiple values (set by `'multiple' => true` like `select`, `checkbox_list`, `file`, `image`, etc.), each value will be saved in a single row in the post meta table.
This way you can use `add_post_meta` or `update_post_meta` to update meta values and `get_post_meta` to retrieve them.
## Cloneable fields
For cloneable fields, values are stored as a serialized array in a single row in the database, unless you set `'clone_as_multiple' => true`.
Using serialized data has some benefits:
- Works for all field types, including nested groups.
- Works perfectly with the helper function or with WordPress's `get_post_meta` function (WordPress automatically unserializes string and returns an array).
- Reduces the database size (number of rows), especially when you have nested groups of many fields.
However, serialized data has a big disadvantage: **you cannot query posts by serialized values**.
For example, if you have a cloneable field `start_date` for the `event` post type, and you want to query events in May 2019 like this:
```php
$args = [
'post_type' => 'event',
'meta_query' => [
[
'key' => 'start_date', // This field is cloneable
'value' => ['2019-05-01', '2019-05-31']
'compare' => 'BETWEEN',
],
],
];
$query = new WP_Query( $args );
```
Then it does not work.
To solve this problem, you need to enable the **Clone as multiple** settings for the field.
With that, Meta Box will **save cloneable values in multiple rows in the database**, where each row contains one value. That means if `start_date` has 2 values `['2019-05-01', '2019-04-30']`, it will be saved in 2 rows in the database, one for `2019-05-01` and one for `2019-04-30`. The data is **not serialized** anymore. And thus, your above query will work!
# Displaying fields with code
import FAQ from '@site/src/components/FAQ';
If you are a developer and familiar with changing template file with PHP code, you can use Meta Box helper functions to display fields:
- [`rwmb_get_value()`](/functions/rwmb-get-value/): to get a field value as a variable
- [`rwmb_the_value()`](/functions/rwmb-the-value/): to display a field
In addition, we also provide [`rwmb_meta()`](/functions/rwmb-meta/) function, which is a wrapper of the 2 functions above which:
- Returns the HTML output for rich-content fields: `map`, `osm`, and `oembed`, same as `rwmb_the_value()`,
- Returns the same value as `rwmb_get_value()` for other field types.
Now open your template file for the single event content. Usually, it is `template-parts/content.php`, `single-event.php` or `single.php` file, depending on your theme structure. Then add the following code below the content area:
```php
>
', '' ); ?>
// highlight-start
Date and time:
Location:
Map:
// highlight-end
```
:::warning Block themes
For block themes, everything is blocks and there are no PHP template files. In that case, please use the [MB Views](/extensions/mb-views/) extension.
:::
All functions accept the following parameters:
Name|Description
---|---
`$field_id`|The field ID. Required.
`$args`|Extra arguments for some field types (image, file, etc.). Can be array or a string in format `param1=value1¶m2=value2`. See more details in field types. Optional.
`$object_id`|Object ID that custom fields are got from. Optional. If not present, the current post ID is used.
`$echo`|Echo the HTML output (`true` - default) or return it (`false`). Applied only for `rwmb_the_value()` function.
## FAQ
If you are using our helper functions in your theme, then they become unavailable when Meta Box is deactivated. You can fix that by going to the admin area » Plugins and re-activate Meta Box.
Alternatively, you can add the following code into your theme's `functions.php` file to make the error go away. However, the custom fields will not display, either.
```php
if ( ! function_exists( 'rwmb_the_value' ) ) {
function rwmb_the_value( $key, $args = [], $post_id = null ) {
return null;
}
}
if ( ! function_exists( 'rwmb_get_value' ) ) {
function rwmb_get_value( $key, $args = [], $post_id = null ) {
return null;
}
}
if ( ! function_exists( 'rwmb_meta' ) ) {
function rwmb_meta( $key, $args = [], $post_id = null ) {
return null;
}
}
```
Absolutely. Our helper function is just a wrapper of WordPress's `get_post_meta` function.
There are some cases where you register custom fields conditionally or only for the back end like you wrap the code under `is_admin()`. In that case, make sure you remove the condition and register custom fields for both the back end and front end.
Absolutely. We have official support for Beaver Builder and Elementor. Some page builders already have built-in support for Meta Box like Oxygen Builder, Bricks, and Brizy. See the [list of compatible plugins](/integrations/) and refer to their docs for how to use them with Meta Box.
# Edit meta boxes
When you use a WordPress theme or plugin which [integrates Meta Box](/bundling/), all the information of fields and meta boxes are fixed, such as: meta box title, number of fields, fields' names and descriptions, ... How to change these texts or add/remove fields of an existing meta box or even remove a meta box?
Assuming we have 2 meta boxes registered in a parent theme:
```php
add_filter( 'rwmb_meta_boxes', 'prefix_register_meta_boxes' );
function prefix_register_meta_boxes( $meta_boxes ) {
// 1st meta box
$meta_boxes[] = array(
'id' => 'personal',
'title' => 'Personal Information',
'fields' => array(
array(
'name' => 'Name',
'id' => 'name',
'desc' => 'Enter your full name: First Last',
'type' => 'text',
),
array(
'name' => 'Occupation',
'id' => 'occupation',
'desc' => 'What do you do?',
'type' => 'text',
),
),
);
// 2nd meta box
$meta_boxes[] = array(
'id' => 'address',
'title' => 'Address Info',
'fields' => array(
array(
'name' => 'Street',
'id' => 'street',
'type' => 'text',
),
array(
'name' => 'City',
'id' => 'city',
'type' => 'text',
),
array(
'name' => 'State',
'id' => 'state',
'type' => 'text',
),
),
);
return $meta_boxes;
}
```
which are rendered as following:
We want to:
- Remove "Personal Information" meta box
- Change title of "Address Info" meta box to "Address"
- Add description for field "Street" in "Address" meta box
- Add field "zip_code" (text field) to "Address" meta box
Our custom code will be put in `functions.php` file of the child theme.
The principle is simple as following:
- Hook to `rwmb_meta_boxes` filter with a high priority to get all registered meta boxes
- Then we check meta boxes by ID or title to get the meta boxes we want to edit / remove
- Remove or change meta boxes information if needed (such as meta box title)
- For that meta box, we loop through all custom fields and change fields' info
- And finally add more fields to that meta box if needed
The code is quite straight as following (with all necessary comments):
```php
// Priority 20 makes sure all meta boxes are already registered
add_filter( 'rwmb_meta_boxes', 'prefix_edit_meta_boxes', 20 );
function prefix_edit_meta_boxes( $meta_boxes ) {
// Loop through all meta boxes to find the ones we need
foreach ( $meta_boxes as $k => $meta_box ) {
// Remove "Personal Information" meta box
if ( isset( $meta_box['id'] ) && 'personal' == $meta_box['id'] ) {
unset( $meta_boxes[$k] );
}
// Edit "Address Info" meta box
if ( isset( $meta_box['id'] ) && 'address' == $meta_box['id'] ) {
// Change title to "Address"
$meta_boxes[$k]['title'] = 'Address';
// Loop through all fields
foreach ( $meta_box['fields'] as $j => $field ) {
// Add description for "Street" field
if ( 'street' == $field['id'] ) {
$meta_boxes[$k][$j]['desc'] = 'Enter street address';
}
}
// Add field "zip_code" to this meta box
$meta_boxes[$k]['fields'][] = array(
'name' => 'Zip code',
'id' => 'zip_code',
'type' => 'text',
);
}
}
// Return edited meta boxes
return $meta_boxes;
}
```
Here is the result:
:::tip
It is recommended to set meta box ID to make it easier to loop through all meta boxes.
:::
# Extensions
Learn about Meta Box extensions, what features they offer and how to use them.
## User Interface
[ MB Custom Post Types](/extensions/mb-custom-post-type/)
[ MB Builder](/extensions/meta-box-builder/)
[ MB Views](/extensions/mb-views/)
[ MB Columns](/extensions/meta-box-columns/)
[ MB Tabs](/extensions/meta-box-tabs/)
[ MB Tooltip](/extensions/meta-box-tooltip/)
[ MB Admin Columns](/extensions/mb-admin-columns/)
[ MB Conditional Logic](/extensions/meta-box-conditional-logic/)
[ MB Include Exclude](/extensions/meta-box-include-exclude/)
[ MB Show Hide](/extensions/meta-box-show-hide/)
[ MB Text Limiter](/extensions/meta-box-text-limiter/)
[ MB Template](/extensions/meta-box-template/)
[ Meta Box AIO](/extensions/meta-box-aio/)
# Field settings
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
Each field contains settings to determine where and how data is loaded and saved. All fields share some common settings, but also offer unique settings per field type. There are also settings from extensions which are explained on each extension docs.
Below is the list of common field settings with a brief description. The keys are for reference in code.
Name | Key | Description
--- | --- | ---
Label | `name` | Field label. Optional. If empty, the field input is 100% width.
ID | `id` | Field ID. Required and must be unique. **It will be used as `meta_key` when saving to the database**. Use only numbers, letters, and underscores (and rarely dashes).
Type | `type` | Field type. Required.
Label description | `label_description` | Label description, displayed below the field label. Optional.
Input description | `desc` | Field description, displayed below the field input. Optional.
Default value | `std` | Default value. Optional.
Placeholder | `placeholder` | Placeholder text for the input or select box. Optional.
Required | `required` | Whether the field is required (`true` or `false`). Optional. Default `false`.
Disabled | `disabled` | Whether the field is disabled (`true` or `false`). Optional. Default `false`.
Read only | `readonly` | Whether the field is read only (`true` or `false`). Optional. Default `false`.
Multiple | `multiple`|Does the field have multiple values (like the `select` field)? Optional. Default `false`.
Cloneable | `clone` | Is the field clonable (repeatable)? `true` or `false`. Optional. Default `false`.
Sortable | `sort_clone`|Ability to drag-and-drop reorder clones (`true` or `false`). Optional. Default `false`.
Clone default value | `clone_default`|Clone the default value of fields? `true` or `false` (default).
Clone as multiple | `clone_as_multiple`|Whether to store clone values in multiple rows in the database? Optional. Default `false`.
Max number of clones | `max_clone`|Maximum number of clones. Optional. Default `0` (unlimited).
Min number of clones | `min_clone`|Minimum number of clones. Optional. Default `0`.
Add more text | `add_button`|The text for **Add more** clone button. Optional. Default "+ Add more".
Hide from front end | `hide_from_front`|Whether to hide the field from front-end submission forms. Required the [MB Frontend Submission](https://metabox.io/plugins/mb-frontend-submission/) extension to work.
Hide from REST API | `hide_from_rest`|Whether to hide the field from REST API responses. Required the [MB REST API](https://metabox.io/plugins/mb-rest-api/) extension to work.
Name | Key | Description
--- | --- | ---
Before | `before` | Custom HTML outputted before field's HTML.
After | `after` | Custom HTML outputted after field's HTML.
Custom CSS class | `class` | Custom CSS class, in case you want to customize the field. Optional.
Custom sanitize callback | `sanitize_callback` | Custom PHP callback for sanitizing field value before saving into the database. Set it to `none` to bypass the sanitization. See [more details](/sanitization/).
Save field value | `save_field` | Whether to save field value. Optional. Default `true`. This option does not work in the block editor (Gutenberg).
Hide from block bindings? | `hide_from_block_bindings` | Hide this field from the block editor bindings UI. Optional. Default `false`. See [more details](/block-bindings/).
Custom HTML5 attributes | `attributes` | Custom attributes for inputs. See [more details](/custom-attributes/).
Validation | `validation` | Validation rules for fields. Optional. See [more details](/validation/).
Custom settings | N/A | Custom field settings, useful when you want to add your settings to fields.
# Field types
Learn about field types, what they are and when you should use them.
## Basic
# Hide Tabs with Conditional Logic
Conditional Logic works with any DOM elements. That means you can hide your tabs created by [MB Tabs](/extensions/meta-box-tabs/) extension with MB Conditional Logic. This guide shows you how to do that.
## Basic
Because tabs are not regular fields or meta boxes, you have to use `rwmb_outside_conditions` filter to tell Conditional Logic to add this element. Imagine that you have created a meta box like this:
```php
add_filter( 'rwmb_meta_boxes', function($meta_boxes) {
$meta_boxes[] = array(
'title' => 'MB Tabs 2',
'tabs' => array(
'bio' => 'Biography',
'interest' => 'Interest',
),
'tab_style' => 'box',
'fields' => array(
array(
'name' => 'Bio',
'id' => 'bio',
'type' => 'textarea',
'tab' => 'bio',
),
array(
'name' => 'Interest',
'id' => 'interest',
'type' => 'textarea',
'tab' => 'interest',
),
),
);
return $meta_boxes;
});
```
This will generate a meta box with two tabs `Biography` and `Interest`. And here is the HTML output:
```html
```
If you want to hide a tab, just add its class to `rwmb_outside_conditions` filter. For example, if I want to hide `Interest` tab when post format is `aside`, add these lines:
```php
add_filter( 'rwmb_outside_conditions', function( $conditions ) {
$conditions['.rwmb-tab-interest'] = array(
'hidden' => array( 'post_format', 'aside' ),
);
return $conditions;
} );
```
This will tell Conditional Logic to hide `.rwmb-tab-interest` selector when `post_format` is `aside`
## Hide the first tab
In case you want to hide the first tab, you have to hide its tab pane also and show the next tab pane. This example shows you how to do that:
```php
add_filter( 'rwmb_outside_conditions', function( $conditions ) {
$conditions['.rwmb-tab-bio, .rwmb-tab-panel-bio'] = array(
'hidden' => array( 'post_format', 'aside' )
);
$conditions['.rwmb-tab-panel-interest'] = array(
'visible' => array( 'post_format', 'aside' )
);
return $conditions;
} );
```
# HTML5 Input Types
## Overview
In addition to the [supported field types](/fields/), Meta Box also supports all HTML5 input types, such as `url` and `tel`. You can start using them without writing any extra code.
## What is HTML5 input types?
[HTML5 input types](http://html5doctor.com/html5-forms-input-types/) are types for the text input that are added to the HTML5 and are supported by all browsers. They act similar to `text` input, but for other data types, such as URL, email or date. Using HTML5 input types has some benefits:
- You have built-in UI like the arrow up/down for `number` or a picker for date/time/week. The UI is various in different browsers, but it works. It also supports mobile devices.
- You have built-in validation. If users enter invalid data (for `url` or `email`), the browser will throw an error.
- Finally, you have a semantic markup
Here is the list of HTML5 input types that you can use:
Input Type | Description
---|---
`search`|Search input field
`email`|Email input field, which has validation for email
`url`|URL input field, which has validation for URL (e.g. must starts with `http`)
`tel`|Telephone input field
`number`|Number input field, which has up/down arrows to increase/decrease the number.
`range`|Range input field, which allows you select a number by dragging a control.
`month`|Month input field, which has the built-in UI for picking a month
`week`|Week input field, which has the built-in UI for picking a week
`datetime-local`|Datetime input field, which has the built-in UI for picking a date and time with the local timezone
Please note that some types such as `date`, `datetime`, `time` and `color` are already implemented with different UI. So they are not available as the custom HTML5 input types anymore.
## Using HTML5 input types with Meta Box
Using HTML5 input types with Meta Box is as simple as `text` field. All you need to do is **set the `type` attribute** of the field to the corresponding HTML 5 input type.
For example, the code below creates a `tel` field:
```php
[
'id' => 'field_id',
'type' => 'tel', // New HTML 5 input type
'name' => 'Telephone',
]
```
That is it.
In order to customize the field, you might want to add some [custom attributes](/custom-attributes/) to the input such as `size`, `pattern`. Even without custom attributes, the field works just fine and you will benefit from all things that HTML5 provides.
# Include Exclude vs Show Hide vs Conditional Logic
We have 3 extensions that can help you control the visibility of a meta box for a certain post/page:
- [MB Include Exclude](/extensions/meta-box-include-exclude/)
- [MB Show Hide](/extensions/meta-box-show-hide/)
- [MB Conditional Logic](/extensions/meta-box-conditional-logic/)
That might be confusing as you do not know which extension is the right choice for you. So the main difference between them is the following: **MB Include Exclude** hides meta boxes **by PHP**, meaning:
- Meta boxes are removed completely from the editing screen, no HTML markup is outputted at all
- Since meta boxes are removed completely, there are no inputs at all and thus, there are no meta values are saved at all
- There is no way to show the meta boxes again unless reloading the page
Both **MB Conditional Logic** and **Show Hide** hide meta boxes **by Javascript**, meaning:
- The HTML of meta boxes are outputted, inputs are only hidden and the meta values are submitted when saving post and are saved in the database
- You can show them without reloading the page
The **MB Conditional Logic** differs from [Show Hide](/extensions/meta-box-conditional-logic/): it has **more advanced options** which allows you to show/hide not only meta boxes but also fields and specific HTML elements. The Show/Hide extension can show/hide only meta boxes. Besides, the number of conditions in Conditional Logic are more than Show/Hide extension (greater, less than, not equal, etc.).
# Installation
import FAQ from '@site/src/components/FAQ';
## Requirements
To run Meta Box, we recommend:
- PHP 7.4 or greater
- Latest version of WordPress
Meta Box also works with PHP 7.0 and older versions of WordPress. These versions have reached the official end of life and may expose your site to security vulnerabilities.
## Installing Meta Box
Meta Box offers [three different versions](/introduction/#meta-box-overview), each with slightly different installation steps.
We recommend using [**Meta Box Lite**](https://metabox.io/lite/), a free version with essential features and a user-friendly interface.
Here is how to install it:
1. Go to [our website](https://metabox.io/lite/), fill in your email, and download it.
2. Go to **Plugins** > **Add New Plugin** > **Upload Plugin**.
3. Upload the downloaded file and click **Install Now**.
Then, click **Activate** to start using Meta Box Lite. You can see it in the admin dashboard.
:::info
For advanced features, buy a [premium plan](https://metabox.io/pricing/), and install the **Meta Box AIO** plugin with all extensions (both free and paid).
:::
## Next steps
You have everything ready!
As most WordPress websites require custom post types, [learn how to create them](/custom-post-types/).
## FAQ
Yes, **Meta Box Lite** is 100% free. It includes Meta Box, [MB Builder](/extensions/meta-box-builder/), and all free extensions. This gives you the tools to create and manage dynamic content at no cost.
No, **Meta Box Lite** already includes Meta Box. There is no need to install it separately.
# Introduction
## What is Meta Box?
When you use WordPress as a CMS (not just for blogging), you need more than just posts and pages. For example, to show events on your website, you need a content type called "event" with some fields to store event details such as date and location. In WordPress, we call them [custom post type](/custom-post-types/) and [custom field](/custom-fields/). To create custom post types and custom fields, you need a plugin like Meta Box.
Meta Box is a framework that helps you create custom post types and custom fields quickly and easily. A framework provides all the tools you need to manage data and build features for your WordPress websites. It saves you time and lets you focus on business logic.
Meta Box provides powerful features [via extensions](/extensions/). These include front-end form submission, post relationships, custom table storage, conditional logic, Gutenberg blocks, and integrations with many third-party plugins.
Whether you are a WordPress user or developer, Meta Box is a toolkit that grows with you. We help you boost your productivity and workflow. We cannot wait to see what you build.
## Why Meta Box?
There are many plugins for working with custom fields. We believe Meta Box is the best choice for building a performant and full-featured website.
**Easy for everyone**
With a user-friendly interface, low-code features, and built-in snippets, you can work with Meta Box easily even if you are not a developer.
**Full-featured**
Meta Box offers the most complete set of features among custom fields plugins. Whatever you need, Meta Box has it for you.
**Lightweight & fast**
Being thoroughly optimized for code and data storage, Meta Box never impacts your website speed or performance.
**Extensibility**
With APIs and actions, filters in many necessary places, you can change how to display fields, change data, or do other things like sending emails.
Learn more about [Meta Box philosophy](/philosophy/).
## Meta Box overview
Meta Box has 3 versions:
* **Meta Box**: the foundation and framework of all [extensions](https://docs.metabox.io/extensions/) and features. You can add individual extensions (free or premium) to have advanced features. It has no UI and suits developers only, who need to use code.
* [**Meta Box Lite**](https://metabox.io/lite/): a single free UI version of Meta Box. It includes the Meta Box plugin, [MB Builder](/extensions/meta-box-builder/), and all the free extensions to create custom post types, custom taxonomies, custom fields, and relationships.
* [**Meta Box AIO**](https://metabox.io/aio/): a single premium plugin. It includes the Meta Box plugin and all the extensions (both free and premium). Meta Box AIO lets you install only one plugin and have everything from Meta Box, so the plugin list stays short and clean.
In short, if you are a free user, use Meta Box Lite. For paid users, use Meta Box AIO!
Now you know about Meta Box, [start using it](/installation/)!
# Local JSON
Besides [creating fields with PHP](/creating-fields-with-code/), you can also register custom fields with JSON. This way is more convenient and easier to manage the fields since you can put them in a separate file, use version control (Git), use caching, and get better code editor support with JSON schema.
This feature is available in the [Meta Box Builder](https://metabox.io/plugins/meta-box-builder/) extension and is included in both [Meta Box Lite](https://metabox.io/lite/) and [Meta Box AIO](https://metabox.io/aio/).
## How it works
To use local JSON to register custom fields, you need to create a new folder called `mb-json` in your theme that is writable by the web server.
After that, you can put the JSON files in the folder and Meta Box will automatically load the JSON files and register the fields, with no more database queries.
## JSON format
The JSON format is the same as when you export a field group and is very similar to the [PHP version](/creating-fields-with-code/) when you create a field group, except the `$schema` and `modified` attributes:
```json
{
"$schema": "https://schemas.metabox.io/field-group.json",
"title": "Event details",
"post_types": "event",
"fields": [
{
"name": "Date and time",
"id": "datetime",
"type": "datetime"
},
{
"name": "Location",
"id": "location",
"type": "text"
},
{
"name": "Map",
"id": "map",
"type": "osm",
"address_field": "location"
}
],
"modified": 1739955432
}
```
We use a **JSON schema** so you can take advantage of the code editor's auto-completion feature (like in VSCode). In the JSON file, you need to set the `$schema` attribute as follows:
```json
https://schemas.metabox.io/field-group.json
```
## Syncing changes
Meta Box will automatically discover **new** or **updated** JSON files in the `mb-json` folder and display them in the **Sync available** tab, showing the status of the JSON files, where you can sync JSON to the database, so you can edit the fields visually, and then sync back to the JSON file.
Before syncing, you can also review the changes by clicking on the **Review** link.
:::info Detecting changes
When you change the content of a JSON file, and want Meta Box to detect the change to show the **Sync available** status, you have to **increase the `modified` attribute** in the JSON file. This attribute stores the last update time in timestamp.
:::
After syncing, you will see the field group in the admin list like this:
Then you can change the field group, add more fields or edit existing fields. You can save changes to the JSON file just by saving the field group in the WordPress admin. The JSON file will be updated automatically. Please note that deleting a field group in the admin will also delete the JSON file.
:::warning Purpose
Syncing from JSON to the database has only one purpose: to edit fields visually, and then sync back to JSON files (or export to JSON file to save somewhere else). Meta Box will **NOT** load fields from the database (to avoid making unnecessary queries), and use JSON files only.
:::
## Adding custom folders
By default, the plugin will look for the JSON files in the `mb-json` folder in the active theme. You can add custom folders to load JSON files by using the `mb_json_paths` filter. Here is an example:
```php
add_filter( 'mb_json_paths', function( $paths ) {
$paths[] = '/path/to/your/folder';
$paths[] = '/path/to/your/folder2'; // Another folder
return $paths;
} );
```
## Security
It is a good practice to hide the JSON files from the public. The easiest way to do that is adding an `index.php` file to the folder. This way, when people try to access the folder, they will see a blank page.
```php
Add New** to see the result!
## Conclusion
**Online Generator** is a great tool for WordPress beginners and developers to generate custom meta boxes and custom fields for the [Meta Box plugin](https://metabox.io/). It saves you a lot of time with a friendly UI and lets you build a bunch of fields without touching code.
It works as a stand-alone tool, meaning that it cannot be put inside your WordPress admin. Instead, you can copy the generated code and paste it into your theme's functions.php file.
In the case that you want to use it inside your WordPress admin and have extra settings for fields or [premium extensions](https://metabox.io/plugins/), do not forget to try [MB Builder](https://docs.metabox.io/extensions/meta-box-builder/).
Besides using the generator for the custom fields, you may want to have custom post types and custom taxonomies. So, **Meta Box** also provides several WordPress generator tools such as [WordPress Custom Post Type Generator](https://metabox.io/post-type-generator/), and [WordPress Custom Taxonomy Generator](https://metabox.io/taxonomy-generator/). Or, you can use the [MB Custom Post Type plugin](https://metabox.io/plugins/custom-post-type/) to create custom post type and custom taxonomy inside your website. It is free and available on [wordpress.org](https://wordpress.org/plugins/mb-custom-post-type/).
Let us try it and give us your feedback.
# Philosophy
## Plugins-As-Libraries
Meta Box is created as a library to help WordPress users work with custom post types and custom fields easier. As a library, it has some uniqueness:
- It is very lightweight and contains only what is really needed.
- It can be [used in other themes or plugins](/bundling/) to provide the functionality needed for the themes or plugins.
- Extra functionality is provided by extensions, which can be installed as libraries as well.
:::warning No admin menu?
Because Meta Box is a library, the **free version** has no admin pages for configuration or settings. Instead, it provides an API that you can use to speed up the process of creating meta boxes and custom fields. Developers need to [use code](/creating-fields-with-code/) to create custom fields.
For normal users and beginners, we recommend using the [Meta Box Lite](https://metabox.io/lite/), which includes a UI to build custom fields inside WordPress. If you are a premium user, you can use the [Meta Box AIO](https://metabox.io/aio/), which includes all the extensions and a UI to build custom fields inside WordPress.
:::
## Modular
Meta Box is modular, which means each functionality is separated into an extension. Each extension is a WordPress plugin and can be installed and used independently or together. Extensions can also be used as libraries and you can [bundle them](/bundling/) in your themes or plugins.
The modularity keeps all the extensions as minimal as possible and keeps Meta Box not bloated.
:::tip
If you are afraid of a long plugin list, use our Meta Box AIO or MB Core, which are available for premium users. They contain all extensions in one plugin and you can enable or disable each extension easily. This shortens the plugin list while still providing all the needed functionality.
:::
## Performance
Performance is our top priority. Everything in Meta Box is considered carefully to perform well on large sites with hundreds of thousands of records. Because of this, we try hard to optimize code and follow WordPress coding standards as well as best coding practices.
Meta Box is lightweight, fast, clean, and will always stay that way.
## Flexibility
Built for both developers and normal WordPress users, we offer a powerful set of options to build and customize WordPress sites with custom post types and custom fields. People have choices to work with Meta Box via code or UI, from the back end to the front end, with or without other plugins like page builders.
Everything in Meta Box can be customized with a comprehensive list of [actions](/category/actions/) and [filters](/category/filters/). Developers can also extend Meta Box to [create new field types](/creating-new-field-types/), build [plugins and awesome stuff](https://github.com/wpmetabox/awesome-meta-box).
# Post Type Generator
[Post Type Generator](https://metabox.io/post-type-generator/) is a free online tool to help you create and set up custom post types easily with a simple and intuitive user interface. With this tool, you can copy and paste PHP code for custom post types in a few clicks.
One notable feature of this tool is that it can be used independently from Meta Box. Therefore, you do not need to install the Meta Box to use Post Type Generator.
## Set up a New Custom Post Type
### Set up General Options
After opening this tool [here](https://metabox.io/post-type-generator/), fill in the basic information for your new custom post type like **Plural name, Singular name** and **Slug** in the **General** tab. The **Function name** and **Text domain** already have default values, but you can change them as well.
### Set up Labels
The **Labels** tab lets you enter the labels of your post types that will show up in the Admin Dashboard.
### Set up Advanced Options
In the **Advanced** tab, the description of each field will help you set up some advanced options for your post types display.
Pay attention to some fields:
- **Publicly queryable?** If you tick the box, it can query to take the data of your post type so that the content of it can be displayed on the front end.
- Similarly, put a tick to the **Show UI?** and **Show in nav menus?** if you want to show your post type UI and show your post type in nav menus in the Dashboard. It is recommended to enable them for easy management.
- **Hierarchical?** If you want your post type to have a parent post type and sub post type to sort and manage it conveniently, enable this.
For more details about all the fields in this tab, please read [this instruction](https://developer.wordpress.org/reference/functions/register_post_type/) from WordPress.
### Set up Supports and Taxonomies
In the **Supports** tabs, you can choose which elements to display in the WordPress Editor when editing your custom post types.
In the **Taxonomies** tab, the two default WordPress taxonomies are listed here. Choose which kind of taxonomy to be included in your post type.
## Generate Code and Insert It to the Functions.php File
When you complete all the steps above, click the **Generate Code** button. Just wait a moment and the code will show up right under the button.
Copy the code and insert it to the `functions.php` file and it is all done.
# Reorder posts & terms
This feature lets you **drag and drop** posts (from any custom post type) or terms (from any custom taxonomy) to rearrange their order right inside the WordPress admin. It is perfect when you need a custom order that does not follow the default publish date or alphabetical sorting.
This functionality is included in the **[MB Custom Post Types & Custom Taxonomies](/extensions/mb-custom-post-type/)** extension - completely free to use.
## Reordering posts
To enable this feature, open your custom post type settings, switch to the **Features** tab, and turn on the **Re-Order Posts** option:
If you are registering the post type via code, simply add:
```php
'order' => true,
```
Once enabled, you will see a new **Re-Order** tab in the post type's admin menu. Click it and rearrange your posts using drag-and-drop.
### Hierarchical post type support
Reordering works smoothly with hierarchical post types. When you move a parent post, all of its child posts automatically follow - similar to how fields in a group move together.
### Frontend display
Your custom order is applied automatically on all archive pages or anywhere you query that post type.
### Reorder posts of other post types
By default, the plugin supports reordering posts of the post types created by Meta Box. If you want to apply this feature to other post types that are built-in WordPress (like `post` or `page`) or created by other plugins or themes, use this snippet:
```php
add_filter( 'mbcpt_post_type_reorderable', function( $enable, $post_type ) {
if ( $post_type = 'your-post-type' ) {
return true;
}
return $enable;
}, 10, 2 );
```
## Reordering terms
To reorder taxonomy terms, go to **Meta Box → Taxonomies**, open your taxonomy settings, and enable the feature in the **Features** tab:
Or enable it via code:
```php
'order' => true,
```
After that, visit the taxonomy screen and click the **Re-Order** button to sort terms using drag-and-drop - including **hierarchical terms**.
Ordered terms also appear exactly in the same sequence in the post editor:
### Reorder terms of other taxonomies
By default, the plugin supports reordering terms of the taxonomies created by Meta Box. If you want to apply this feature to other taxonomies that are built-in WordPress (like `category` or `tag`) or created by other plugins or themes, use this snippet:
```php
add_filter( 'mbcpt_taxonomy_reorderable', function( $enable, $taxonomy ) {
if ( $taxonomy = 'your-taxonomy' ) {
return true;
}
return $enable;
}, 10, 2 );
```
# Sanitization
import FAQ from '@site/src/components/FAQ';
To ensure the user input is safe to save to the database, Meta Box provides a mechanism to sanitize fields' values. The sanitization is automatically applied for all built-in field types. For some fields such as select or radio, Meta Box also validates the submitted value to ensure it is a valid value (e.g. available in the field options).
The sanitization is applied for both single and cloneable fields. With cloneable fields, sanitization is applied for each cloned value.
## Default sanitize callbacks
We try to provide appropriate callbacks for built-in field types and use built-in WordPress sanitization functions as much as possible.
To see the list of default sanitize callbacks, please [see the plugin source code](https://github.com/wpmetabox/meta-box/blob/master/inc/sanitizer.php#L50).
:::warning
- **Textarea field**: Meta Box **removes all scripts and iframes** from the value. If you want to enter scripts (like Google Analytics) or embed videos, then you need to disable sanitization. See below for details.
- **Choice fields**: Meta Box validates the input to make sure it is in the field options.
- **[Groups](/extensions/meta-box-group/)** are not sanitized due to their complexity.
:::
## Bypass the sanitization
If you do not want to sanitize the input value for a specific field (we do not encourage this, obviously), then go to the **Advanced** tab and set **Custom sanitize callback** to "none":
In this case, whatever users input will be saved.
:::info
The instruction above uses [MB Builder](/extensions/meta-box-builder/), an extension providing the UI to create fields, and is already bundled in [Meta Box Lite](https://metabox.io/lite/) and [Meta Box AIO](/extensions/meta-box-aio/). If you prefer to use code, please see below.
:::
If you use code, then set `'sanitize_callback' => 'none'` in the [field settings](/field-settings/):
```php
[
'type' => 'text',
'id' => 'amount',
'name' => 'Amount',
// highlight-next-line
'sanitize_callback' => 'none',
]
```
## Custom sanitize callback
To provide a custom sanitize callback for a field, please enter a function name to the **Custom sanitize callback** settings in the **Advanced** tab when editing a field.
And do not forget to define the function in your theme or plugin.
The code below uses code to define a custom sanitize callback that auto adds a currency symbol "$" to a text field if it is missed:
```php
add_filter( 'rwmb_meta_boxes', function( $meta_boxes ) {
$meta_boxes[] = [
'title' => 'Test Sanitization Money Field',
'fields' => [
[
'type' => 'text',
'id' => 'amount',
'name' => 'Amount',
// highlight-next-line
'sanitize_callback' => 'my_sanitize_money_field',
]
],
];
return $meta_boxes;
} );
// highlight-start
function my_sanitize_money_field( $value, $field, $old_value, $object_id ) {
if ( 0 !== strpos( $value, '$' ) ) {
$value = '$' . $value;
}
return $value;
}
// highlight-end
```
The sanitize callback is passed 4 parameters as follows:
Parameter|Description
---|---
`$value` | The submitted value
`$field` | The field settings
`$old_value` | The old value which is in the database
`$object_id` | The current object ID
## Sanitizing subfields in a group
Because the group field saves its value in the database as a serialized array, to sanitize subfields, we need to put the `sanitize_callback` function for the outer group and use it to check the values of subfields:
```php
'fields' => [
[
'name' => 'My group',
'id' => 'my_group_id',
'type' => 'group',
// highlight-next-line
'sanitize_callback' => 'my_subfield_validation',
'fields' => [
[
'name' => 'Text',
'id' => 'text',
'type' => 'text',
],
[
'name' => 'Textarea',
'id' => 'textarea',
'type' => 'textarea',
],
],
],
],
```
The returned value of the sanitize callback is the group value, e.g. an array of subfield values.
```php
function my_subfield_validation( $group ) {
if ( empty( $group['text'] ) ) {
$group['text'] = 'Hello World!';
}
return $group;
}
```
## FAQ
Probably you are trying to save a script like Google Analytics or an embedded video. Meta Box removes all these things during sanitization. To save them, please disable sanitization for the field. See the "Bypass the sanitization" section for details.
# Save WYSIWYG content as post content
Sometimes you want to move the traditional editor for the post to another location, probably inside a meta box. It will keep everything more organized. For example, if you have an event post type, then you might have the following data:
- Start date and time
- End date and time
- Venue
- Description
- Gallery
Then keeping the description (which can be the post content) along with other fields makes it easier for users to fill in the data. While this is impossible to do with the default WordPress editor, we can do that with the [Meta Box](https://metabox.io) plugin. The steps to do that are described below:
1. Remove the default editor (we do not want to display it at the top)
1. [Create a new wysiwyg field](/fields/wysiwyg/)
1. Set that field to take the post content as the value
1. Save that field content into post content
The code is quite straightforward as below:
```php
// Remove the editor. Change 'post' to your custom post type.
add_action( 'init', function () {
remove_post_type_support( 'post', 'editor' );
} );
add_filter( 'rwmb_meta_boxes', function ( $meta_boxes ) {
// Get the current post content and set as the default value for the wysiwyg field.
$post_id = filter_input( INPUT_GET, 'post', FILTER_SANITIZE_NUMBER_INT );
$post_content = get_post_field( 'post_content', $post_id );
$meta_boxes[] = [
'title' => 'Test',
'post_types' => 'post', // Change 'post' to your custom post type.
'fields' => [
// Register a wysiwyg field of which the content is saved as post content.
[
'type' => 'wysiwyg',
'name' => 'Fake content',
// highlight-start
'id' => 'content',
'std' => $post_content,
'save_field' => false,
// highlight-end
],
// Custom style to overwrite the editor style set by WordPress.
[
'type' => 'custom_html',
'std' => '',
],
],
];
return $meta_boxes;
} );
// Set the value for the 'content' field.
add_filter( 'rwmb_content_field_meta', function() {
$post_id = filter_input( INPUT_GET, 'post', FILTER_SANITIZE_NUMBER_INT );
return get_post_field( 'post_content', $post_id );
} );
```
There are 2 important things in the code above:
1. To make Meta Box save the wysiwyg content to post content, we have to set it `'id' => 'content'`. This `id` is used to tell WordPress to get the submitted value and save it to post content.
1. Because we use the WordPress's id for the field, some WordPress styles are applied and make the field look weird. We have to use a `custom_html` field to output some CSS to fix it. Note that you might want to enqueue another stylesheet to do the same job. Here we use the `custom_html` for the quick fix, it just works.
The code above works for `post`. If you want to make it work for another post type, do not forget to change the post type in the code above!
# Shortcode
Besides [normal ways](/custom-fields/#displaying-fields) to display fields on the website, Meta Box also provides a simple shortcode `[rwmb_meta]` to help you show custom fields in the post content or widgets easily.
```php
[rwmb_meta id="field_id" object_id="15"]
```
## Attributes
Attribute|Description
---|---
`id`|The field ID. Required.
`object_id`|The object ID. Optional. If not defined, then the current object ID is used.
`attribute`|Get a single attribute from the field value (such as URL of the image or term slug). The field value is get with the [rwmb_get_value()](/functions/rwmb-get-value/) helper function. This works only when the value is an array.
`render_shortcode`|Whether to render inner shortcodes inside the value of the field. For example, if you enter a shortcode in a textarea/editor field, this attribute will render that shortcode and return the rendered content. Default true.
This shortcode works exactly like the [rwmb_the_value()](/functions/rwmb-the-value/) function with the same parameters.
:::tip Other attributes
You can pass **other attributes** to the shortcode if you want. If you do so, those attributes will be passed to the [rwmb_the_value()](/functions/rwmb-the-value/) function as the 2nd parameter.
:::
## Examples
**Getting the value of a text field:**
```php
[rwmb_meta id="phone"]
```
**Getting image URL (`single_image`):**
```php
[rwmb_meta id="company_logo" attribute="url" size="thumbnail"]
```
**Getting a term meta:**
```php
[rwmb_meta id="color" object_id="15" object_type="term"]
```
**Getting a settings:**
```php
[rwmb_meta id="phone" object_id="site_option" object_type="setting"]
```
**Getting a field value from a custom table:**
```php
[rwmb_meta id="area" object_id="15" storage_type="custom_table" table="properties"]
```
## Bypass HTML filtering
By default, the shortcode will be filtered by the `wp_kses_post()` function to remove all insecure HTML tags and attributes. If you want to bypass this filtering, you can use the `rwmb_meta_shortcode_secure` filter:
```php
add_filter( 'rwmb_meta_shortcode_secure', '__return_false' );
```
To bypass HTML filtering for a specific field, you can use the `rwmb_meta_shortcode_secure_{$field_id}` filter:
```php
add_filter( 'rwmb_meta_shortcode_secure_footer_script', '__return_false' );
```
# Status column
The status column lets you quickly switch the status of field groups, custom post types, custom taxonomies, settings pages, and relationships between Publish and Draft without opening each item individually. You can enable this feature for posts of a custom post type as well.
This feature adds a small toggle button directly to the management screen. Switch it **on** to publish, or **off** to save as a draft.
As a result, the traditional **Publish**/**Update** actions on the edit screens of field groups, custom post types, custom taxonomies, settings pages, and relationships are replaced with a single **Save Changes** button.
## Custom post types
To add a status column to the table of the post list of a custom post type, when you [create that post type](/custom-post-types/) with Meta Box, navigate to the **Features** tab, then enable the setting as below:
Then, you will see the Status column displayed. Turn the button on to publish or turn it off to save the post to a draft.
If your post type is not created by Meta Box, then you can use this filter to enable this feature for the post type:
```php
add_filter( 'mbb_toggle_status_post_types', function( $post_types ) {
$post_types[] = 'your-post-type-slug';
return $post_types;
} );
```
# Support policy
## Support channels
The official support channel is the [support forum](https://support.metabox.io), which is public. Only premium users can open a new topic. For free plugins, we also support via [WordPress.org support forum](https://wordpress.org/support/plugin/meta-box/).
There is also a [Facebook group](https://www.facebook.com/groups/metaboxusers), which is for community discussion, not for support.
We rarely support via email. Email is mostly used for sending private info. Please use the support forum first before sending us emails.
## Scope of support
We only support our plugins, not general WordPress issues (like custom post types, custom taxonomies, etc.). Our support includes plugin installation, configuration, update and use.
We do **not** support:
- Bugs that come from other plugins.
- Compatibility with other plugins, unless we have an extension for them.
- For plugins that officially support Meta Box, like Oxygen Builder, SearchWP, Admin Columns, ... please reach out to them if you have any issue with installation, configuration, compatibility, or usage.
- For other plugins that have no support for Meta Box, contact them to ask for Meta Box integration, or [let us know](https://metabox.io/contact/) so we can put it in our roadmap. We cannot promise or guarantee future integration.
- Customization for your specific needs.
- Custom development. We do custom development **as an outsourcing service** and are [available for hire](https://metabox.io/contact/).
## Support time
All questions will be answered within 24 hours.
We support during the working time from 8 AM to 5 PM in the ICT timezone (GMT+7), from Monday to Friday. For questions asked on the weekends or holidays, they will be answered in the next working day.
:::info Ready?
If you have any support question, open a topic on the [support forum](https://support.metabox.io). We will answer as soon as possible!
:::
# Taxonomy Generator
[Taxonomy Generator](https://metabox.io/taxonomy-generator/) is a free online tool to create custom taxonomy easily and quickly. You can use it without installing Meta Box.
## Set up a New Custom Post Taxonomy
### Set up General Options
Open this tool [here](https://metabox.io/taxonomy-generator/) and put the **Plural Name, Singular Name** and **Slug** of your custom taxonomy in the **General** tab. The **Function name** and **Text domain** already have default values, but you can change them as well.
### Set up Labels
The **Labels** tab lets you enter the labels of your custom taxonomy that will show up in the Admin Dashboard.
### Set up Advanced Options
In the **Advanced tab**, just read the description of each field. They will help you set up some advanced options for your custom taxonomy.
Remember that if you tick the box **Public?**, it can query to take the data of your custom taxonomy so that the content of it can be displayed on the front end.
For more detail about all the fields in this tab, please read [this instruction](https://developer.wordpress.org/reference/functions/register_taxonomy/) from WordPress.
### Set up Post Types Tab
The Post Types tab lists the two default post types **Post** and **Page** here. Just decide whether your custom taxonomy will display in your posts or pages.
## Generate Code and Insert It to the Functions.php File
When you complete all steps above, click the **Generate Code** button. Just wait a moment and the code will show up right under the button.
Copy the code and insert it to the `functions.php` file and it is all done.
# Tools
[Meta Box AIO](https://metabox.io/aio/) includes four tools that help you clean up and optimize your WordPress database. They focus on removing unused data, fixing field inconsistencies, and handling post types efficiently.
These tools let you:
* Remove orphaned custom field entries
* Delete data from unused or deleted field keys
* Migrate data from one field key to another
* Move posts from one post type to another
They act as a small maintenance toolkit to keep your database clean and running smoothly.
## Removing orphan fields
This tool **deletes custom field** that no longer belong to any post, term, or user. It helps you clean up leftover data and free your database with a single click.
## Removing custom fields
This tool helps you **remove all data for a specific custom field key across posts, terms, or users** when you delete fields you no longer use. It cleans up leftover data that would otherwise take up unnecessary space in your database.
## Changing custom field key
The **Change Custom Field Key** tool helps you migrate all data from an old custom field key to a new one when you rename a custom field (for example, from location to address), ensuring nothing is lost and your content stays consistent.
You will also get suggestions of existing field keys, making it easier to select and update.
## Changing post type
This tool helps you move posts to a different post type when a post type is disabled or removed.
For example, if the **Restaurant** post type is disabled, its posts remain in the database but are inaccessible. Using this tool, you can move them to **Post**, making them visible and usable again.
As a result, the posts in the Restaurant post type will be moved to Post.
Each tool is easy to use. Choose an option and click. Remember to back up your database before running them.
# Tutorials
[](/tutorials/create-custom-post-types-taxonomies/)
# Updates
import FAQ from '@site/src/components/FAQ';
Meta Box and all extensions can be updated automatically or manually. The automatic update uses the WordPress update mechanism, which checks for new versions twice a day. This is the recommended way to get new updates from our website.
## Automatic update
To enable automatic updates, you need a valid license key. Go to [My Account](https://metabox.io/my-account/) page to get it.
Then go to **Meta Box » License**, enter your license key and click **Save Changes** button.
From now on, when WordPress checks for new versions of plugins, it also checks for new versions of Meta Box extensions. If there is any new update, you will see this:
Then you can update the extensions the same way as for other plugins by clicking the **Update now** link.
## Manual update
You can also update the extensions manually by following these steps:
1. Go to [My Account](https://metabox.io/my-account/) page.
1. On your account page, you will see all downloads for your purchased extensions. Download the extension(s) to your computer, unzip the file and upload the extension folder to your website, overwriting the old files.
## FAQ
We cache the requests to check updates in a WordPress transient, which has a one-day lifetime. To force WordPress to check for updates, you need to remove this transient. To do that, install the [WP-Sweep](https://wordpress.org/plugins/wp-sweep/) plugin and clear all transients. Then go to **Dashboard » Updates** and click the **Check again** button.
You can define the license key in a constant in the `wp-config.php` file instead of storing it in the database. It might be more secure since no one can see it from the WordPress dashboard or in the database. To do that, define it via the `META_BOX_KEY` constant:
```php
define( 'META_BOX_KEY', 'ABCDEFGHIJKLMNOPQRSTUVWXYZ123456' ); // Your Meta Box license key.
```
# Using custom HTML to output anything
`custom_html` is a very useful field in Meta Box, which helps you to _output anything_ in the post edit screen. It can be a warning box or an instruction for users to help them enter the correct data. But do you know that **you can use PHP** to render the HTML for the field?
Using PHP, you can query the database, get WordPress information and show it. There is no limit with PHP. This guide helps you understand the field using a callback function to query the WordPress database and output the result. For the demo purpose: **I will set up a connection from a post to many pages (1 to many). And when editing a page, I need to know which posts refer to the current page**. So, creating a connection from a page to many posts is very simple with a field `post` like this:
```php
array(
'id' => 'page',
'name' => 'Page',
'type' => 'post',
'post_type' => 'page',
'multiple' => true,
),
```
To get the list of posts that refer to the current page, I will use a field `custom_html` like this:
```php
array(
'id' => 'posts',
'type' => 'custom_html',
'callback' => 'prefix_get_connected_posts',
),
```
Note the `callback` parameter: this callback refers to a custom PHP function (in this case `prefix_get_connected_posts`) which renders the content for the field. Implementing this function is quite easy as below:
```php
function prefix_get_connected_posts() {
if ( ! $page_id = filter_input( INPUT_GET, 'post', FILTER_SANITIZE_NUMBER_INT ) ) {
return '';
}
$output = '';
$posts = get_posts( [
'posts_per_page' => - 1,
'meta_key' => 'page',
'meta_value' => $page_id,
] );
foreach ( $posts as $post ) {
$output .= '
' : '';
}
```
And here is the result:
When editing a post:
When editing a page:
# Validation
Meta Box has a built-in validation module for all fields. You can use validation to make a field required, check password length, check phone number format, etc. The validation is done on the **client side**.
There are 2 ways of doing validation: basic validation with input attributes and advanced validation with jQuery validation plugin. You can choose which one fits your needs.
## Basic validation
Meta Box supports [custom attributes](/custom-attributes/) for all input fields. You can use these attributes to validate the values of fields.
:::warning
This type of validation uses browser validation, thus the UI and the error message depend on the browser (like language).
:::
When editing a field, switch to the **Advanced** tab, and scroll down to the **Custom HTML5 attributes**. Then click **Add New** button to add a new rule.
In the **Key** input box, you can select any rule from the dropdown (if you do not see the dropdown, press the down arrow button), or enter the attribute name manually. And then enter the desired value in the **Value** input box.
:::info
The instruction above uses [MB Builder](/extensions/meta-box-builder/), an extension providing the UI to create fields, and is already bundled in [Meta Box Lite](https://metabox.io/lite/) and [Meta Box AIO](/extensions/meta-box-aio/). If you prefer to use code, please see below.
:::
These are the available attributes that you can use for validation:
Attribute| Description
---|---
`max` | Maximum value
`maxlength` | Maximum number of characters
`min` | Minimum value
`minlength` | Minimum number of characters
`pattern` | Match a regular expression
`required` | Required
`step` | Match the step increment. Enter `any` to accept any step.
`type` | Mostly used as `url` or `email` to validate value as a valid URL or email
If you prefer to [use code to create fields](/creating-fields-with-code/), add pairs of `'key' => 'value'` rules for the field settings array:
```php
[
'type' => 'text',
'id' => 'phone',
'name' => 'Phone number',
// highlight-start
'required' => true, // Make the field required.
'pattern' => '[0-9]{9}', // Must have 9 digits
// highlight-end
]
```
## Advanced validation
For more advanced validation, including new rules and custom error messages, you might want to use the validation module, powered by the popular [jQuery validation plugin](https://jqueryvalidation.org/). It comes bundled with a useful set of validation methods and an API to write your own methods. All methods come with default error messages in English and translations into 37 other languages.
To define validation rules, switch to the **Advanced** tab, and scroll down to the **Validation**. Then click **Add New** button to add a new rule.
For each rule, the list of types is available as a dropdown, so you can select it. Depending on the rule type, you can enter a value and/or custom error message.
These are available validation rules that you can use:
Name|Description
---|---
`required` | Makes the element required
`minlength` | Makes the element require a given minimum length
`maxlength` | Makes the element require a given maximum length
`rangelength` | Makes the element require a given value range. Array.
`min` | Makes the element require a given minimum
`max` | Makes the element require a given maximum
`range` | Makes the element require a given value range. Array.
`email` | Makes the element require a valid email
`url` | Makes the element require a valid URL
`date` | Makes the element require a date
`dateISO` | Makes the element require an ISO date
`number` | Makes the element require a decimal number
`digits` | Makes the element require digits only
`creditcard` | Makes the element require a credit card number
`equalTo` | Requires the element to be the same as another one. Value must be the ID of another field.
`extension` | Makes the element require certain file extensions. For `file`, `image` fields only.
`accept` | Makes a file upload accept only specified mime-types. For `file`, `image` fields only.
`phoneUS` | Validate for valid US phone number
`remote` | Requests a resource to check the element for validity. Value can be the URL of the resource to request for server-side validation (string) or options to fully customize the request, see [jQuery.ajax](https://api.jquery.com/jQuery.ajax). The server-side resource is called via jQuery.ajax and gets a key/value pair corresponding to the name of the validated element and its value as a GET parameter. The response is evaluated as JSON and must be `true` for valid elements, and can be any `false`, `undefined` or `null` for invalid elements, using the default message. Or it can be a string, e.g. "That name is already taken, try peter123 instead" to display as the error message.
If you prefer code, you need to add a key `validation` to the [field group settings](/creating-fields-with-code/#field-group-settings). This key has a parameter `rules` for validation rules and `messages` for error messages.
```php
add_filter( 'rwmb_meta_boxes', function ( $meta_boxes ) {
$meta_boxes[] = [
'title' => 'Personal info',
'post_types' => 'team_member',
'fields' => [
[
'name' => 'Email',
'id' => 'email',
'type' => 'text',
],
[
'name' => 'Address',
'id' => 'address',
'type' => 'text',
],
],
// highlight-start
'validation' => [
'rules' => [
'email' => [
'required' => true,
'minlength' => 7,
],
// Rules for other fields
],
'messages' => [
'email' => [
'required' => 'Email is required',
'minlength' => 'Email must be at least 7 characters',
],
// Error messages for other fields
],
],
// highlight-end
];
return $meta_boxes;
} );
```
:::warning Fields with multiple inputs
The jQuery validation library actually uses the **input name**, not the input ID. In most cases, they are the same. But for some cases where a field has multiple inputs like a checkbox list, then the checkboxes do not have IDs.
In this case, **you need to use input name for the rules**. For example, if you use a taxonomy field displayed as a checkbox list, you should set validation rules as follows:
```php
'validation' => [
'rules' => [
// highlight-next-line
'my_taxonomy[]' => [
'required' => true,
],
],
'messages' => [
// highlight-next-line
'my_taxonomy[]' => [
'required' => 'You must select a tag to proceed',
],
],
],
```
For the field types "File" and "Image", the input name has the format `_file_fieldID[]`, you should set validation rules as follows:
```php
'fields' => [
[
'name' => 'Uploaded Files',
'id' => 'my_files',
'type' => 'file',
],
],
'validation' => [
'rules' => [
// highlight-next-line
'_file_my_files[]' => [
'extension' => 'pdf',
],
],
'messages' => [
// highlight-next-line
'_file_my_files[]' => [
'extension' => 'file extension not allowed',
],
],
],
```
:::
## Remote validation
Remote validation is supported by the jQuery validation library, which is used by Meta Box. Using remote validation helps you use server data (such as from a post or a setting) and return dynamic error messages.
To validate fields remotely with PHP, use the `remote` parameter for the validation rule array as follows:
```php
'validation' => [
'rules' => [
'field_id1' => [
// highlight-next-line
'remote' => admin_url( 'admin-ajax.php?action=my_action1' ),
],
],
'messages' => [
'field_id1' => [
// highlight-next-line
'remote' => 'Value is not valid.',
],
],
],
```
Please note that remote validation is only triggered when the field is changed so it is recommended to set the `required` rule to `true` to make sure the field is not empty before sending the request.
The validation performs via an ajax request with action `my_action1`. In your theme's `functions.php` file or your plugin, you need to create a callback to handle this ajax request that outputs:
- "true" if the value is valid
- "false" if the value is not valid. In this case, the error message is set in the `messages` array as above
- A custom string (not "false") if the value is not valid and you want to return it as a custom error message
```php
add_action( 'wp_ajax_my_action1', function () {
// Get the field value via the global variable $_GET
if ( $_GET['field_id1'] === 'something' ) {
echo 'true'; // Valid
} else {
echo 'false'; // Invalid
// or
// echo 'This value is invalid, please try again.'; // Custom error message
}
die;
} );
```
### Custom error message
As mentioned above, you can return a custom error message instead of `'false'` to display it as the error message sent from the server.
By default, the jQuery Validation library expects a JSON response from the server, any values that are not valid JSON will be ignored. So you will need to set the `dataType` parameter to `text` to return a custom error message.
```php
// AJAX callback
add_action( 'wp_ajax_my_action1', function () {
// Get the field value via the global variable $_GET
if ( $_GET['field_id1'] === 'something' ) {
echo 'true'; // Valid
} else {
echo 'This value is invalid, please try again.'; // Custom error message
}
die;
} );
```
```php
// Field settings
'validation' => [
'rules' => [
'field_id1' => [
'remote' => [
'url' => admin_url( 'admin-ajax.php?action=my_action1' ),
// highlight-next-line
'dataType' => 'text'
]
],
],
'messages' => [
'field_id1' => [
'remote' => 'Value is not valid.',
],
],
],
```
:::tip Other parameters
The `remote` parameter also accepts an array of options to fully customize the request, see [jQuery.ajax](https://api.jquery.com/jQuery.ajax).
:::
# rwmb_before
This action runs before all fields in a field group is displayed. It's usually used for outputting custom HTML.
```php
do_action( 'rwmb_before', $meta_box );
```
It takes 1 parameter: the instance of `RW_Meta_Box` class for the current field group.
To run this action for a specific field group, use a variation of this action:
```php
do_action( "rwmb_before_{$field_group_id}", $meta_box );
```
## Examples
This code wraps a field group with ID `event-details` into a custom div:
```php
add_action( 'rwmb_before_event-details', function( $meta_box ) {
echo '
';
} );
```
# rwmb_after
This action runs after all fields in a field group is displayed. It's usually used for outputting custom HTML.
```php
do_action( 'rwmb_after', $meta_box );
```
It takes 1 parameter: the instance of `RW_Meta_Box` class for the current field group.
To run this action for a specific field group, use a variation of this action:
```php
do_action( "rwmb_after_{$field_group_id}", $meta_box );
```
## Examples
This code wraps a field group with ID `event-details` into a custom div:
```php
add_action( 'rwmb_before_event-details', function( $meta_box ) {
echo '
';
} );
```
# rwmb_before_save_post
This action runs before a field group is saved.
```php
do_action( 'rwmb_before_save_post', $object_id );
```
It takes 1 parameter: current object ID.
:::info
Although the action name is `rwmb_before_save_post`, it applies to all object types, including term, user, or setting. We keep the name for historical reasons.
:::
To run this action for a specific field group, use a variation of this action:
```php
do_action( "rwmb_{$field_group_id}_before_save_post", $object_id );
```
## Examples
**Changing a field value before saving:**
```php
add_action( 'rwmb_event-details_before_save_post', function() {
$_POST['location'] = 'United States';
rwmb_request()->set_post_data( $_POST );
} );
```
**Changing a field value based on another field value:**
```php
add_action( 'rwmb_event-details_before_save_post', function() {
if ( $_POST['event_type'] === 'festival' ) {
$_POST['event_start_time'] = '09:00';
$_POST['event_end_time'] = '17:00';
rwmb_request()->set_post_data( $_POST );
}
} );
```
:::info
When modifying the global `$_POST` data, note that for a **cloneable field** with `'start_clone' => true`, the original value is an array where index `0` is empty and actual values start from index `1`. When you call `rwmb_request()->set_post_data()`, this empty value at index `0` is removed and will not be saved to the database.
:::
# rwmb_after_save_post
This action runs after all fields in a field group are saved.
```php
do_action( 'rwmb_after_save_post', $object_id );
```
It takes 1 parameter: current object ID.
:::info
Although the action name is `rwmb_after_save_post`, it applies to all object types, including term, user, or setting. We keep the name for historical reasons.
:::
To run this action for a specific field group, use a variation of this action:
```php
do_action( "rwmb_{$field_group_id}_after_save_post", $object_id );
```
## Examples
**Combining values of 2 fields into another one:**
```php
add_action( 'rwmb_my-field-group_after_save_post', function( $object_id ) {
if ( isset( $_POST['field_1'] ) && isset( $_POST['field_2'] ) ) {
$value = $_POST['field_1'] . $_POST['field_2'];
update_post_meta( $object_id, 'field_combine', $value );
}
} );
```
**Saving a sub-field of a group into a separated custom field:**
This is helpful when you have a group of many fields and want to query posts by a sub-field. As the group value is serialized, querying by a sub-field is not possible. With this trick, you can do that.
```php
add_action( 'rwmb_event-details_after_save_post', function( $object_id ) {
$event = $_POST['event'];
$date = $event['date'];
update_post_meta( $object_id, 'event_date', $date );
} );
```
This way, you can query posts by `event_date`.
**Sending an email after saving a field group:**
```php
add_action( 'rwmb_event-details_after_save_post', function( $object_id ) {
$title = get_the_title( $object_id );
$event_date = get_post_meta( $object_id, 'event_date', true );
$subject = 'Event updated';
$body = "The following event is updated:\n\n
Title: $title\n\n
Date: $event_date";
$to = get_option( 'admin_email' );
wp_mail( $to, $subject, $body );
} );
```
# rwmb_after_save_field
This action runs after a field is saved.
```php
do_action( 'rwmb_after_save_field', $null, $field, $new, $old, $object_id );
```
It accepts the following parameters:
Name|Description
---|---
`$null`|Not used
`$field`|Field settings
`$new`|The new (submitted) field value
`$old`|The old field value
`$object_id`|The object ID
This action has variations:
- `rwmb_after_save_field`: apply to all fields
- `rwmb_{$field_type}_after_save_field`: apply to fields with a particular type
- `rwmb_{$field_id}_after_save_field`: apply to a field with a particular id
## Examples
**Logging all values of a field using another custom field:**
```php
add_action( 'rwmb_event_date_after_save_field', function ( $null, $field, $new, $old, $object_id ) {
$log = get_post_meta( $object_id, 'log_event_dates', true );
$log[] = $new;
update_post_meta( $object_id, 'log_event_dates', $log );
}, 10, 5 );
```
**Update another custom field based on a field value:**
```php
add_action( 'rwmb_event_date_after_save_field', function ( $null, $field, $new, $old, $object_id ) {
if ( $new < '2022-04-01' ) {
update_post_meta( $object_id, 'current_year', true );
}
}, 10, 5 );
```
# rwmb_enqueue_scripts
This action runs after all Meta Box scripts and styles are enqueued to allows developers to enqueue more scripts and styles.
```php
do_action( 'rwmb_enqueue_scripts', $meta_box );
```
It takes 1 parameter: the instance of `RW_Meta_Box` class for the current field group.
## Examples
This code enqueues a CSS file for a specific field group.
```php
add_action( 'rwmb_enqueue_scripts', function( $meta_box ) {
if ( $meta_box->id === 'event-details' ) {
wp_enqueue_style( 'event', get_template_directory_uri() . '/css/admin/event.css' );
}
} );
```
# MB ACF Migration
import LiteYouTubeEmbed from 'react-lite-youtube-embed';
import 'react-lite-youtube-embed/dist/LiteYouTubeEmbed.css';
MB ACF Migration extension helps you to migrate field groups and custom field data from Advanced Custom Fields (ACF) to Meta Box. It works with both free and pro versions of Advanced Custom Fields.
## Video tutorial
This is the walkthrough video created by David McCan that shows you how to migrate data from ACF to Meta Box:
## Backup the database
Before migrating data, make sure you have a backup of your database. During the migration process, because of the difference in [data format](/database/), the plugin will attempt to modify the existing data in custom fields created by ACF. We try to do it at a very minimum level and create a backup of fields for some specific cases, but it's still important to make a backup just in case something goes wrong.
## Migrate
Before migrating, make sure you keep Advanced Custom Fields, Meta Box (required) and extensions (optional) activated. To know which extensions you might need, please see the **How it works** section below. Normally, if you use Meta Box AIO and keep all extensions activated, you don't have to worry about this.
To migrate, go to **Meta Box > ACF Migration** and click the **Migrate** button.
The plugin will show the process of migrating. When it's done, you'll see the text "Done".
## How it works
MB ACF Migration tries to migrate all the following data from ACF to Meta Box. Please note that not all data types and settings in ACF have an equivalent in Meta Box. The plugin will try to migrate as much as it can. The details are explained below:
### Field groups
ACF field groups are migrated to Meta Box's field groups, which requires [MB Builder](/extensions/meta-box-builder/). Most of the field group settings are the same as in Meta Box.
:::warning
**We do not remove ACF field groups** after migration, for safety. Instead, we changed their status to 'Inactive'. You can remove them later after all the data is processed.
:::
For **field group locations**, the basic rules are already supported in Meta Box and extensions. You might need extensions such as:
- [MB Term Meta](/extensions/mb-term-meta/): If you set locations for taxonomies.
- [MB User Meta](/extensions/mb-user-meta/): If you set locations for users.
- [MB Comment Meta](https://metabox.io/plugins/mb-comment-meta/): If you set locations for comments.
- [MB Settings Pages](/extensions/mb-settings-page/): If you set locations for settings pages.
For "Blocks", although there's an [equivalent in Meta Box](/extensions/mb-blocks/), the data of blocks are stored in post content and hard to parsed and migrated, so it's ignored at the moment.
For other rules like "Page Type", "Widget", "Menu", "Menu Item", there's no equivalent in Meta Box and they will be ignored.
Besides, if you use complex locations, then you'll need [MB Include Exclude](/extensions/meta-box-include-exclude/) extension. Due to the difference in how plugins create rules, the plugin works the following way:
- If there's only one location group: the plugin will migrate all rules with operator `AND`.
- If there are multiple location groups: the plugin will take the first rule of each group and combine them with operator `OR`.
### Settings pages
ACF requires you to use code to register settings pages. In Meta Box, thanks to [MB Builder](/extensions/meta-box-builder/), you can create and manage settings pages with UI.
During the migration, the plugin will try to create settings pages with UI if you have settings pages registered with ACF.
### Custom fields data
Most ACF field types work well with Meta Box, such as text, radio, select, etc. However, there's still a difference in how plugins store values in the database. Because of that, we'll process as the following:
1. **Remove all extra keys** in the database. ACF stores an extra meta in the database for field reference. It has the format `_{$field_id}`. This is redundant and causes the database to bloat. We don't need them and thus, we remove them.
2. For **fields that have multiple values** such as gallery, select (with multiple options), ACF saves their values as serialized arrays. We'll migrate them multiple rows in the database (similar to what `add_post_meta` does with the last parameter `false`).
3. For **layout fields**, ACF saves values of each sub-fields in a row in the database. We'll migrate them into groups (which requires [MB Group](/extensions/meta-box-group/)).
Details are below:
Field type | Meta Box's equivalent
--- | ---
Gallery | Image advanced
Select | Select advanced if stylised UI is enabled, normal select otherwise
Checkbox | Checkbox list
Post, Page link, Relationship | Post. In the case of page link, it works only with a post is selected, archive links don't work.
Taxonomy | Taxonomy advanced
Google maps | A pair of address field - which is a text field, and a Google maps field
Group | Non-cloneable group. Requires [MB Group](/extensions/meta-box-group/).
Repeater | Cloneable group. Requires [MB Group](/extensions/meta-box-group/).
Flexible content | Cloneable group with 2 sub-fields: a select field for selecting a layout, and a non-cloneable group for data. Requires [MB Group](/extensions/meta-box-group/) and [MB Conditional Logic](/extensions/meta-box-conditional-logic/).
:::info Field backup
For these fields, as the data format is different, for the safety, we create a backup for each field value. The new field value is stored with the key `_acf_bak_{$field_id}`.
:::
However, the following field types are not supported, because there're no equivalent field types in Meta Box:
- Link
- Accordion
- Clone
For other field types, the data is untouched.
# MB Admin Columns
**MB Admin Columns** helps you display the custom fields' values in the table of the post list in the **All Posts** screen in the **back end**. It works with any custom post types and supports for terms and users as well (requires [MB Term Meta](/extensions/mb-term-meta/) and [MB User Meta](/extensions/mb-user-meta/) correspondingly).
Showing fields' values in the post table give users a better overview of the posts without going to edit each post. It saves you time verifying/viewing the data.
## Showing custom fields as admin columns
To show a custom field as an admin column, go to **Meta Box > Custom Fields** and edit a field group. Click on a field that you want to show as an admin column and turn on the option "Admin column":
More settings will appear below that let you customize the admin column for that field:
These settings are self-explained. We also add some tooltips next to the setting title to give you more information if needed. Here is the list of the settings with the explanation:
Name|Description
---|---
Column position|Where to show the column. You have to choose the placement (before, after, or replace) and a target column ID.
Column title|By default, the plugin shows the field name as the column title. If you want to change it, enter a custom text here.
Column content before|The content outputted before the field value.
Column content after|The content outputted after the field value.
Sortable|Whether the column is sortable.
Searchable|Whether the column is searchable.
Filterable|Whether the column is filterable. It's applied only to the taxonomy field, which allows you to filter posts by taxonomy terms.
Item link type|Whether to link the value to the post edit screen or post view on the front end.
:::info
The instruction above uses [MB Builder](/extensions/meta-box-builder/), an extension providing the UI to create fields, and is already bundled in [Meta Box Lite](https://metabox.io/lite/) and [Meta Box AIO](/extensions/meta-box-aio/). If you prefer to use code, please see below.
:::
## Using code
If you're a developer and prefer using code to register admin columns, then you need to set the `admin_columns` settings for the field. Below is a sample code to register admin columns for a post type `book`:
```php
add_filter( 'rwmb_meta_boxes', function ( $meta_boxes ) {
$meta_boxes[] = [
'title' => 'Book Info',
'post_types' => 'book',
'fields' => [
[
'name' => 'Cover',
'id' => 'cover',
'type' => 'image_advanced',
// highlight-start
'admin_columns' => [
'position' => 'before title', // Show before the 'Title' column
'link' => 'edit', // Link to the edit post screen
],
// highlight-end
],
[
'name' => 'Author',
'id' => 'book_author',
'type' => 'text',
// highlight-next-line
'admin_columns' => 'after title', // Show after the 'Title' column
],
[
'name' => 'Pages',
'id' => 'pages',
'type' => 'number',
// highlight-next-line
'admin_columns' => true, // Just show this column
],
],
];
return $meta_boxes;
} );
```
The `admin_columns` settings can be in one of 3 following formats:
1. A boolean `true`: to simply display the admin column.
1. A string "before title": to specify the column position. It accepts 2 words: the first one is the placement ("before", "after" or "replace") and the last one is the target existing column ID.
1. An array of advanced configurations, as below:
```php
'admin_columns' => [
'position' => 'after title',
'title' => 'Price',
'before' => '$',
'after' => ' USD',
'sort' => true,
'searchable' => true,
'filterable' => false,
'link' => 'edit',
'width' => '10%',
],
```
Key|Description
---|---
`position`|Specify where to insert the new column. It accepts 2 words: the first one is the placement ("before", "after" or "replace") and the last one is the target existing column ID.
`title`|Column title. Optional. Default is the field name.
`before`|Custom HTML outputted before the column content. Optional.
`after`|Custom HTML outputted after the column content. Optional.
`sort`|Whether to sort the column by meta value? Set to `true` to just enable sorting. Set to `numeric` to sort values as numeric. Default `false`.
`searchable`|Allow searching posts by meta value. Optional. Default `false`.
`filterable`|Allow filtering posts by the custom taxonomy. Applied only if the field is the `taxonomy` field. Default `false`.
`link`|Whether to link the value to the post edit screen (value `edit`) or post view on the front end (value `view`) or no link (`false`).
`width`|The column width.
Note that the `sort` parameter is used to sort displayed posts by altering the WordPress query. It works only with non-clonable and non-multiple fields.
## Custom admin columns
By default, the extension is made to work with fields created by Meta Box. However, there are situations where you want to make it work with non-custom fields by Meta Box. And that's possible. Follow the steps below (note that it requires some coding):
**Step 1: Creating a custom PHP class**
Create a new file `custom.php` (you can name it anything you want) in your plugin/theme folder where you need to extend the `\MBAC\Post` class:
```php
class Prefix_Custom_Admin_Columns extends \MBAC\Post {
public function columns( $columns ) {
$columns = parent::columns( $columns );
$position = 'after';
$target = 'title';
$this->add( $columns, 'column_id', 'Column Title', $position, $target );
// Add more if you want
return $columns;
}
public function show( $column, $post_id ) {
switch ( $column ) {
case 'column_id':
echo 'Column content';
break;
// More columns
}
}
}
```
The custom column(s) is added via the call `$this->add( $columns, 'column_id', 'Column Title', $position, $target );`. You can repeat that code to add as many columns as you want.
In the `show` function, you must add code to display the content of these columns.
**Step 2: Instantiating the class**
In your plugin main file or `functions.php` of your theme, add the following code to create an instance of the class above:
```php
add_action( 'admin_init', 'prefix_add_custom_columns', 20 );
function prefix_add_custom_columns() {
require_once 'custom.php';
$post_type = 'post';
new Prefix_Custom_Admin_Columns( $post_type, [] );
}
```
The call `new Prefix_Custom_Admin_Columns( $post_type, [] );` tells WordPress to add custom column(s) to `$post_type`. You can change this to another post type if you want.
# MB Blocks
import LiteYouTubeEmbed from 'react-lite-youtube-embed';
import 'react-lite-youtube-embed/dist/LiteYouTubeEmbed.css';
With the help of MB Blocks, WordPress developers are now able to create Gutenberg blocks using PHP only. There is no JavaScript configuration and build process. The plugin is also compatible with Full-Site Editing, so your blocks can be used to create templates in the FSE.
Here is a screenshot of a custom Gutenberg block (hero area) that's created using MB Blocks:
The preview of the block is displayed in the main content area while the block configuration is displayed on the right. This allows you to edit the block content and live-preview the block in real time. Later, you can also change where the block settings are displayed (on the sidebar or right in the main content area).
## Block registration with MB Builder
The easiest way to create a block is using [MB Builder](/extensions/meta-box-builder/). The plugin provides you with the UI to create blocks easily. This is the video on doing that:
## Block registration with block.json
WordPress recommends using `block.json` for block registration because of [these benefits](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/#benefits-of-using-the-metadata-file).
MB Blocks supports registering blocks using a `block.json` file. It respects WordPress standards so the registration steps are the same as native WordPress block registration.
### Creating the block.json file
Assuming we're creating a hero content block, which has 3 fields: title, image, and content, create a `block.json` file with the following content. It's recommended to put it in a folder `blocks/block-name` (in this example, it's `blocks/hero-content`) within your theme, but you can put it anywhere. We'll use the path for registering the block later.
```json
{
"$schema": "https://schemas.wp.org/trunk/block.json",
"apiVersion": 3,
"name": "meta-box/hero-content",
"title": "Hero Content",
"description": "A custom hero content block that uses MB fields.",
"style": [
"file:./hero-content.css"
],
"category": "formatting",
"icon": "format-quote",
"keywords": [
"hero-content",
"quote"
],
"supports": {
"anchor": true
},
"attributes": {
"image": {
"type": "object",
"default": {
"full_url": "https://example.com/photo.png"
}
},
"title": {
"type": "string",
"default": "Hello, World!"
},
"content": {
"type": "string",
"default": "This is a hero content block."
}
},
"render": "file:./hero-content.php"
}
```
You can see the syntax is the same as WordPress's JSON specification for the [block metadata](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/). The differences are:
- The block name must start with `meta-box/` to make it work with Meta Box.
- The `attributes` must be an array of fields, where the field IDs are the properties and the field types and default values are the properties values. These fields must match the Meta Box fields that we will register below.
:::success
To create a `block.json` file, you can use our [Block Generator](https://metabox.io/block-generator/), which provides a friendly user interface to enter block data.
:::
### Registering the block
After creating the `block.json` file, you must register it with WordPress. Put the following snippet in your theme or plugin.
```php
function your_prefix_register_blocks() {
// Specify the path to the block.json's folder.
register_block_type( get_template_directory() . '/blocks/hero-content' );
}
add_action( 'init', 'your_prefix_register_blocks' );
```
### Registering block fields
Now you need to register block fields with Meta Box. The block fields must match the fields defined in the `block.json`'s `attributes` property above.
Registering block fields is similar to [registering a field group](/creating-fields-with-code/) in Meta Box. The only difference is that you must set `type` to `block`:
```php
add_filter( 'rwmb_meta_boxes', function( $meta_boxes ) {
$meta_boxes[] = [
'title' => 'Hero Content',
'id' => 'hero-content',
'description' => 'A custom hero content block',
// highlight-next-line
'type' => 'block',
// Block fields, must match block.json's attributes.
'fields' => [
[
'type' => 'single_image',
'id' => 'image',
'name' => 'Image',
],
[
'id' => 'title',
'name' => 'Title',
],
[
'type' => 'textarea',
'id' => 'content',
'name' => 'Content',
],
],
];
return $meta_boxes;
} );
```
After that, you can go to edit a post and insert your block into the post content!
### Rendering the block
In the `block.json` file, you can specify the PHP template to render the block via the `render` parameter.
```json
{
"render": "file:./hero-content.php"
}
```
(this means render the block with the PHP file `hero-content.php` in the same folder as the `block.json` file)
By following WordPress standards, these parameters are available in the block template file:
- `$attributes`: the block attributes, which have all the block settings and fields' data. Attributes are automatically [prepared for you](#automatically-prepare-attributes) so you can access them directly.
- `$content`: the block's inner content.
- `$block`: the block object, an instance of `WP_Block` class.
```php
>
```
#### Using MB Views
You can also use MB Views to render the block. This is useful when you want to create views with twig, manage JS, CSS from within the Dashboard.
To do so, first, make sure you have the [MB Views](/extensions/mb-views/) plugin installed and activated. Then, instead of using `file:` prefix, use `view:` instead.
```json
{
"render": "view:testimonial"
}
```
Now create a view by going to Meta Box > Views and create a new view with the name `testimonial`. In the view, you can use twig syntax to render the block. For example:
```php
{{ attributes.name }}
```
:::tip
You can access `{{ block }}`, `{{ attributes }}`, `{{ content }}` in the view like the above example.
Array can be accessed directly by their keys, via dot syntax e.g. `{{ attributes.image.full_url }}`, `{{ attributes.name }}`.
You can also use CSS and JS tabs in the view to add styles and scripts for the block.
PHP functions need to be prefixed with `mb.` to be used in the view.
:::
Set the view's type to `Block` and name to `testimonial`. Then save the view.
### Block styles and scripts
The `block.json` allows you to add styles and scripts for blocks as follows. In the value, it’s possible to pass a script handle registered with the `wp_register_script` or `wp_register_style` functions, a path to a JavaScript/CSS file relative to the `block.json` file, or a list with a mix of both.
```json
{
// Editor script: will only be enqueued in the editor.
"editorScript": "file:./index.js",
// Script: will be enqueued both in the editor and on the frontend.
"script": "file:./script.js",
// View script: will be enqueued only on the frontend.
"viewScript": [ "file:./view.js", "example-shared-view-script" ],
// View script module: will be enqueued only on the frontend.
"viewScriptModule": [ "file:./view.js", "example-shared-script-module-id" ],
// Editor style: will only be enqueued in the editor.
"editorStyle": "file:./index.css",
// Style: will be enqueued both in the editor and on the frontend.
"style": [ "file:./style.css", "example-shared-style" ],
// View style: will be enqueued only on the frontend.
"viewStyle": [ "file:./view.css", "example-view-style" ],
}
```
## Block registration without block.json
If you don't want to use `block.json` to register blocks, you can do that with pure PHP. The process is similar to [registering a field group](/creating-fields-with-code/) in Meta Box. The only difference is that you need to add some settings for the block.
Assuming we're creating a hero content block with 3 fields: title, image, and content. Open your theme's `functions.php` file (or your plugin's PHP file) and add the following code:
```php
add_filter( 'rwmb_meta_boxes', function( $meta_boxes ) {
$meta_boxes[] = [
'title' => 'Hero Content',
'id' => 'hero-content',
'description' => 'A custom hero content block',
// highlight-start
// Block settings.
'type' => 'block',
'icon' => 'awards',
'category' => 'layout',
'context' => 'side',
'render_template' => get_template_directory() . '/blocks/hero/template.php',
'enqueue_style' => get_template_directory_uri() . '/blocks/hero/style.css',
'supports' => [
'align' => ['wide', 'full'],
],
// highlight-end
// Block fields.
'fields' => [
[
'type' => 'single_image',
'id' => 'image',
'name' => 'Image',
],
[
'id' => 'title',
'name' => 'Title',
],
[
'type' => 'textarea',
'id' => 'content',
'name' => 'Content',
],
],
];
return $meta_boxes;
} );
```
The block settings are inherited from the Block *JavaScript* API with a few differences. See the [block registration](https://developer.wordpress.org/block-editor/developers/block-api/block-registration/) page on the Gutenberg Handbook if you need more details.
### Block settings
#### `title`
The block title. It's used to display the block when you click the Block Inserter in Gutenberg.
#### `id`
The block ID. Must be unique.
:::warning No underscores
A block ID can only contain lowercase alphanumeric characters and dashes and must begin with a letter. It doesn't accept underscores, i.e. `my_block` won't work, but `my-block` will work.
:::
#### `version`
The block version. This version number is also used to enqueue CSS and JavaScript files to avoid browser caching.
#### `icon`
The block icon. Can be any of [WordPress' Dashicons](https://developer.wordpress.org/resource/dashicons/) (without the prefix `dashicons-`), or a custom `svg` element (string) or [FontAwesome 5 free icons](https://fontawesome.com/).
Example:
```php
// Specifying a dashicon for the block
'icon' => 'book-alt',
// FontAwesome 5 icon
'icon' => 'fas fa-user',
// Specifying a custom svg for the block
'icon' => '',
```
If you need an advanced configuration for the icon, you can set `icon` as an array that can contain background and foreground colors, these colors will appear with the icon when they are applicable e.g.: in the inserter.
```php
'icon' => [
// Specifying a background color to appear with the icon e.g.: in the inserter.
'background' => '#7e70af',
// Specifying a color for the icon (optional: if not set, a readable color will be automatically defined)
'foreground' => '#fff',
// Specifying a dashicon for the block
'src' => 'book-alt',
],
```
#### `description`
The block description. Optional.
#### `type`
Tells Meta Box to register this as a Gutenberg block (not as a normal meta box). This must be set to `block`.
#### `category`
Specify the block category, which is used to help users browse and discover them. Available values: `text`, `media`, `design` (default), `widgets`, `theme`, `embed`. If a theme or a plugin registers a custom category, you can use it, too.
#### `keywords`
List of keywords that users can use to search the block from the block inserter.
```php
// Make it easier to discover a block with keyword aliases.
'keywords' => ['image', 'photo', 'pics'],
```
#### `context`
Where to show the block settings. If set to `side` (default), the block settings are displayed on the right sidebar when you select the block. If set to `normal`, the block settings are displayed when you click the Edit icon in the block toolbar.
See the short video below to understand.
#### `supports`
Custom supports for the block. This parameter accepts an array like this:
```php
'supports' => [
'align' => ['wide', 'full'],
'customClassName' => true,
'multiple' => true,
'reusable' => true,
'lock' => false,
],
```
The following parameters are available for `supports`:
`align`
Add supports for the block alignment. Note that your theme must add styling for the Gutenberg alignment.
```php
// Add the support for the block alignment (left, center, right, wide, full).
'align' => true,
// Pick which alignment options to display.
'align' => [ 'left', 'right', 'full' ],
```
`customClassName`
This property adds a field to define a custom CSS class name for the block's wrapper. It's useful when you want to add custom styling for a specific instance of the block.
`multiple`
If you want to have a block that can be inserted into each post one time only (like a hero area block), then set this parameter to `false`. A non-multiple block's icon is automatically dimmed (unclickable) to prevent multiple instances.
`reusable`
A block may want to disable the ability to be converted into a reusable block. By default, all blocks can be converted to reusable blocks. If supports reusable is set to `false`, the option to convert the block into a reusable block will not appear.
`lock`
If you want to remove the support for locking UI, set this parameter to `false`.
#### `mode`
The default mode of the block: `edit` to make it show the edit fields when loaded, `preview` (default) to show the rendered HTML when loaded.
```php
'mode' => 'edit',
```
#### `render_callback`
A custom PHP callback or MB Views to display the block content, it accepts the following parameters:
- `$attributes`: the block attributes, which have all the block settings and fields' data. Attributes are automatically [prepared for you](#automatically-prepare-attributes) so you can access them directly.
- `$content`: the block's inner content.
- `$block`: the block object, an instance of `WP_Block` class.
- `$is_preview`: whether previewing the block in the admin. Deprecated.
- `$post_id`: the current post ID. Deprecated. You can get the post ID with `get_the_ID()`.
Please note that you can use all of these parameters **regardless of the number of parameters and order**.
For example: `( $attributes, $block )`, `( $block, $attributes )`, `( $attributes, $content )`... are valid function signatures.
```php
// Specify a custom PHP callback to display the block.
'render_callback' => 'my_hero_callback',
// Or using $this class method.
'render_callback' => [ $this, 'my_hero_callback' ],
// Or using static method.
'render_callback' => [ 'MyClass', 'my_hero_callback' ],
// You can also use MB Views to render the block by prefixing the view name with `view:`.
'render_callback' => 'view:hero-view',
```
```php
get_template_directory() . '/blocks/hero/template.php',
```
Inside the template file, you have full access to these parameters, just like `render_callback`:
- `$attributes`: the block attributes, which have all the block settings and fields' data. Attributes are automatically [prepared for you](#automatically-prepare-attributes) so you can access them directly.
- `$content`: the block's inner content.
- `$block`: the block object, an instance of `WP_Block` class.
- `$is_preview`: whether previewing the block in the admin. Deprecated.
- `$post_id`: the current post ID. Deprecated. You can get the post ID with `get_the_ID()`.
So, inside the `blocks/hero/template.php`, you can write:
```php
```
#### `enqueue_style`
If you want to specify a custom styling for this specific block, then set this parameter to the URL of the custom CSS file that will be used to style the block.
```php
'enqueue_style' => get_template_directory_uri() . '/blocks/hero/style.css',
```
If you have multiple blocks, then using multiple CSS files might hurt the performance of your website since you have many CSS files enqueued. In that case, please put the styles in your theme, and use the functions [enqueue_block_assets()](https://developer.wordpress.org/reference/hooks/enqueue_block_assets/) and [enqueue_block_editor_assets()](https://developer.wordpress.org/reference/hooks/enqueue_block_editor_assets/) to enqueue your styles.
#### `enqueue_script`
If your block requires custom JavaScript actions, then set this parameter to the URL of the custom JavaScript file that will be used to do JavaScript tasks for the block (like initializing a slider).
```php
'enqueue_script' => get_template_directory_uri() . '/blocks/hero/script.js',
```
Please note that this script should be run in 2 cases:
- When the block is done loading on the front end
- When the block preview is done loading in the block editor on the back end
On the back end, every time you modify the block settings, the block preview is re-rendered. The whole HTML of the block preview will be replaced by the new HTML.
So, to trigger a custom code when the block preview is loaded, you need to add an event listener to the event `mb_blocks_preview/{$block_id}` and run your code there:
```js
// Run when a block preview is done loading.
$( document ).on( 'mb_blocks_preview/hero-area', function( e ) {
console.log( e.target ); // e.target is the wrapper div of the block.
// Do something.
} );
```
To make it work for both the front end and back end, you can write your JavaScript like this:
```js
( function( $ ) {
function init() {
// Do something.
}
// Run when a document ready on the front end.
$( document ).ready( init );
// Run when a block preview is done loading.
$( document ).on( 'mb_blocks_preview/hero-area', init );
} )( jQuery );
```
Note that jQuery is already added as a dependency for the script, so you can use it in your script.
#### `enqueue_assets`
If your block has some CSS / JavaScript dependencies (such as a JavaScript library), then using `enqueue_style` and `enqueue_script` might not be a good option since it allows you to enqueue only one single CSS / JS file.
In that case, use `enqueue_assets` to enqueue your assets. This parameter accepts a PHP callback function, like this:
```php
'enqueue_assets' => function() {
wp_enqueue_style( 'slick', '//cdn.jsdelivr.net/npm/slick-carousel@1.8.1/slick/slick.css', [], '1.8.1' );
wp_enqueue_script( 'slick', '//cdn.jsdelivr.net/npm/slick-carousel@1.8.1/slick/slick.min.js', ['jquery'], '1.8.1', true );
wp_enqueue_script( 'my-custom-script', get_template_directory_uri() . '/blocks/hero/script.js', ['slick'], '', true );
}
```
:::info
Because `enqueue_assets` callback is called at `enqueue_block_assets`, it will fire on the front end even when the block is not used. It's better to use `enqueue_style` and `enqueue_script` to load assets only when the block is used.
:::
#### `preview`
This attribute allows you to set preview data for the block, which will show when you click on the plus icon (+) on the toolbar:
The block preview is just the block rendered with sample data. And you'll just need to set the parameter `preview` as an array of that sample data.
For example, if you have a "Team Member" block (as above) that has 3 fields: image, title, and description, you can set the `preview` parameter as follows:
```php
'preview' => [
'image' => 'https://domain.com/person.jpg', // Image URL
'title' => 'William Shakespeare',
'description' => 'Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam',
]
```
#### `storage_type`
Sets the storage for the block fields. Default, it's `attributes`, which means saving block fields in the attributes.
If you want to save the block fields into custom fields, set it to `post_meta`. Saving block fields in the custom fields makes the block act as a wrapper of custom fields. In this case, to prevent bugs, you *should* set `multiple` to `false` to prevent inserting the same block multiple times (see `supports` parameter above).
If you want to save the block fields into custom tables, you need to activate the [MB Custom Table](/extensions/mb-custom-table/) extension first. Then set `storage_type` and `table` as follows:
```php
'storage_type' => 'custom_table',
'table' => 'your table name',
```
See [MB Custom Table documentation](/extensions/mb-custom-table/) for more details.
### Block fields
Each block can have unlimited fields. Adding fields to blocks is similar to adding fields to a custom meta box. All you need to do is specify the fields in the parameter `fields` from the block settings.
```php
add_filter( 'rwmb_meta_boxes', function( $meta_boxes ) {
$meta_boxes[] = [
// Other block settings.
// Block fields.
'fields' => [
[
'type' => 'single_image',
'id' => 'image',
'name' => 'Image',
],
[
'id' => 'title',
'name' => 'Title',
],
// Other fields,
],
];
return $meta_boxes;
} );
```
Each field is an array of its settings. See [this guide](/field-settings/) for details about field settings.
## Block rendering
There are various ways to render a block (via `render` property if you use `block.json` or via `render_callback` or `render_template` if you don't use `block.json`). In any case, the plugin provides you these variables that you can use:
- `$attributes`: the block attributes, which have all the block settings and fields' data. Attributes are automatically [prepared for you](#automatically-prepare-attributes) so you can access them directly.
- `$content`: the block's inner content.
- `$block`: the block object, an instance of `WP_Block` class..
### Automatically prepare attributes
By default, all attributes inside `$attributes` are automatically prepared for you. `$attributes[ $field_id ]` returns the value of the [`rwmb_get_value()`](/functions/rwmb-get-value/) function, which gives you all the data for the field.
For example, if you have a `single_image` field, the value of that field is stored as a number (attachment ID). But when you access the field value via `$attributes['image']`, you'll get the whole attachment object like below, which is more convenient to use:
```php
[
'ID' => 123,
'name' => 'logo-150x80.png',
'path' => '/var/www/wp-content/uploads/logo-150x80.png',
'url' => 'https://example.com/wp-content/uploads/logo-150x80.png',
'width' => 150,
'height' => 80,
'full_url' => 'https://example.com/wp-content/uploads/logo.png',
'title' => 'Logo',
'caption' => 'Logo caption',
'description' => 'Used in the header',
'alt' => 'Logo ALT text',
'srcset' => 'large.jpg 1920w, medium.jpg 960w, small.jpg 480w', // List of responsive image src
'sizes' => [], // List of image sizes. See https://developer.wordpress.org/reference/functions/wp_get_attachment_metadata/
'image_meta' => [], // List of image meta. See https://developer.wordpress.org/reference/functions/wp_get_attachment_metadata/
]
```
And you can use it in your block template like this:
```php
```
This preparation is helpful for not-simple fields like image, file, post, taxonomy, etc.
### Accessing raw data
In case you want to access the raw data (e.g., the attachment ID), you can use the `data` key inside `$attributes`. `$attributes['data']` contains all the info of fields as an array in the format of `'field_id' => 'field_value'`.
Note that, unlike `$attributes[ $field_id ]`, the field value in `$attributes['data']` is *not* prepared, which means it's the raw value.
For example, for a `single_image` field, the value of `$attributes['data']['image']` is the attachment ID.
### Rendering helper functions
In addition to the automatic preparation of attributes, to make it easier to access the block fields' data, we created 2 helper functions: `mb_get_block_field()` and `mb_the_block_field()`.
These functions work exactly like the [`rwmb_get_value()`](/functions/rwmb-get-value/) and [`rwmb_the_value()`](/functions/rwmb-the-value/), but applied for the current block only. The first function returns the data stored for a block field, while the 2nd one outputs that data.
```php
// Get block image field.
$image = mb_get_block_field( 'image' );
echo $image['full_url'];
// Output the block content field.
mb_the_block_field( 'content' );
```
### Reserved attributes
When you create a block, there are some reserved attributes that you should avoid using for field's ID, unless your purpose is to override the default MB Block's behavior. These attributes are:
- `id`: the auto generated ID for the block, which is unique for each block.
- `name`: the block name.
These attributes are used by MB Blocks for easier to style and manipulate the block. If you a field with IDs `id` or `name`, the field's value will override the default value generated by MB Blocks.
In that case, if you want to get the block name, you can use the variable `$block->name`. `$block` is a variable that is always available in your template (or callback). It's an instance of the [`WP_Block`](https://developer.wordpress.org/reference/classes/wp_block/) class.
### Deprecated parameters
These parameters are available in the previous versions of MB Blocks and are deprecated since 1.5.0. They're still working but will be removed in the future. Please use the alternative methods instead.
- `$is_preview`: a boolean variable to let you know if you're in the preview mode for Gutenberg or on the front end. It's useful when you want to display a custom message to users when they edit the block on the back end. To check if the active block is in preview mode, use `defined( 'REST_REQUEST' ) && REST_REQUEST` instead.
- `$post_id`: the current post ID. You can access via `get_the_ID()` function instead.
## Inner blocks
WordPress has an amazing feature for Gutenberg blocks called [InnerBlocks](https://developer.wordpress.org/block-editor/how-to-guides/block-tutorial/nested-blocks-inner-blocks/), which allows you to insert other blocks inside a block. Since version 1.4, MB Blocks also supports this feature.
Assuming you want to create a custom testimonial block, which has the following data:
- An image
- A title
- A paragraph for the testimonial content
- And a select field for the testimonial style (something like an image on the right or above the content)
It's easy to make those fields with MB Blocks. However, it might be less flexible than using the default Gutenberg heading and paragraph blocks for the title and content field. So, we might want to wrap those 2 fields into a `InnerBlocks` like this:
- Image
- InnerBlocks
- Style
This is an example code of the block:
```php
'Testimonial',
'id' => 'testimonial',
'type' => 'block',
'context' => 'side',
'render_callback' => function( $attributes ) {
?>
[
[
'type' => 'select',
'id' => 'style',
'name' => 'Style',
'options' => [
'default' => 'Default',
'image_above' => 'Image above',
],
],
[
'type' => 'single_image',
'id' => 'image',
'name' => 'Image',
],
],
];
return $meta_boxes;
} );
```
When inserting a field in the admin, you'll see the block like this:
As you can see the InnerBlocks on the left, where the usual placeholder is displayed "Type / to choose a block". And you can insert headings (of any type H1, H2, H3, etc.) and the content very easily.
:::tip
I use [Wayfinder](https://wordpress.org/plugins/wayfinder/) plugin to show the block outline, which makes it easier to see which blocks are being edited.
:::
```html
```
To make it more powerful, MB Blocks supports the following properties of InnerBlocks. They're the same as in the [block handbook](https://developer.wordpress.org/block-editor/how-to-guides/block-tutorial/nested-blocks-inner-blocks/).
### `allowedBlocks`
`allowedBlocks` helps you to restrict blocks that are available to insert into the InnerBlocks. The blocks that are not specified, will be not available to be inserted.
In your template (or render callback), you can set `allowedBlocks` like this:
```php
```
This allows you to insert only heading and paragraph blocks.
### `orientation`
By default, InnerBlocks expects its blocks to be shown in a vertical list. A valid use case is to style InnerBlocks to appear horizontally. When blocks are styled in such a way, the orientation prop can be used to indicate a horizontal layout:
```php
```
### `template`
Use the template property to define a set of blocks that prefill the InnerBlocks component when inserted. You can set attributes on the blocks to define their use. The example below shows a book review template using InnerBlocks component and setting placeholder values to show the block usage.
```php
```
### `templateLock`
Template locking allows locking the InnerBlocks area for the current template. Options:
- `all` — prevents all operations. It is not possible to insert new blocks. Move existing blocks or delete them.
- `insert` — prevents inserting or removing blocks, but allows moving existing ones.
- `false` — prevents locking from being applied to an InnerBlocks area even if a parent block contains locking. ( Boolean )
If locking is not set in an InnerBlocks area: the locking of the parent InnerBlocks area is used.
If the block is a top-level block: the locking of the Custom Post Type is used.
### Wrapper div issue
By default, WordPress will create a couple of wrappers `
` for inner blocks **in the editor** (in the admin) to function, this causes inconsistent styling for the editor and the frontend. For example, if you create inner blocks structure like this:
```html
```
If you add items to the inner blocks, in the frontend, its structure looks like this:
```html
My heading
My content
```
However, in the editor, it will render like this (e.g. two extra `div`):
```html
// highlight-start
// highlight-end
My heading
My content
// highlight-start
// highlight-end
```
This causes the editor and the frontend have different markup, which makes it hard to style the block consistently in both places using the same CSS.
To fix this, MB Blocks lets you **remove two extra `div` of inner blocks** in the admin by adding `class`, `id`, or `style` directly to ``. So, instead of writing:
```html
```
You should write:
```html
```
By doing this, it tells WordPress that MB Blocks will control the output of inner blocks in the editor, so both editor and front end will rendered like:
```html
My heading
My content
```
## Block templates
Sometimes you want to load default blocks when creating a new post. Block templates allow specifying a default initial state for an editor session. Use the argument `template` when [registering the post type](/custom-post-types/):
```php
'template' => [
['meta-box/{$block_id}']
]
```
## Block data
Each block created using MB Blocks is a *dynamic block*. By default, the block data is saved as a JSON string in the block content.
If you view the post content via a tool like PHPMyAdmin, you'll see the block is stored as a string like this:
```html
```
When you decode the JSON string, you'll see the block data as an object like this:
```json
{
"id": "block_jyqlhbauqz4jz51ahab",
"data": {
"image": "10",
"title": "Hi, I’m Martin Green",
"subtitle": "WEB DEVELOPER \u0026 DESIGNER",
"content": "Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusa ntium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta suntlo explica bo. Nemo enim ipsam voluptatem quia voluptas.",
"signature": "9",
"button_text": "Discover More",
"button_url": "#",
"background_color": "#f5f7f8"
},
"align": "wide"
}
```
It has the following attributes:
- `name`: the block name. Note that if you have a field with ID `name`, the field value will overwrite this property. In this case, if you want to get the block name, you can use the variable `$block->name`.
- `id`: a unique ID for the block. Note that it's different from the block settings ID. This ID can be used to set the `id` parameter in the HTML if you want.
- `align`: block alignment
- `anchor`: block anchor
- `className`: custom CSS class for the block
- `data`: an array of the block fields' data, in the format of `'field_id' => 'field_value'`
The data is passed to the `render_callback` or `render_template` as a `$attributes` parameter. So you can use it to render the block. See the [block rendering](#block-rendering) section for more details.
### Saving block data in post meta or custom tables
Besides saving the block data as a JSON string in the block's attributes, the plugin allows you to save data in post meta or custom tables. This makes blocks behave the same as a normal field group.
If you want to save block data in post meta, in the meta box's group, set the `storage_type` to `post_meta`:
```php
[
'storage_type' => 'post_meta',
'supports' => [
'multiple' => false,
],
]
```
In this case, to prevent bugs, you *should* set `multiple` to `false` to prevent inserting the same block multiple times (the codes above already have that).
If you want to save the block fields into custom tables, you need to activate the [MB Custom Table](/extensions/mb-custom-table/) extension first. Then set `storage_type` and `table` as follows:
```php
[
'storage_type' => 'custom_table',
'table' => 'your_table_name',
'supports' => [
'multiple' => false,
],
]
```
:::warning Caveats
When saving block data in post meta or custom tables, there is no attributes stored in the block itself.
Automatic preparation of attributes is not available, helpers functions like `mb_get_block_field()` and `mb_the_block_field()` will not work.
You will have to use the [rwmb_meta](/functions/rwmb-meta/) function to get the block data.
:::
## Hooks
`mb_${blockId}_settings`
This is a filter to let developers change the block settings **via Javascript**. It accepts one parameter - `settings`, the block settings array.
In this filter, `blockId` is the block ID, which has the format `meta-box/id` where `id` is the field group ID.
To use a JavaScript hook, please refer to [this tutorial](https://metabox.io/wordpress-javascript-hooks/).
## Video Tutorial
**Create Custom Gutenberg Blocks With Meta Box (only PHP)**
**Build Gutenberg Blocks Visually With MB Builder**
See more details on [using MB Builder with MB Blocks](https://metabox.io/build-gutenberg-blocks-visually-with-meta-box-builder/).
## Examples
The complete code example for the video (and used to write this tutorial) is [available in the Library](https://github.com/wpmetabox/library/tree/master/extensions/mb-blocks/hero). You can copy the code and put it in your theme. Then start to modify it to create your own Gutenberg blocks.
# MB Builder
import LiteYouTubeEmbed from 'react-lite-youtube-embed';
import 'react-lite-youtube-embed/dist/LiteYouTubeEmbed.css';
This extension helps you create custom fields, settings pages, and relationships with a user-friendly interface.
## Creating custom fields
Custom fields are organized in groups. Each group is displayed as a collapsible panel below the post editor.
To create a field group, go to **Meta Box » Custom Fields** and click **Add New**. You'll see a screen to add fields to the group:
On the left side bar, there are three icons with corresponding panels: Add field, Structure, and Settings. Panels are resizable.
Enter the group title on the top and then click the **+ Add Field** button and select a field type to add to the group. There are two buttons you can click to add a new field:
After that, a new field will appear in the field list. Clicking on that field on the preview to open the field settings panel where you can edit settings. Besides, to edit the label and ID of the field, you can double click on the preview to change them directly.
:::tip Quickly find a field type
To find a field type quickly, type its name in the input box above the field list. The plugin will filter the fields and show only matched fields.
:::
:::tip
You can delete, duplicate or add a new field above/below the current field by clicking the icons in the field toolbar. To reorder fields, drag and drop them to the new positions.
:::
You can see the field settings and structure at the same time by opening the floating structure panel. It’s also resizable.
When finishing adding fields, click the **Settings** icon and select the location where the fields are displayed for.
After that click the **Save Changes** button to finish.
## Field settings
When adding fields to a field group, each field has its own settings. The list of settings with detailed explanation is [here](/field-settings/). MB Builder creates UI for them.
To view and edit field settings, click anywhere in the field preview:
Each field settings are self-explained. We also add some tooltips next to the setting title to give you more information if needed.
All field settings are divided into some sections: General, Appearance, Conditional logic, Validation and Advanced. The General tab has most settings you need while the Appearance decides how your field display in the post editor. Besides:
* Conditional logic: if you install the [MB Conditional Logic](/extensions/meta-box-conditional-logic/), then this part is for creating rules with UI.
* Validation: helps you to create [complex validation rules](/validation/).
* Advanced tab has the following settings:
- Custom CSS class: if you need to cusomize the style of the field.
- Before & after: For entering custom HTML that outputed before and after the field.
- Custom sanitize callback: if you need [custom sanitization](/sanitization/).
- Save field value: if you don't want Meta Box to save the field value (which rarely happens) and you want to handle saving by yourself, then uncheck this checkbox.
- Custom HTML5 attributes: helps you add [custom HTMl5 attributes](/custom-attributes/) to your input fields.
- Custom settings: if you want to add extra settings to the field. We'll cover it in a next section.
Note that: plugins and developers might add more settings for fields. We'll see how to do that later in this docs.
## Field group settings
The field group settings are put in the tab **Settings** panel:
There are several settings:
* Location: where you select this field group is for posts, terms, users, comments, blocks or settings pages. For each object type, you'll be able to select corresponding post types, taxonomies or settings pages. Please note that it's required to install and activate corresponding extensions: [MB Term Meta](/extensions/mb-term-meta/), [MB User Meta](/extensions/mb-term-meta/), [MB Comment Meta](https://metabox.io/plugins/mb-comment-meta/), [MB Blocks](/extensions/mb-blocks/), and [MB Settings Page](/extensions/mb-settings-page/). In there, the Advanced rules allows you to add advanced rules for which category, post, user, ... the field group appears for. Requires the [MB Include Exclude](/extensions/meta-box-include-exclude/) extension.
* Toggle rules: select which conditions to show or hide the field group. Requires the [MB Show Hide](/extensions/meta-box-show-hide/) extension.
* Conditional Logic: setup the conditional logic rules to toggle the field group based on other fields' values. Requires the [MB Conditional Logic](/extensions/meta-box-conditional-logic/) extension.
* Post settings, such as context, priority if you select the location is for posts.
* Custom block settings, such as block icon, render callback if you select the location is for blocks, which means creating custom Gutenberg blocks. Requires [MB Blocks](/extensions/mb-blocks/) extension. See the **Create Gutenberg blocks** section below.
* Tab style and default active tab: these are the settings for [MB Tabs](/extensions/meta-box-tabs/) extension.
* Custom table settings, including table name, table prefix and option to create custom table automatically. These are the settings for [MB Custom Table](/extensions/mb-custom-table/) extension. Note that if you select to create the custom table automatically, all columns will have the data type `TEXT` to ensure maximum compatibility.
* Advanced:
+ Custom CSS class: the custom CSS class for the wrapper `div` if you need to cusomize the style of the field group.
+ Field ID prefix: if you want to prefix all fields in the field group, then this settings is for that. It's optional, but a good practice to keep your custom fields separated from other custom fields. You can also use underscore `_` as prefix to keep your fields hidden in the default WordPress **Custom Fields** meta box.
+ Custom settings: if you want to add extra settings to the field group. See below for details.
## Custom settings
Custom settings is a feature for both fields and field groups, which allows you to add extra settings for them in case the builder doesn't have. It's useful when you want to add your own settings or the settings the builder hasn't added yet (in this case, please let us know).
:::info Key-value settings
What describes in this section is applied also for similar key-value settings, including: choice field options, JavaScript options (date, datepicker, slider, ...), query args (post, taxonomy, taxonomy advanced, user) and custom HTML5 attributes.
:::
To add custom settings, scroll down to the last setting of the **Advanced** section of the fields or field group. Then click **+ Add New** button and add new settings. Like this:
Which will produce the result like this:
```php
[
'id' => 'new-your-phone',
'name' => 'New Your phone',
'type' => 'text',
// Custom settings.
'mask' => '012-345-6789',
'enable' => false
],
```
Remember, MB Builder treats `true`, `false` as boolean values.
If you want to add complex custom settings, like multi-dimentional arrays:
```php
[
'type' => 'post',
'id' => 'field_id',
'query_args' => [
'tax_query' => [
[
'taxonomy' => 'category',
'field' => 'slug',
'terms' => 'technology',
],
],
],
],
```
Then you can use the dot notation or JSON for custom attributes:
### Dot notation
Dot notation is a way that let you define structural data (hierarchical data) with dots (.). Each dot (.) defines a level in your data.
If you want to enter a structural custom settings for a field like:
```php
'my_prop' => [
'param1' => 'Value 1',
'param2' => 'Value 2',
'param3' => 'Value 3',
]
```
This can be understood like this:
```php
"my_prop.param1": "Value 1",
"my_prop.param1": "Value 2",
"my_prop.param1": "Value 3",
```
Here the params param1, param2, param3 are sub-params of the my_prop and they're defined with a dot prefixed.
Implementing that in MB Builder as follows:
Another case is when you want to add a set of data without keys. The data in PHP looks like this:
```php
'my_prop' => [
'Value 1',
'Value 2',
'Value 3',
]
```
Although keys are not implemented, we can understand that this list (array) uses numeric keys: 0, 1, 2. So we can rewrite it as:
```php
'my_prop': [
0: 'Value 1',
1: 'Value 2',
2: 'Value 3',
]
```
Similar to above, this can be understood as:
```
"my_prop.0": "Value 1",
"my_prop.1": "Value 2",
"my_prop.2": "Value 3",
```
And can be implemented as follows in MB Builder:
Combining these, you can define a complex data structure as follows (this is a post field with advanced query args):
```php
[
'type' => 'post',
'id' => 'field_id',
'query_args' => [
'tax_query' => [
[
'taxonomy' => 'category',
'field' => 'slug',
'terms' => 'technology',
],
],
],
],
```
In MB Builder:
### JSON notation
Another way to enter nested array in MB Builder, you can use JSON notation. Paste the JSON string into the value input, and this JSON will be parsed into an array in PHP.
For example, the `tax_query` above can be implemented like this:
## Getting PHP code
For each field group, MB Buider can create a PHP code that you can copy and paste into your theme's `functions.php` file (or your plugin file) and then *deactivate the MB Builder extension*.
This is helpful if you want to:
- [Share field groups to other websites](https://metabox.io/copy-custom-fields-with-meta-box-builder/) which doesn't have MB Builder installed.
- Improve the performance since field groups are loaded directly from your file.
To get the code, click the **Get PHP Code** button on the toolbar:
On this screen, set the text domain (for field labels in case you want to translate them in a multilingual website) and the function name. Then click the **Generate** button to generate the code. Finally, click the **Copy** button to copy the code and paste it into your theme's `functions.php` file.
When you copy PHP code and paste it into your theme's `functions.php` file, you can **safely deactivate MB Builder** (do *not* deactivate Meta Box, it's still required).
For detailed instruction, please see [this tutorial](https://metabox.io/copy-custom-fields-with-meta-box-builder/).
Please note that once you take the PHP code and remove the settings from the MB Builder, there's no way to edit the field group in the MB Builder directly from the exported code.
In order to do re-edit the field group, we suggest after taking the PHP code, export the field group settings from MB Builder (see the section below). Then whenever you want to edit the field group, just import it back and edit.
## Export / Import
To export one or more field groups, go to the main screen *Meta Box → Custom Fields*. Then click the checkboxes next to the field groups' titles you want to export. Then choose **Export** from the Bulk Actions dropdown. Then click **Apply**.
Or you can export individual field group by clicking on **Export** link when hover the mouse over the field group title:
To import field groups, select the *Import* button at the top of the page. Then choose the downloaded file in the previous step, then press **Upload file and import**. That’s all!
For detailed instruction, please see [this tutorial](https://metabox.io/export-import-custom-fields-meta-box-builder/).
Video tutorial:
## Creating Gutenberg blocks
Since v3.1.0, MB Builder allows you to create Gutenberg blocks visually, without writing code. See this video tutorial on how to do that:
Note that the plugin supports Twig template engine to write block template code. See [Twig documentation](https://twig.symfony.com/doc/1.x/templates.html) for how to use variables, conditions and functions.
For more convenient, the plugin supports the following variables:
- `{{ align }}`: block alignment (if the block supports it).
- `{{ anchor }}`: block anchor (if the block supports it).
- `{{ className }}`: custom CSS class name (if the block supports it).
- `{{ is_preview }}`: whether or not in preview mode.
- `{{ post_id }}`: the current post ID.
To access the field value, you can use `{{ field_id }}`, where `field_id` is the field ID. If the field returns an array (such as `single_image` field), you can access to field's attribute with `{{ my_image.full_url }}`.
Besides, the plugin also allows you to use any PHP/WordPress function via `mb.function()` where `function` is the function name. For example, the code below get the post object and output the post title:
```php
{% set post = mb.get_post( post_id ) %}
{{ post.post_title }}
```
Or this code will output the site title:
```php
{% set site_title = mb.get_bloginfo( 'name' ) %}
{{ site_title }}
```
## Creating settings pages
This feature helps you to create custom settings pages (or Customize panels) with UI. It requires the [MB Settings Page](/extensions/mb-settings-page/) extension.
To start, go to **Meta Box > Settings Pages** and click **Add New**.
Here you can enter all the settings for the settings page. All settings are self-explained. Please see the [documentation of MB Settings Page](/extensions/mb-settings-page/) to understand them.
## Creating relationships
This feature helps you to create relationships between posts, terms and users with UI. It requires the [MB Relationships](/extensions/mb-relationships/) extension.
To start, go to **Meta Box > Relationships** and click **Add New**.
Here you can enter all the settings for each side of the relationship (**From** and **To**). For each side, there are 3 tabs of settings:
- General: for general settings such as object type and post type.
- Meta Box: for extra meta box settings. These settings are the same as the field group settings when creating custom fields.
- Field: for extra field settings. These settings are the same as the field settings (post, term or user depending on the object type).
Please see the [documentation of MB Relationships](/extensions/mb-relationships/) to understand them.
## Extending the builder
### Adding custom controls to fields
If you develop [extra solutions for Meta Box](https://metabox.io/resources/), then you might need to add a custom settings for fields. Luckily, MB Builder has API for you to create custom controls for these settings.
To add a control, use the following hook:
```php
add_filter( 'mbb_field_controls', 'your_prefix_add_field_controls', 10, 2 );
function your_prefix_add_field_controls( $controls, $type ) {
// Add a checkbox control.
$controls[] = \MBB\Control::Checkbox( 'custom_layout', __( 'Custom layout', 'your-text-domain' ) );
// Add a select control.
$controls[] = \MBB\Control::Select(
'layout',
[
'label' => __( 'Layout', 'your-text-domain' ),
'tooltip' => __( 'Select the layout for the field', 'your-text-domain' ),
'options' => [
'one-third' => __( 'One-third', 'your-text-domain' ),
'one-half' => __( 'One-half', 'your-text-domain' ),
'two-third' => __( 'Two-third', 'your-text-domain' ),
'full-width' => __( 'Full-width', 'your-text-domain' ),
],
'dependency' => 'custom_layout:true',
],
'one-half',
'general'
);
return $controls;
}
```
The filter `mbb_field_controls` accepts 2 parameters:
- `$controls`: Array of controls.
- `$type`: Field type, useful if you want to add controls to specific field types only.
Each control has a specific type (`\MBB\Control::Select` in the above example, which is a select dropdown) and several parameters:
1. Setting name
1. Control properties, which is an array:
- `label`: the control label.
- `tooltip`: the content of the tooltip, if you want to explain what the control is for users.
- `options`: array of options for the select control, in format of `'value' => 'label'`.
- `dependency`: if you want to show the control only when another control has a specific value, then set this to `{$other_control_setting_name}:{$value}`. Optional.
1. Default value. Optional.
1. Settings tab: `general` (default) or `advanced`. Optional.
In case your control has only `label` property, you can set the property as a string (see the checkbox control in the above example).
List of supported control types:
Name|Description
---|---
`MBB\Control::Checkbox` | A checkbox
`MBB\Control::Input` | An input text. You can set the `'type' => 'number'` for the control property to make it accepts only numbers.
`MBB\Control::Select` | A select dropdown where you can select only a single value. You need to set `options` property for the control as shown in the above example.
`MBB\Control::ReactSelect` | A select dropdown where you can select multiple values. You need to set `options` property for the control and the default value must be an array.
`MBB\Control::Textarea` | A textarea.
This is the result of the above example:
### Adding custom controls field groups
Similarly, you can add custom controls for the whole field group. Here is how we do to add custom controls when [MB Tabs](/extensions/meta-box-tabs/) extension is activated.
```php
add_filter( 'mbb_settings_controls', 'your_prefix_add_settings_controls' );
function your_prefix_add_settings_controls( $controls ) {
$controls[] = \MBB\Control::Select( 'tab_style', [
'label' => __( 'Tab style', 'meta-box-builder' ),
'tooltip' => __( 'Change how look and feel of tabs in MB Tabs', 'meta-box-builder' ),
'options' => [
'default' => __( 'Default', 'meta-box-builder' ),
'box' => __( 'Box', 'meta-box-builder' ),
'left' => __( 'Left', 'meta-box-builder' ),
],
] );
$controls[] = Control::Input( 'tab_default_active', __( 'Default active tab ID', 'meta-box-builder' ) );
return $controls;
}
```
The filter `mbb_settings_controls` accepts only one parameter - an array of controls. Each control is defined similarly as for fields.
### Changing the parsed settings
In most cases, when adding a new control or a new field type, the settings are saved correctly. These settings will be parsed to a PHP array and is used by Meta Box and extensions. The parsed result is also used when you generate PHP code.
In some specific cases, you might want to set custom value to the fields instead of the value set in the controls. To do that, use the following hook:
```php
// For fields.
$field_settings = apply_filters( 'mbb_field_settings', $field_settings );
$field_settings = apply_filters( "mbb_field_settings_{$field_type}", $field_settings );
// For field group.
$field_group_settings = apply_filters( 'mbb_meta_box_settings', $field_group_settings );
```
For example: you created 2 controls for `custom_layout` (checkbox) and `layout` (select) for fields (see example in the section "Adding your own field settings" above). When parsing, you don't want to set `custom_layout` to `true` if `layout` has a value as it's redundant. You can do that with:
```php
add_filter( 'mbb_field_settings', 'your_prefix_parse_field_settings' );
function your_prefix_parse_field_settings( $field_settings ) {
if ( ! empty( $field_settings['layout'] ) ) {
unset( $field_settings['custom_layout'];
}
return $field_settings;
}
```
## Video tutorial
Here is a quick video showing how to use the MB Builder to create custom fields in WordPress:
## Upgrade
When updating from version 4 to version 5, the plugin automatically migrates data of field groups to compatible with the new React app. The migration process doesn't touch your existing data, so you're always safe.
## Further reading
- [How to Add and Configure Custom Fields Using MB Builder](https://metabox.io/add-configure-custom-fields-meta-box-builder/)
- [How to Export and Import Custom Fields with MB Builder](https://metabox.io/export-import-custom-fields-meta-box-builder/)
- [How to Easily Copy Custom Fields From One Site to Others with MB Builder](https://metabox.io/copy-custom-fields-with-meta-box-builder/)
# MB Columns
MB Columns helps you put custom fields into columns in a 12-column grid. You can create nested columns for sub-fields in [groups](/extensions/meta-box-group/) or put multiple fields into one column.
## Simple syntax
To specify number of columns for each field, add `columns` parameter for that field. The plugin will automatically calculate number of columns and wrap fields into a div "row" and apply styles for them.
The code below registers some fields and make each field obtain 4 columns of the grid (thus, you'll see 3 columns layout):
```php
add_filter( 'rwmb_meta_boxes', 'prefix_columns_demo_register' );
function prefix_columns_demo_register( $meta_boxes ) {
$meta_boxes[] = array(
'title' => 'MB Columns Demo',
'fields' => array(
array(
'name' => 'Name',
'id' => 'name',
'type' => 'text',
// Number of columns (in grid 12)
'columns' => 4,
),
array(
'name' => 'Email',
'id' => 'email',
'type' => 'email',
'columns' => 4,
),
array(
'name' => 'Mobile',
'id' => 'mobile',
'type' => 'text',
'columns' => 4,
),
),
);
return $meta_boxes;
}
```
## Advanced syntax
The advanced syntax is helpful if you need to put **multiple fields in 1 column**.
```php
add_filter( 'rwmb_meta_boxes', 'prefix_register_meta_boxes' );
function prefix_register_meta_boxes( $meta_boxes ) {
$meta_boxes[] = array(
'id' => 'test-columns',
'title' => 'MB Columns Demo',
'columns' => array(
'column-1' => 4, // Define the size of the column (from 1 to 12)
'column-2' => array( // More advanced syntax
'size' => 8, // Column size (1-12)
'class' => 'custom-css-class', // Custom CSS class for the column
),
),
'fields' => array(
array(
'name' => 'Name',
'id' => 'name',
'type' => 'text',
'column' => 'column-1',
),
array(
'name' => 'Email',
'id' => 'email',
'type' => 'email',
'column' => 'column-1',
),
array(
'name' => 'State',
'id' => 'state',
'type' => 'select_advanced',
'options' => array(
'NY' => 'New York',
'CA' => 'California',
),
'column' => 'column-2',
),
array(
'name' => 'Description',
'id' => 'description',
'type' => 'textarea',
'column' => 'column-2',
),
),
);
return $meta_boxes;
}
```
In the advanced syntax, you need to define a parameter `columns` for the meta box. It's the list of columns for all fields in the following format:
```php
'columns' => array(
'column-1' => 4, // Define the size of the column (from 1 to 12)
'column-2' => array( // More advanced syntax
'size' => 4, // Column size (1-12)
'class' => 'custom-css-class', // Custom CSS class for the column
),
),
```
Then each field in the meta box need to specify which column it belongs to by setting `'column' => 'column-0'`.
## Notes
This extension uses 12-columns grid, so when defining number of columns, you must define them so that the total columns for each row equals to 12.
For example:
- Row 1: field 1 (3 columns), field 2 (3 columns), field 3 (3 columns), field 4 (3 columns)
- Row 2: field 5 (6 columns), field 6 (6 columns)
- Row 3: field 7 (12 columns)
# MB Conditional Logic
import LiteYouTubeEmbed from 'react-lite-youtube-embed';
import 'react-lite-youtube-embed/dist/LiteYouTubeEmbed.css';
**MB Conditional Logic** helps you to show or hide meta boxes, custom fields or any elements based on other fields' values.
You can also combine conditions. It works not only for meta boxes or custom fields, but also other HTML elements.
## Getting started
### With UI
If you are using [MB Builder](/extensions/meta-box-builder/) (which is included in [Meta Box Lite](https://metabox.io/lite/) or [Meta Box AIO](https://metabox.io/pricing/)), you can set conditional logic for a specific field by clicking the plus in the **Conditional Logic** section:
In this section, you can choose to show or hide a field when all or any conditions match. For each rule, you need to select or enter a dependency field ID, the operator and enter the field value. The dependency field ID is auto-suggested from the list of current fields and you can add as many rules as you want:
Using MB Builder is intuitive and self-explained.
For advanced usage (like with custom conditions or using outside field groups), please use code which are explained in detailed below.
### With code
In case you use code to register meta boxes, you need to add an extra parameter `visible` or `hide` to a field (or a meta box if you want to hide the whole meta box) to set the conditional logic for it.
For example, Tthe code below registers a meta box that is **hidden when the post format is "aside"**. The meta box also have 2 custom fields: Brand and Product. **The Product field will be hidden if user select a brand that's not "Apple"**.
```php
add_filter( 'rwmb_meta_boxes', function( $meta_boxes ) {
$meta_boxes[] = [
'title' => 'Brands and Products',
// highlight-start
// Hide this meta box when post format is aside
'hidden' => [ 'post_format', 'aside' ],
// highlight-end
'fields' => [
[
'id' => 'brand',
'name' => 'Brand',
'type' => 'select',
'options' => [
'Apple' => 'Apple',
'Google' => 'Google',
],
],
[
'id' => 'apple_products',
'name' => 'Which Apple product that you love?',
'type' => 'radio',
'options' => [
'iPhone' => 'iPhone',
'iPad' => 'iPad',
],
// highlight-start
// Hide this field when user selected a brand that's not 'Apple'
'hidden' => [ 'brand', '!=', 'Apple' ]
// highlight-end
],
],
];
return $meta_boxes;
} );
```
## Syntax
To make a meta box or a field visible/hidden, please add a setting for the meta box or the field with the following syntax:
```php
// Condition to show.
'visible' => [ 'field', 'operator', 'value' ],
// Condition to hide
'hidden' => [ 'field', 'operator', 'value' ],
```
Name|Description
---|---
`field`| Meta Box field ID or ID of a DOM element to compare.
`operator` | Comparison operators: `=`, `>=`, `<=`, `>`, `<`, `!=`, `in`, `contains`, `between`, `starts with`, `ends with`, `match`. All of them can combine with `not` operator to become negate operator. Default: `=`. Optional.
`value` | Value to compare with.
:::info
You can bypass `operator` if it's `=`, which is the default value. So you can write:
```php
'visible' => [ 'field', 'value' ],
// or
'hidden' => [ 'field', 'value' ],
```
:::
The normal operators like `=`, `!=`, etc. are pretty clear. Let's see the advanced operators like `contains`, `starts with`, etc.
## Advanced Operators
### `contains`
The operator `contains` can check if **a field value contains another string or value**:
```php
'visible' => ['brand', 'contains', 'pp'] // Apple, App, ...
```
In case a field has multiple value (checkbox list, select multiple...), this operator checks **if the field value (which is an array) contains a value**:
```php
'visible' => ['brand', 'contains', 'Apple'];
```
It also works with `taxonomy_advanced` field. In this case, please **set the value to the term ID**. For example, if you need to check if a taxonomy advanced field has a value:
```php
'visible' => ['product_type', 'contains', 4]; // 4 is a term ID.
```
### `in`
This operator is used to check if **a field value is in an array of specific values**:
```php
'visible' => ['brand', 'in', ['Apple', 'Samsung']];
```
In case a field has multiple value (checkbox list, select multiple...), this operator checks if **any of the field value is in the specified array**. For example, if the `brand` field above is a `checkbox_list` field, then it will be visible if users select any of the value "Apple" or "Samsung":
```php
'visible' => ['brand', 'in', ['Apple', 'Samsung']];
```
If you use with a `taxonomy_advanced` field, please **set the value to the term IDs**:
```php
'visible' => ['product_type', 'in', [2, 4]]; // The field will be visible if the product type has any term with ID 2 or 4.
```
### `between`
This operator check if the field value is between minimum and maximum values.
Let say that we have a date field `released_date` and we want to show another field only when `released_date` is between "2015-06-01" and "2015-12-01":
```php
'visible' => [ 'released_date', 'between', [ '2015-06-01', '2015-12-01' ] ]
```
Please note that the `between` operator does not only compare numeric fields but also date and time fields.
### `starts with`
This operator checks if field value starts with a string:
```php
'visible' => [ 'brand', 'starts with', 'App' ] // Apple, App
```
### `ends with`
This operator checks if field value ends with a string:
```php
'visible' => [ 'brand', 'ends with', 'le' ] // Apple, Google
```
### `match`
This operator checks if field value matches a regular expression:
```php
'visible' => [ 'brand', 'match', '[a-z]$' ],
```
### `not`
We can combine `not` operator with other operators to negative the meaning of them. So we'll have `not contains`, `not in`, `not match`, `not starts with`, `not ends with`, `not between`.
## Multiple conditions
Sometimes, you'll need to use more than one conditional logic. To do that, you can define multiple conditions to show or hide a meta box or a custom field. For example:
```php
// Visible when 'brand' is 'Apple' AND 'released_year' is between 2010 and 2015
'visible' => [
[ 'brand', 'Apple' ],
[ 'released_year', 'between', [ 2010, 2015 ] ],
],
```
By default, if you define compound statement, the logic will correct if **ALL** of them are correct. In case you want to visible a field if **ONE** of them is correct, move all statements to `when` key and put new `relation` key like this example:
```php
// Visible when 'brand' is 'Apple' OR 'released_year' is between 2010 and 2015
'visible' => [
'when' => [
[ 'brand', 'Apple' ],
[ 'released_year', 'between', [ 2010, 2015 ] ],
],
'relation' => 'or'
],
```
## Special values
This section shows you how to specify the `value` in the conditions for some specific fields.
### Checkbox field
For checkboxes, use `0` or `false` if it's not checked, `1` or `true` if it's checked.
```php
'visible' => [ 'checkbox_field', true ], // Visible if checkbox_field is checked
```
### Media fields
For media fields that use WordPress media popup to handle upload like `file_advanced`, `image_advanced`, the extension checks **number of uploaded files** instead of their values.
This example shows or hides a field depends on there's a file uploaded:
```php
// Visible when file_advanced field is has file
'visible' => [ 'file_advanced', '>', 0 ],
// Or hidden if image_advanced doesn't contains anything
'hidden' => [ 'image_advanced', 0 ],
```
## Toggle by other elements
MB Conditional Logic can work with other HTML elements the same as Meta Box fields. With this feature, you can show or hide any meta box or field based on post types, page parent, post ID, categories...
To make it work with HTML element, instead of passing the field ID as the first parameter, please pass the **element's ID**.
Here are the list of available built-in WordPress elements:
Param|Description
---|---
`post_ID`|Post ID
`page_template`|Page template
`parent_id`|Parent post ID
`post_format`|Post format
Examples:
Display a meta box (or a field) if page template is `template-custom.php`:
```php
'visible' => [ 'page_template', 'template-custom.php' ],
```
### Featured image
Featured image is a special HTML element. It has the field name/ID `_thumbnail_id` and when empty, WordPress sets the value to `-1`. The plugin can detect changes for featured image and let you define conditions with it.
Examples:
Make a field visible if no featured image:
```php
'visible' => [ '_thumbnail_id', '=', '-1' ],
```
Make a field visible if featured image is set:
```php
'visible' => [ '_thumbnail_id', '!=', '-1' ],
```
Or make a field visible only if featured image is a specific image with ID `123`:
```php
'visible' => [ '_thumbnail_id', '=', '123' ],
```
## Using outside field groups
The extension can even work with elements outside field groups. Let's say you want to hide an element `.custom-div` when a field with ID `brand` is `Microsoft`, then you can do that with the following code:
```php
add_filter( 'rwmb_outside_conditions', function( $conditions ) {
$conditions['.custom-div'] = [
'hidden' => ['brand', 'Microsoft'],
// or you can write this for clarity
'hidden' => ['#brand', 'Microsoft'],
];
return $conditions;
} );
```
Note that the `.custom-div` can be any CSS selector, like `#custom-id` or `.my-class .children`.
If you want to hide an element `.custom-div` based on a value of an input, which is not a Meta Box field, specify its ID as follows:
```php
add_filter( 'rwmb_outside_conditions', function( $conditions ) {
$conditions['.custom-div'] = array(
'hidden' => ['#input-id', 'value'],
);
return $conditions;
} );
```
If you want to hide a tab created by [MB Tabs](/extensions/meta-box-tabs/), [see this](/hide-tabs-with-conditional-logic/).
## Using with taxonomies
### Post category
For post category, use `post_category` as the first parameter:
```php
'visible' => ['post_category', 'in', [4, 5, 6]]
```
By default, the extension uses category IDs to check. If you want to use slug, use the following code:
```php
'visible' => ['slug:post_category', 'in', ['fashion', 'gaming', 'technology']]
```
### Post tag
Support for post tag is available only for Gutenberg editor.
To add conditions by post tag, use `tags` as the first parameter:
```php
'visible' => ['tags', 'in', [4, 5, 6]]
```
Unlike post category, you have to use tag IDs.
### Custom taxonomies
For custom taxonomies, use `tax_input[taxonomy_slug]` as the first parameter:
```php
'hidden' => ['tax_input[product]', 'in', [5, 6, 7]],
```
Similarly to post category, it works with slug, too.
```php
'hidden' => ['slug:tax_input[product]', '!=', 'drones']
```
## Using with Group
The extension uses jQuery to check the field ID and value to match the condition. For the sub-fields in a **non-cloneable** group, the field ID actually has the format `groupID_fieldID`. You need to use that format for the condition like this:
```php
[
'id' => 'group',
'type' => 'group',
'fields' => [
[
'id' => 'brand',
'name' => 'Brand',
'type' => 'select',
'options' => [
'apple' => 'Apple',
'google' => 'Google',
'microsoft' => 'Microsoft'
],
),
[
'id' => 'apple_products',
'name' => 'Which Apple product that you love?',
'type' => 'radio',
'options' => [
'iPhone' => 'iPhone',
'iPad' => 'iPad',
'Macbook' => 'Macbook',
],
// highlight-next-line
'visible' => [ 'group_brand', '=', 'apple' ]
],
],
],
```
If the group is **cloneable**, the conditional logic **runs inside the clone only**. In this case you **don't** have to change the sub-field IDs like above.
## Custom callback
To set conditional logic with custom JavaScript callback, just put your function call in the first parameter. Like so:
In your JavaScript file:
```js
// Your custom JavaScript function that checks the condition
function my_custom_callback() {
return true;
}
```
In your PHP file:
```php
'visible' => [ 'my_custom_callback()', true ]
```
Please note that your function can return anything you want and you can use any operator to compare. For example
```js
// Your js
function dummy_function() {
return ['foo', 'bar', 'baz];
}
```
```php
// Your field or meta box
'hidden' => [ 'dummy_function()', 'contains', 'bar' ];
```
## Toggle types
By default, we use jQuery `.show()` and `.hide()` method (which equivalent to CSS `display` property) to toggle elements. Imagine you have three fields named A, B, and C. So by default it will display vertical like so:
```
A
-
B
-
C
```
Or if you use Column extension, it will display horizontal like so:
```
A | B | C
```
What happen when field B is hidden? The field C will jump to B place, sometimes, you will want to keep the position of these field, so if field B is hidden, it should keep the blank space like so:
```
A
-
-
C
```
Or
```
A | | C
```
So, basically, we have to use CSS `visibility` property instead of `display` property. To do so, just add `'toggle_type' => 'visibility'` to your Meta Box.
We also support **slide and fade animations**. In order to use these animation just set `toggle_type` to `slide` or `fade`.
In short, we support 4 toggle types: `visibility`, `display`, `slide`, `fade`.
## Running conditional logic manually
There are situations where you manually modify some fields' values by code. In those cases, no events of the changes are fired, and your conditions might not be applied for other fields.
To fix that, you can run the conditions manually via JavaScript like this:
```js
let $scope = $( '.scope' );
rwmb.runConditionalLogic( $scope );
```
Where `.scope` is a selector of the wrapper element, which contains all the fields you want to apply conditional logic to. It might be a field group, or any `div`, or even the whole page. When running this code, the conditional logic will be applied to all fields inside this wrapper element. In other words, some fields will be visible or hidden based on the current values of other fields.
## Notes
### Cloneable groups
It's important to note that, when you have a **cloneable group**, then all the rules are applied **within** the group clones only. It won't work if the rule refers to a field outside of the group.
In other words, both the dependency and dependant of the rules must be sub-fields of the group.
### Chained hidden fields
Another important rule is that **if a field is hidden, then all fields depend on it will be hidden** regardless of their values.
For example, if you have 3 fields A, B, C and set the rule as follow:
```
IF A = 1 or B = 1 THEN show C
```
Then if A or B is hidden, the C is always hidden, regardless values of A and B.
## Known issues
Conditional Logic doesn't works with [autocomplete](/fields/autocomplete/) field.
# MB Custom Post Types & Custom Taxonomies
import LiteYouTubeEmbed from 'react-lite-youtube-embed';
import 'react-lite-youtube-embed/dist/LiteYouTubeEmbed.css';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import FAQ from '@site/src/components/FAQ';
This extension helps you create custom post types and custom taxonomies with a user-friendly interface.
## Creating post types
To create a new custom post type, go to **Meta Box » Post Types** and click **New Post Type**:
There are several settings divided into tabs. In most cases, you only need to enter the plural name, singular name, and slug in the **General** tab and click the **Publish** button to register the post type.
### Post type settings
If you want to customize the post type such as changing the menu icon or disabling the block editor (Gutenberg) for it, please see the settings below.
:::tip
From our experience, the most important settings are in the **Advanced** tab.
:::
Name | Description
---|---
Plural name | General name for the post type, usually plural. Required.
Singular name | Name for one object of this post type. Required.
Slug | Post type key. Must not exceed 20 characters and may only contain lowercase alphanumeric characters, dashes, and underscores.
When entering a singular name for the post type, the slug is automatically generated. You can manually change the slug if necessary.
Labels are automatically generated from the post type's plural and singular names.
Name | Description
---|---
Add new | Label for adding a new singular item. Default is 'Add New' for both hierarchical and non-hierarchical types.
Add new item | Label for adding a new singular item. Default is 'Add New Post' / 'Add New Page'.
Edit item | Label for editing a singular item. Default is 'Edit Post' / 'Edit Page'.
New item | Label for the new item page title. Default is 'New Post' / 'New Page'.
View item | Label for viewing a singular item. Default is 'View Post' / 'View Page'.
View items | Label for viewing post type archives. Default is 'View Posts' / 'View Pages'.
Search items | Label for searching items. Default is 'Search Posts' / 'Search Pages'.
Not found | Label used when no items are found. Default is 'No posts found' / 'No pages found'.
Not found in trash | Label used when no items are in the Trash. Default is 'No posts found in Trash' / 'No pages found in Trash'.
Parent items | Label used to prefix parents of hierarchical items. Not used on non-hierarchical post types. Default is 'Parent Page:'.
All items | Label to signify all items in a submenu link. Default is 'All Posts' / 'All Pages'.
Nav menu archives | Label for archives in nav menus. Default is 'Post Archives' / 'Page Archives'.
Attributes meta box | Label for the attributes meta box. Default is 'Post Attributes' / 'Page Attributes'.
Media frame button | Label for the media frame button. Default is 'Insert into post' / 'Insert into page'.
Media frame filter | Label for the media frame filter. Default is 'Uploaded to this post' / 'Uploaded to this page'.
Featured image meta box | Label for the featured image meta box title. Default is 'Featured image'.
Setting the featured image | Label for setting the featured image. Default is 'Set featured image'.
Removing the featured image | Label for removing the featured image. Default is 'Remove featured image'.
Used as featured image | Label in the media frame for using a featured image. Default is 'Use as featured image'.
Menu name | Label for the menu name. Default is the same as plural name.
Table filter hidden heading | Label for the table views hidden heading. Default is 'Filter posts list' / 'Filter pages list'.
Table date filter hidden heading | Label for the date filter in list tables. Default is 'Filter by date'.
Table pagination hidden heading | Label for the table pagination hidden heading. Default is 'Posts list navigation' / 'Pages list navigation'.
Table hidden heading | Label for the table hidden heading. Default is 'Posts list' / 'Pages list'.
Item published | Label used when an item is published. Default is 'Post published.' / 'Page published.'
Item published privately | Label used when an item is published with private visibility. Default is 'Post published privately.' / 'Page published privately.'
Item switched to draft | Label used when an item is switched to a draft. Default is 'Post reverted to draft.' / 'Page reverted to draft.'
Item scheduled | Label used when an item is scheduled for publishing. Default is 'Post scheduled.' / 'Page scheduled.'
Item updated | Label used when an item is updated. Default is 'Post updated.' / 'Page updated.'
Name | Description
---|---
Description | A short descriptive summary of what the post type is.
Public | Whether a post type is intended for use publicly either via the admin interface or by front-end users. Default false.
Hierarchical | Whether the post type is hierarchical (e.g. page). Default false.
Exclude from search | Whether to exclude posts with this post type from front-end search results. Default is the opposite value of the public settings.
Publicly queryable | Whether queries can be performed on the front end for the post type as part of `parse_request()`. Default is inherited from the public settings.
Show UI | Whether to generate and allow a UI for managing this post type in the admin. Default is the value of the public settings.
Show in menu | Where to show the post type in the admin menu.
Menu position after | The position in the menu order the post type should appear.
Menu icon | The URL to the icon to be used for this menu (Dashicons).
Show in nav menus | Makes this post type available for selection in navigation menus. Default is the value of the public settings.
Show in admin bar | Makes this post type available via the admin bar. Default is the value of show in menu settings.
Show in REST | Whether to include the post type in the REST API. Set this to true for the post type to be available in the block editor.
REST API base slug | Custom base URL of REST API route. Default is the post type slug.
Capability type | The string to use to build the read, edit, and delete capabilities. Default 'post'.
Has archive | Whether there should be post type archives. Will generate the proper rewrite rules if the rewrite settings are enabled. Default false.
Custom archive slug | The custom archive slug. Default is the post type slug.
Custom rewrite slug | Customize the permalink slug. Default is the post type slug.
Prepended permalink structure | Whether the permalink should be prepended. Example: if your permalink is `/blog/`, then your links will be: `false` -> `/news/`, `true` -> `/blog/news/`. Default true.
Query var | Sets the custom query var key for this post type. Default is the post type slug.
Can export | Whether to allow this post type to be exported. Default true.
Delete with user | Whether to delete posts of this type when deleting a user.
These are core features the post type supports.
Name | Description
---|---
Title | Post title
Editor | Post editor (the main content)
Excerpt | Post excerpt
Author | Post author
Thumbnail | The featured image
Trackbacks | The trackbacks/pingbacks from other websites
Custom fields | The custom fields meta box in the edit screen
Comments | Enable comments for posts of this type
Revisions | Enable revisions for posts of this type
Page attributes | The attributes meta box to select post template and parent
Post formats | Enable post format for posts
This is the list of taxonomies that are registered for the post type. Select the taxonomies you want to use for the post type.
Name | Description
---|---
Re-Order Posts | Order posts of that post type using a drag and drop interface. [Learn more here](/reorder-posts-terms/).
Add toggle status column | Add a column to quickly toggle post status between published and draft.
### Getting PHP code
If you're familiar with PHP, you might want to get the PHP code to register the post type. To do that, click the **Get PHP Code** button and copy the generated code. Then can insert it into your theme's `functions.php` file (or your plugin's file). After inserting, you can deactivate the extension to make your site a little bit faster.
## Creating taxonomies
To create a new custom taxonomy, go to **Meta Box » Taxonomies** and click **Add New**:
There are several settings divided into tabs. In most cases, you only need to enter the plural name, singular name, and slug in the **General** tab and click the **Publish** button to register the taxonomy.
The settings are similar to creating post types above.
### Taxonomy settings
If you want to customize the taxonomy such as setting the hierarchy or showing it in the post type list table, please see the settings below.
:::tip
From our experience, the most important settings are in the **Advanced** tab.
:::
Name | Description
---|---
Plural name | General name for the taxonomy, usually plural. Required.
Singular name | Name for one object of this taxonomy. Required.
Slug | Taxonomy key, must not exceed 32 characters and may only contain lowercase alphanumeric characters, dashes, and underscores.
When entering a singular name for the taxonomy, the slug is automatically generated. You can manually change the slug if necessary.
Labels are automatically generated from the taxonomy's plural and singular names.
Name | Description
---|---
Search items | Label for searching items. Default 'Search Tags'/'Search Categories'.
Popular items | Label for most popular items, only used for non-hierarchical taxonomies. Default 'Popular Tags'.
All items | Label to signify all items in a submenu link. Default 'All Tags'/'All Categories'.
Parent item | Label for parent item, only used for hierarchical taxonomies. Default 'Parent Category'.
Parent item colon | The same as parent item, but with colon : in the end.
Edit item | Label for adding a new singular item. Default 'Edit Tag'/'Edit Category'.
View item | Label for viewing a singular item. Default 'View Tag'/'View Category'.
Update item | Label for updating a singular item. Default 'Update Tag'/'Update Category'.
Add new item | Label for adding a new singular item. Default 'Add New Tag'/'Add New Category'.
New item name | Label for new item name. Default 'New Tag Name'/'New Category Name'.
Separate items with commas | This label is only used for non-hierarchical taxonomies. Default 'Separate tags with commas', used in the meta box.
Add or remove items | This label is only used for non-hierarchical taxonomies. Default 'Add or remove tags', used in the meta box when JavaScript is disabled.
Choose from most used | This label is only used on non-hierarchical taxonomies. Default 'Choose from the most used tags', used in the meta box.
Not found | Label used in the meta box and taxonomy list table. Default 'No tags found'/'No categories found'.
No terms | Label used in the posts and media list tables. Default 'No tags'/'No categories'.
Filter by | This label is only used for hierarchical taxonomies, used in the posts list table. Default 'Filter by category'.
Table pagination hidden heading | Label for the table pagination hidden heading.
Table hidden heading | Label for the table hidden heading.
Most used tab | Title for the Most Used tab. Default 'Most Used'.
Back to items | Label displayed after a term has been updated.
Menu name | Label for the tab in the admin menu.
Name | Description
---|---
Description | A short descriptive summary of what the taxonomy is for.
Public | Whether a taxonomy is intended for use publicly either via the admin interface or by front-end users.
Public queryable| Whether the taxonomy is publicly queryable. If not set, the default is inherited from the public settings.
Hierarchical | Whether the taxonomy is hierarchical. Default false.
Show UI | Whether to generate and allow a UI for managing terms in this taxonomy in the admin. If not set, the default is inherited from the public settings (default true).
Show in menu | Whether to show the taxonomy in the admin menu. If true, the taxonomy is shown as a submenu of the object type menu. If false, no menu is shown. The show UI settings must be true. If not set, default is inherited from the show UI settings.
Show in nav menus | Makes this taxonomy available for selection in navigation menus. If not set, the default is inherited from the public settings.
Show on edit page | Whether to show the taxonomy meta box on the edit page.
Show in REST | Whether to include the taxonomy in the REST API. Set this to true for the taxonomy to be available in the block editor.
REST API base slug | To change the base URL of the REST API route. Default is the taxonomy slug.
Show tag cloud | Whether to list the taxonomy in the Tag Cloud Widget controls. Default is inherited from the show UI settings.
Show in quick edit | Whether to show the taxonomy in the quick/bulk edit panel. Default is inherited from the show UI settings.
Show admin column | Whether to display a column for the taxonomy on its post type list table. Default false.
Custom rewrite slug | Customize the permastruct slug. Default is the taxonomy slug.
Prepended permalink structure | Should the permastruct be prepended. Default true. Example: if your permalink structure is `/blog/`, then your links will be: false -> `/news/`, true -> `/blog/news/`.
Hierarchical URL | Either hierarchical rewrite tag or not. Default false.
Query var | Sets the query var key (taxonomy slug) for this taxonomy.
Sort | Whether terms in this taxonomy should be sorted.
This is the list of post types that are connected with the taxonomy. Select the post types you want to connect to the taxonomy.
Name | Description
---|---
Manage terms | The capability required for managing terms.
Edit terms | The capability required for editing terms.
Delete terms | The capability required for deleting terms.
Assign terms | The capability required for assigning terms.
Name | Description
---|---
Re-Order Terms | Order terms of this taxonomy using a drag and drop interface. [Learn more here](/reorder-posts-terms/).
### Getting PHP code
If you're familiar with PHP, you might want to get the PHP code to register the taxonomy. To do that, click the **Get PHP Code** button and copy the generated code. Then can insert it into your theme's `functions.php` file (or your plugin's file). After inserting, you can deactivate the extension to make your site a little bit faster.
## Video tutorial
The video below shows you the steps and explains the settings for a custom post type (and also custom taxonomy):
## Notes
### Custom capabilities for custom post types
When creating custom post types, you have 3 options to set capabilities: copy from "post", copy from "page" or create custom capabilities. While copying from "post" or "page" is clear (the plugin applies the same capabilities from post or page for this custom post type), creating custom capabilities might be confusing.
When you select "custom" for capabilities, the plugin does the following (assumming we have a post type `book`):
- Set `'capability_type' => array( 'book', 'books' ),`, and
- Set `'map_meta_cap' => true`
These 2 steps will create the following capabilities for the post types:
```php
[edit_post] => 'edit_book'
[read_post] => 'read_book'
[delete_post] => 'delete_book'
// Primitive capabilities used outside of map_meta_cap():
[edit_posts] => 'edit_books'
[edit_others_posts] => 'edit_others_books'
[publish_posts] => 'publish_books'
[read_private_posts] => 'read_private_books'
// Primitive capabilities used within map_meta_cap():
[read] => 'read',
[delete_posts] => 'delete_books'
[delete_private_posts] => 'delete_private_books'
[delete_published_posts] => 'delete_published_books'
[delete_others_posts] => 'delete_others_books'
[edit_private_posts] => 'edit_private_books'
[edit_published_posts] => 'edit_published_books'
[create_posts] => 'edit_books'
```
And thanks to `map_meta_cap`, the admin role can edit the posts types.
### Block templates with MB Blocks
Sometimes you want to load default blocks created by [MB Blocks](/extensions/mb-blocks/) when creating a new post. Block templates allow specifying a default initial state for an editor session. Use the argument `template` when registering the post type:
`'template' => [
['meta-box/{$block_id}']
]`
### Reserved terms
There is a complete set of reserved keywords, or terms, in WordPress that should not be used in certain circumstances as they may conflict with core functionality. See more in [the documentation](https://codex.wordpress.org/Reserved_Terms).
## FAQ
The problem is that WordPress hasn't refreshed the rewrite rules for the custom post type. Please go to **Settings » Permalink** and re-save the settings.
Meta Box only supports changing the rewrite slug for custom post types. If you want more customization for the permalink, you'll need a plugin like [Custom Post Type Permalinks](https://wordpress.org/plugins/custom-post-type-permalinks/) or if you're a developer, you can follow [this guide](https://www.shibashake.com/wp/custom-post-type-permalinks-part-2).
Similar to the question above, Meta Box only supports changing the rewrite slug for custom post types. If you want to add custom taxonomies to the permalink of custom post types, you'll need a plugin like [Custom Post Type Permalinks](https://wordpress.org/plugins/custom-post-type-permalinks/) or if you're a developer, you can follow [this guide](https://wordpress.stackexchange.com/q/94817/2051).
After changing your post type slug, you can use the plugin [Post Type Switcher](https://wordpress.org/plugins/post-type-switcher/) to switch the posts from the old post type to the new one.
No, they're still in the database, but not visible. To show them again, create a post type with the old slug.
The default WordPress UI can't be changed to radio buttons. However, you can remove the default WordPress UI and create a [taxonomy field](/fields/taxonomy/) with Meta Box, which supports many ways to display and choose terms, including radio buttons. See this video for how to do that:
Yes! This extension can work independently without Meta Box. If you only need custom post types and/or custom taxonomies (no custom fields), then you can install the extension for free from [WordPress.org](https://wordpress.org/plugins/mb-custom-post-type/).
# MB Custom Table
import LiteYouTubeEmbed from 'react-lite-youtube-embed';
import 'react-lite-youtube-embed/dist/LiteYouTubeEmbed.css';
**MB Custom Table** helps you to save custom fields' values to a custom table instead of the default WordPress meta table. All custom fields for a post are saved in a single row, where each column contains the value of a corresponding field.
This reduces the number of rows in the database which can help improve the performance when the data grows and lets you have all of your data in one place, so you can easily view, edit, import, and export it.
## Getting started
The easiest way to work with custom tables is using [MB Builder](/extensions/meta-box-builder/). It provides a UI to create custom tables and automatically save custom fields to table columns.
When creating a field group with MB Builder, click on the settings button on the left sidebar and you'll see options to use a custom table as follows:
Turn on the option to **Custom table**, and enter the **Table name**. By default, the table name doesn't contain the WordPress table prefix. If you want to use the WordPress table prefix, enable the **Include table prefix** option (and don't enter the prefix manually).
If you select the option **Auto create table**, the plugin will attempt to create the table for you. Once it's done, you'll see the custom table in your database, which has columns that match your custom field IDs, each column per field ID. To make the data compatible with the field data, the plugin uses the data type `TEXT` for all columns.
Now you can go to the edit post screen (or the edit user profile if you use the meta box for users) and save the post. You'll see the data is saved in the new custom table instead of the post meta table.
:::info How does it work?
The plugin will map custom table columns with custom field IDs, one column per custom field. If you have a group field, then the column name will be the top-level group ID, and it won't create columns for sub-fields. When you save a post, each custom field is stored in a corresponding column.
:::
## Using custom tables with code
Using custom tables with code is suitable if you want to have more control over the data type or index key which can help improve the performance. It's recommended when you're a developer and you're familiar with MySQL.
### Creating a custom table
Use the plugin API to create a custom table as follows:
```php
add_action( 'init', function () {
MetaBox\CustomTable\API::create(
'my_custom_table', // Custom table name.
[ // List of columns with data types.
'address' => 'TEXT NOT NULL',
'phone' => 'TEXT NOT NULL',
'email' => 'VARCHAR(20) NOT NULL',
],
[ 'email' ], // List of columns that will be indexed.
);
} );
```
Here we use the `init` hook to make sure the API is ready to use. The code will generate an SQL query for creating a custom table like this:
```php
$sql = 'CREATE TABLE my_custom_table (
ID int(11) unsigned NOT NULL,
address TEXT NOT NULL,
phone TEXT NOT NULL,
email VARCHAR(20) NOT NULL
PRIMARY KEY (ID)
KEY email
)';
```
Parameter|Description
---|---
`table_name`|The custom table name. Required.
`columns`|Array of table columns, where the key is the column name and the value is the [MySQL data type](https://dev.mysql.com/doc/refman/8.0/en/data-types.html). Required.
`keys`|Array of key column names, which will be indexed. Optional. Note that if you want to index BLOB and TEXT columns, make sure you set a fixed length for them.
### Notes
A. Use **only alphanumeric and underscore characters** for the table name. Do not use any special characters, dashes, or spaces.
B. The **table name doesn't need to include the WordPress table prefix**. The extension does not put any constraints on you to define the table name. If you want to include the WordPress table prefix, do this:
```php
global $wpdb;
MetaBox\CustomTable\API::create( "{$wpdb->prefix}my_custom_table", [
'address' => 'TEXT NOT NULL',
'phone' => 'TEXT NOT NULL',
'email' => 'VARCHAR(20) NOT NULL',
] );
```
C. **Do not add ID column**. The ID column is automatically created and set as the primary key in the table. It's used to store the object ID for future reference. Object ID can be the post ID, user ID, or term ID depending on what meta type the table is used for.
D. The **column names must match custom field IDs**, one column per custom field. If you create a column to store a group, then the column name must be the top-level group ID. Don't create columns for sub-fields.
E. The extension uses WordPress's recommended method to create a custom table, which means if the table already exists, the code will do nothing. Although, **it's recommended to run the code that creates custom tables [only when activating your plugin](https://developer.wordpress.org/plugins/creating-tables-with-plugins/)**, like this:
```php
register_activation_hook( __FILE__, function() {
MetaBox\CustomTable\API::create( 'my_custom_table', [
'address' => 'TEXT NOT NULL',
'phone' => 'TEXT NOT NULL',
'email' => 'VARCHAR(20) NOT NULL',
], [ 'email' ] );
} )
```
But if you can't run the code when activating your plugin, it's fine to run the code with the `init` or `plugins_loaded` hook.
### Using existing tables
You can also use an existing table to store your data. The table can be [manually created](https://developer.wordpress.org/plugins/creating-tables-with-plugins/) by a plugin, a theme, or any tool like phpMyAdmin. To use it with Meta Box:
- **The custom table must have the ID column**. It's required to connect entries in the custom table with WordPress posts, terms, or users table.
- **The columns in the custom table much match the field IDs in your meta box**.
### Connecting custom fields to a custom table
To tell a field group to use a custom table to store custom fields, you need to specify 2 parameters `storage_type` and `table` like this:
```php
add_filter( 'rwmb_meta_boxes', function( $meta_boxes ) {
$meta_boxes[] = [
'title' => 'Meta Box Title',
// highlight-start
'storage_type' => 'custom_table',
'table' => 'my_custom_table', // Your custom table name
// highlight-end
'fields' => [
[
'id' => 'address',
'name' => 'Address',
],
[
'id' => 'phone',
'name' => 'Phone',
],
[
'id' => 'email',
'type' => 'email',
'name' => 'Email',
],
],
];
return $meta_boxes;
} );
```
:::warning Column names and field IDs
Again, column names have to match your custom fields' IDs, one column per custom field. If you create a column to store a group, then the column names must be the top-level group ID. No need to create columns for sub-fields.
:::
Now you can go to the edit post screen (or the edit user profile if you use the meta box for users) and save the post. You'll see the data is saved in the new custom table instead of the post meta table.
### Video tutorial
## Getting field value
Use the helper [rwmb_meta()](/functions/rwmb-meta/) function to get a field value. The only difference is you need to specify the table name in the 2nd argument:
```php
$args = [
'storage_type' => 'custom_table',
'table' => $table_name,
];
$value = rwmb_meta( $field_id, $args, $post_id );
echo $value;
```
Also, note that the call to the custom table will be cached, e.g. if you call the helper function several times for the same `$post_id`, it will only query once. This technique will improve the database performance.
You can also use the [`[rwmb_meta]`](/shortcode/) shortcode to display a field value. You need to set the shortcode attributes similar to the `rwmb_meta()` helper function:
```
[rwmb_meta id="field_id" storage_type="custom_table" table="table_name"]
```
## Group fields
For group fields, it's worth mentioning that the whole group value, including sub-field values, is saved as a serialized array in **one column**. So, they're not as flat as other fields.
That means:
- When you create a table, please create only one column for the group (even if that group contains many sub-fields or sub-groups). The column name must be the group ID.
- The group value is serialized, you cannot make SQL queries against the sub-fields values. Thus, you don't benefit from the custom table structure. So, be careful to decide on what fields should be in groups and what fields should not. It's recommended to use groups only for *data storing, not for querying*.
While the data of the group is serialized, it will be unserialized when getting via helper functions. So you don't have to unserialize yourself.
## Query posts with WP_Query
It's important to understand that the plugin doesn't hook to the `WP_Query` to get posts by custom fields stored in the custom table. In other words, using `meta_*` in `WP_Query` for custom fields won't work.
To get posts by custom fields in the custom table, you need to make an extra query to get the post IDs first. Then use these IDs to get full post objects.
Here is an example:
```php
global $wpdb;
$ids = $wpdb->get_col( "SELECT ID FROM your_table WHERE field1 = 'value1' OR field2 = 'value2'" );
if ( empty( $ids ) ) {
echo 'There are no posts';
} else {
$query = new WP_Query( [
'post_type' => 'post',
'post__in' => $ids,
] );
// Do something
}
```
This technique also works with terms and users.
## Custom models
Besides custom tables for built-in WordPress posts, terms, and users, the plugin allows you to create custom models, that mimic the WordPress posts, but store the data completely in custom tables. So you don't need to connect to posts, terms, or users anymore. The data is stored only in one table, which is more efficient.
Pros:
- Better data structure, because you can define the custom table to match your needs.
- Don't mess with WordPress tables. You manage data on your own.
- Complete CRUD for models so you can create/edit/delete them quickly.
- Compatible with all Meta Box field types.
- Use the similar Meta Box and WordPress API/UI to show a list of models or edit models.
- Compatible with MB Admin Columns extension to show fields in admin columns.
Cons:
- Models don't have front-end templates like posts. You won't have permalinks for each model and their archive. Models should be used for managing data. If you want to have the power of the templates, then you should use the normal custom tables above.
- Limited compatibility with some extensions such as MB Relationships and MB Views.
### Usage
To create and use custom models, you need to follow 3 steps below:
#### Step 1: Register a model
Registering a model is very similar to a custom post type in WordPress, with fewer parameters. The code below registers a custom model `transaction`.
```php
// Step 1: Register a model.
add_action( 'init', function() {
mb_register_model( 'transaction', [
'table' => 'transactions',
'labels' => [
'name' => 'Transactions',
'singular_name' => 'Transaction',
],
'menu_icon' => 'dashicons-money-alt',
'supports' => [ 'author', 'published_date', 'modified_date' ],
] );
} );
```
Parameter | Description
---|---
`table`|Custom table for the model. Required.
`labels`|An array of labels for this model. Required. See below for the list of labels.
`show_in_menu`|Where to show the menu in the admin menu. Optional. Default `true`.
`menu_position`|The position in the menu where the model should appear. Optional. Default `null` (at the bottom).
`menu_icon`|The URL to the icon to be used for this menu. Pass a base64-encoded SVG using a data URI, which will be colored to match the color scheme -- this should begin with 'data:image/svg+xml;base64,'. Pass the name of a Dashicons helper class to use a font icon, e.g. 'dashicons-chart-pie'. Pass 'none' to leave div.wp-menu-image empty so an icon can be added via CSS. Defaults to use the posts icon.
`parent`|Menu parent, if you want to show the model as a sub-menu. Optional.
`capability`|The capability to access the menu and create/edit/delete models. Default `edit_posts`.
`supports`|Feature(s) the model supports. Array. Optional. Can be any of `author`, `published_date`, `modified_date`.
**List of labels:**
Name|Description
---|---
`name`|General name for the model, usually plural.
`menu_name`|Label for the menu name. The default is the same as the name.
`singular_name`|Name for one item of this model.
`add_new`|Label for 'Add New' models.
`add_new_item`|Label for adding a new singular item.
`edit_item`|Label for editing a singular item.
`search_items`|Label for searching plural items.
`not_found`|Label used when no items are found.
`all_items`|Label to signify all items in the page title.
`item_updated`|Label used when an item is updated.
`item_added`|Label used when an item is added.
`item_deleted`|Label used when an item is deleted.
**Supports:**
Sometimes, you may want your model to automatically include metadata such as the author, published date, or modified date - without having to manually set them each time.
To do this, you can use the `supports` parameter when defining your model. This parameter is **optional** and accepts an array of supported features:
- `author` - Automatically assigns the current user as the author.
- `published_date` - Automatically sets the date when the model is created.
- `modified_date` - Automatically updates the date when the model is modified.
For example:
```php
'supports' => [ 'author', 'published_date', 'modified_date' ],
```
By adding these options, your model will automatically handle common metadata fields, making your workflow simpler and more consistent.
#### Step 2: Create a custom table for the model
Creating a custom table is exactly the same to the section above. However, for models, the plugin automatically:
- Adds an `ID` column, and sets it as primary key and auto-increment.
- Adds columns for supports (`author`, `published_date`, `modified_date`) if needed.
- Adds a key for `author` if the model supports it.
#### Step 3: Register fields for the model, corresponding to the custom table structure
Registering fields for models is the same as for posts. You just need to specify which model the meta box is for.
If your custom table has many fields, you can split them into multiple meta boxes, to enter the data more conveniently. The order of fields doesn't matter when saving.
```php
// Step 3: Register fields for the model, corresponding to the custom table structure.
add_filter( 'rwmb_meta_boxes', function ( $meta_boxes ) {
$meta_boxes[] = [
'title' => 'Transaction Details',
// highlight-start
'models' => ['transaction'], // Model name
'storage_type' => 'custom_table', // Must be 'custom_table'
'table' => 'transactions', // Custom table name
// highlight-end
'fields' => [
[
'id' => 'created_at',
'type' => 'datetime',
'name' => 'Created at',
'js_options' => [
'timeFormat' => 'HH:mm:ss',
],
'admin_columns' => true,
],
[
'id' => 'amount',
'type' => 'number',
'name' => 'Amount',
'append' => 'USD',
'admin_columns' => [
'position' => 'after id',
'sort' => true,
],
],
[
'id' => 'gateway',
'name' => 'Gateway',
'admin_columns' => true,
],
[
'id' => 'status',
'type' => 'select',
'name' => 'Status',
'options' => [
'pending' => 'Pending',
'completed' => 'Completed',
'refunded' => 'Refunded',
],
'admin_columns' => true,
],
],
];
$meta_boxes[] = [
'title' => 'Additional Transaction Details',
// highlight-start
'models' => ['transaction'], // Model name
'storage_type' => 'custom_table', // Must be 'custom_table'
'table' => 'transactions', // Custom table name
// highlight-end
'fields' => [
[
'id' => 'email',
'type' => 'email',
'name' => 'Email',
'admin_columns' => [
'position' => 'after amount',
'searchable' => true,
],
],
[
'id' => 'screenshot',
'type' => 'image_advanced',
'name' => 'Screenshots',
'admin_columns' => true,
],
],
];
return $meta_boxes;
} );
```
After completing 3 steps, you'll see the Transactions menu on the left and you can add/edit/delete models easily as follows:
### Getting field values for models
To get a field value for models, you can use 2 methods:
Using custom table API to get the raw value in the custom table.
```php
$value = \MetaBox\CustomTable\API::get_value( $field_id, $model_id, $table_name );
// Example: returns 'completed'
$status = \MetaBox\CustomTable\API::get_value( 'status', 3, 'transactions' );
```
Using the helper function to get the formatted value:
```php
$value = rwmb_meta( $field_id, [
// highlight-next-line
'object_type' => 'model', // Must be 'model',
'type' => $model,
], $model_id );
// Example: returns 'Completed'
$status = rwmb_meta( 'status', [
'object_type' => 'model',
'type' => 'transaction',
], 3 );
```
### Bulk actions
#### Add a custom bulk action
The plugin provides a way to handle bulk actions for custom models. By default, it supports only the `delete` action.
To add more custom bulk actions, use the `mbct_{$model}_bulk_actions` filter, which filter accepts an array with the key as the action name and value as the action label.
```php
add_filter( 'mbct_transaction_bulk_actions', function ( $actions ) {
$actions['refund-all'] = 'Refund';
return $actions;
} );
```
#### Create bulk action handlers
To hanle a bulk action, create a function named `mbct_{$action}_bulk_action`. The action name is auto-converted to lowercase and uses underscores instead of hyphens. In the example above, the function name is `mbct_refund_all_bulk_action`.
The function can accept up to 3 parameters: `$ids`, `$model`, and `$request` **regardless of the number of parameters and order**, e.g. `( $ids, $model )`, `( $model, $ids )`, `( $request, $ids, $model )`... are valid function signatures.
Parameter|Type|Description
---|---|---
`$ids`|`int[]`|An array of object IDs
`$model`|`MetaBox\CustomTable\Model`|The model object. You can use this object to get the model name, table name, and other information.
`$request`|`RWMB_Request`|The request object which contains the request data. In every request, we have `action`, `bulk_action`, `ids`, `model`, and `_ajax_nonce` fields. You can get the value of a field by calling `$request->post( $field_name )`.
```php
function mbct_refund_all_bulk_action( $ids, $model ) {
foreach ( $ids as $id ) {
\MetaBox\CustomTable\API::update( $id, $model->table, [
'status' => 'refunded',
] );
}
wp_send_json_success();
}
```
Alternatively, you can hook to `mbct_{$action}_bulk_action` to handle the bulk action, which accepts the same parameters as the callback function.
```php
add_action( "mbct_{$action}_bulk_action", my_function( $ids, $model, $request ) {
foreach ( $ids as $id ) {
\MetaBox\CustomTable\API::update( $id, $model->table, [
'status' => 'refunded',
] );
}
wp_send_json_success();
}, 10, 3 );
```
#### Redirection and custom message
By default, the page will get reloaded after the bulk action is completed. You can set the redirect URL by passing an array with the `redirect` key in the `wp_send_json_success()` function in your callback function.
```php
// in your callback function
wp_send_json_success( [
'redirect' => add_query_arg( 'model-message', 'updated', admin_url( 'admin.php?page=model-transaction' ) ),
] );
```
The above code will redirect the user to the `admin.php?page=model-transaction&model-message=updated`.
Since the plugin supports custom messages via the `model-message` query string and matches it with labels in the custom model.
You can set the custom message by adding the `item_updated` label in the `labels` parameter of the model registration.
```php
// In your model registration
mb_register_model( 'transaction', [
/// ...
'labels' => [
'name' => 'Transactions',
'singular_name' => 'Transaction',
// highlight-next-line
'item_updated' => 'Transaction updated.',
],
//...
] );
```
As the above example. The *Transaction updated* message will be shown to the user after the bulk action is completed.
#### Custom error message
You can also set a custom error message by calling `wp_send_json_error( $message )` in your callback function, in which `$message` is an error string.
For example:
```php
// In your callback function
if ( ! current_user_can( 'manage_options' ) ) {
wp_send_json_error( 'Sorry, you are not allowed to do this action.' );
}
```
The error message will be shown as a browser alert box to the user.
### Hooks
`mbct_{$model}_query_where`
Filters the where statement in the query in the custom model table list. Accepts one parameter - the where statement. It should include the term `WHERE` if not empty.
```php
add_filter( 'mbct_transaction_query_where', function( $where ) {
return $where ? $where . ' AND status="completed"' : 'WHERE status="completed"';
} );
```
`mbct_{$model}_query_order`
Filters the order statement in the query in the custom model table list. Accepts one parameter - the order statement. It should include the `ORDER BY` term if not empty.
```php
add_filter( 'mbct_transaction_query_order', function( $order ) {
return $order ? $order : 'ORDER BY created_at DESC';
} );
```
`mbct_{$model}_prepare_items`
Filters the SQL query in the custom model table list to get items. Accepts one parameter - the SQL.
This filter is useful when you want to join the current model table with other tables to filter the results.
```php
add_filter( 'mbct_transaction_prepare_items', function( $sql ) {
$sql = str_replace(
'SELECT * FROM wp_transactions',
'SELECT t.*, c.ID FROM wp_transactions t JOIN wp_customers c ON t.ID = c.transaction_id'
$sql
);
return $sql;
} );
```
`mbct_{$model}_total_items`
Filters the SQL query in the custom model table list to get total items. Accepts 2 parameters:
- `$sql`: the full SQL query,
- `$where`: the `WHERE` statement in the query.
```php
add_filter( 'mbct_transaction_total_items', function( $sql, $where ) {
$sql = "SELECT COUNT(t.*) FROM wp_transactions t JOIN wp_customers c ON t.ID = c.transaction_id $where";
return $sql;
}, 10, 2 );
```
`mbct_{$model}_columns`
Filters the list of columns in the custom model table list. Accepts one parameter - the array of columns.
`mbct_{$model}_sortable_columns`
Filters the list of sortable columns in the custom model table list. Accepts one parameter - the array of sortable columns.
`mbct_{$model}_column_output`
Filters the output of a column in the custom model table list. Accepts 4 parameters:
- `$output`: the output
- `$column_name`: the column name
- `$item`: the array of the item data
- `$model`: the model name
`mbct_{$model}_row_actions`
Filters the list of actions for each row item in the custom model table list (default is Edit and Delete). Accepts one parameter - an associate array of actions.
`mbct_{$model}_bulk_actions`
Filters the list of bulk actions for each row item in the custom model table list (default is Delete). Accepts one parameter - an associate array of actions.
`mbct_{$action}_bulk_action`
Fires when a bulk action is performed, used to handle the bulk action. Accepts 3 parameters:
Parameter|Type|Description
---|---|---
`$ids`|`int[]`|An array of object IDs
`$model`|`MetaBox\CustomTable\Model`|The model object. You can use this object to get the model name, table name, and other information.
`$request`|`RWMB_Request`|The request object which contains the request data. In every request, we have `action`, `bulk_action`, `ids`, `model`, and `_ajax_nonce` fields. You can get the value of a field by calling `$request->post( $field_name )`.
[See bulk actions](#bulk-actions) for details.
`mbct_restrict_manage_posts`
Fires after the bulk action for the custom model table list. It's usually used to output custom filters for the table. Accepts 2 parameters:
- `$model`: the model name
- `$which`: `top` or `bottom` - the position of the filters
`mbct_manage_posts_extra_tablenav`
Fires after the bulk action and after `mbct_restrict_manage_posts`. Accepts one parameter - `$which` which can be `top` or `bottom` - the position in the table.
`mbct_submit_box`
Filters the output of the submit meta box. Accepts 2 parameters:
- `$output`: the HTML output
- `$model`: the model name
`mbct_before_submit_box`
Fires before the output of the submit meta box. Accepts one parameter - the model name.
`mbct_after_submit_box`
Fires after the output of the submit meta box. Accepts one parameter - the model name.
`mbct_before_add`
`mbct_after_add`
`mbct_before_update`
`mbct_after_update`
These are actions that fire before/after adding/updating data in a custom table. Accepts 3 parameters:
- `$object_id`: the object ID
- `$table`: the table name
- `$row`: the associate array of data
`mbct_before_delete`
`mbct_after_delete`
These are actions that fire before/after deleting data in a custom table. Accepts 2 parameters:
- `$object_id`: the object ID
- `$table`: the table name
`mbct_add_data`
`mbct_update_data`
These are filters that let you change the data before inserting/updating into the custom table. Accepts 3 parameters:
- `$row`: the associate array of data
- `$object_id`: the object ID
- `$table`: the table name
These filters should return an array of data (e.g., the `$row`).
### Notes
Each model can have only one custom table.
While models work with all Meta Box field types, the data of cloneable/multiple/group fields is always an array, thus it's saved as a serialized array in the model table column.
## API
The plugin has the following APIs for you to work with the data in custom tables. These APIs work well with both custom tables for posts/terms/users and models.
### `exists`
Check if a custom table has a row for an object. In other words, check if an object has data stored in a custom table.
```php
$exists = \MetaBox\CustomTable\API::exists( $object_id, $table );
if ( $exists ) {
// Do something.
}
```
### `get`
Get all custom fields data for an object from a custom table. The returned data is an array, where keys are custom field IDs, and values are custom field values.
The data is raw, meaning it's not formatted yet. For example: for images, you'll get the attachment IDs instead of an array of URL, width, height, size, etc. as you get via `rwmb_the_value` function.
Parameters:
`$object_id` (int) (required) The object (row) ID.
`$table` (string) (required) The custom table name.
`$force` (bool) (optional) Whether to force to get the data from the database, not from the cache. Default is `true`.
```php
$data = \MetaBox\CustomTable\API::get( $object_id, $table, $force );
// Inspect the data.
print_r( $data );
/*
Result:
[
'field_1' => 'value 1',
'field_2' => 'value 2',
'field 3' => ['one', 'two', 'three'],
]
*/
```
### `add`
Add an array of custom field values for an object. Make sure the data for the object doesn't exist yet in the database.
```php
$data = [
'field_1' => 'value 1',
'field_2' => 'value 2',
'field 3' => ['one', 'two', 'three'],
];
\MetaBox\CustomTable\API::add( $object_id, $table, $data );
```
In case you want to add a row for a custom model, set `$object_id` to `null`.
Technically, this method calls the [`wpdb::insert`](https://developer.wordpress.org/reference/classes/wpdb/insert/) method, which returns the number of rows inserted (which is always `1`) or `false` on error.
If you want to get the ID of the inserted row, please use this code:
```php
global $wpdb;
$id = $wpdb->insert_id;
```
If there's an error (like the data format is not compatible with the table column format), you can get the error message like this:
```php
print_r( $wpdb->last_error );
// Output:
// WordPress database error: Processing the value for the following field failed: status. The supplied value may be too long or contain invalid data.
```
### `update`
Update the data for an object. Works similarly to `add`. Make sure the data for the object exists in the database.
```php
$data = [
'field_1' => 'value 1',
'field_2' => 'value 2',
'field 3' => ['one', 'two', 'three'],
];
\MetaBox\CustomTable\API::update( $object_id, $table, $data );
```
### `delete`
Delete all data for an object in the custom table.
```php
\MetaBox\CustomTable\API::delete( $object_id, $table );
```
## Further reading
[How to Move Custom Fields' Data to Custom Tables](https://metabox.io/move-custom-fields-data-to-custom-tables/)
# MB Favorite Posts
## Overview
**MB Favorite Posts** is a WordPress plugin that helps you create the “Favorite Post” button easily. Users can click the button to **bookmark posts as favorites**, and then review them on a Dashboard page. You can enable this feature for **both guests and logged-in users**.
**Note**: MB Favorite Posts plugin is only available for the [Lifetime Bundle](https://metabox.io/pricing/).
## Installation
First, you need to install and activate Meta Box from [wordpress.org](https://wordpress.org/plugins/meta-box/). Next, download MB Favorite Posts plugin from the [My Account](https://metabox.io/my-account/) page, then upload the .zip file from the **Admin Dashboard**. MB Favorite Posts and [other solutions](https://metabox.io/product-category/solutions/) are not included in Meta Box AIO, so you can install them independently without Meta Box AIO.
Upon finishing, the Favorite Posts Button will be automatically added to your WordPress website with the default settings:
To configure the Favorite Posts button to fit your needs, move to the next step.
## Settings
Go to **Settings** > **Favorite Posts**. You will see the UI with sections as follows:
Here you can change the style for the button. We create 3 predefined styles for you to choose from:
- Default: which has a form of a button
- Like: a simple like icon (similar to Facebook like button)
- Rounded: a rounded button with an icon only
You can customize the style for all elements of the button, such as text, text color, icon, etc.
There are also options to let you specify where and when the button is displayed.
### Dashboard Page and Register Page
MB Favorite Posts are integrated with [MB User Profile](/extensions/mb-user-profile/) to help users create the Dashboard page and the Register page automatically without coding.
The Dashboard page shows all the favorite posts of a user, and the Register page contains a form that users can sign up for accounts to use the Favorite Posts feature.
**Note**: when a user signs up for an account on the Register Page, his user role will be **Subscriber**.
You can choose available pages on the website and change them to the Dashboard page and the Register page.
For example, I choose these pages:
Better yet, you should create brand new pages for this purpose. To do so, go to **Pages** > **Add New**, fill in the name for the page and click **Publish**.
The Register page and the Dashboard page will be displayed on the front end as follows:
To delete a post from the favorite list, just click the icon on the right of the post name:
## Shortcodes
The plugin provides 3 shortcodes:
You can put them anywhere on the website (sidebar, page content, etc.).
`[mbfp-posts]`: to show the list of favorite objects
`[mbfp-button]`: to show the "Add to favorite" button
```php
[mbfp-button id="post_id" class="custom_class" add="add_text" added="added_text" show_count="true"]
```
It accepts the following parameters:
Name|Description
---|---
`id`|The ID of the post. Optional. If missed, the shortcode will get the current object ID.
`class`|Custom class name. Optional.
`add`|Custom button text when the post isn't added to favorites. Optional. If missed, the shortcode will get the value from the plugin settings.
`added`|Custom button text when the post is added to favorites. Optional. If missed, the shortcode will get the value from the plugin settings.
`font_size`|Size of text. Optional. Default 14px.
`show_count`|Show the total favorites of a post. Optional. Default false.
`show_icon`|Show icon in button. Optional. Default false.
`icon`|Custom icon. You can choose one of these [ heart, star, pin, like, award ]. Optional. Default heart icon.
`icon_only`|Show icon only. Optional. Default false.
`icon_size`|Size of icon. Optional. Default 16px.
`[mbfp-count]`: to show the total number favorite of a object
```php
[mbfp-count id="post_id" ]
```
It accepts the following parameters:
Name|Description
---|---
`id`|The ID of the post. Optional. If missed, the shortcode will get the current object ID.
## Data
The data of favorites is stored in 2 places:
- User meta: the plugin stores array (serialized) of favorite post IDs in the user meta with key `mbfp_posts`. If you enable for non-logged in users, then the array of favorite post IDs is stored in the cookie.
- Post meta: the plugin also stores array (serialized) of user IDs, who added a post to their favorites, in the post meta with key `mbfp_count`. This post meta is used to count how many favorites a post has.
So if you want to query favorite posts of an user, you can do the following:
```php
$post_ids = get_user_meta( $user_id, 'mbfp_posts', true );
$query = new WP_Query( [
'post_type' => 'post',
'post__in' => $post_ids,
] );
// Do something with $query.
```
You can also query which users favorite a post:
```php
$user_ids = get_post_meta( $post_id, 'mbfp_count', true );
$users = get_users( [
'include' => $user_ids,
] );
// Do something with $users.
```
## Hook
### `mbfp_cookie_expiration`:
This filter is used to allow developers to change the cookie expiration day
```php
add_filter( 'mbfp_cookie_expiration', function( $days ) {
$days = '1 month';
return $days;
}, 10, 3 );
```
### `mbfp_limit`:
This filter is used to define the maximum number of favorite posts.
```php
add_filter( 'mbfp_limit', function( $limit ) {
$limit = 100;
return $limit;
} );
```
# MB Frontend Submission
import FAQ from '@site/src/components/FAQ';
MB Frontend Submission helps you create front-end forms for users to submit data to your website. It allows you to submit data for posts like post fields (title, content, etc.) and also custom fields created by Meta Box. It also support to custom table models and works with all extensions like [MB Group](/extensions/meta-box-group/) or [MB Conditional Logic](/extensions/meta-box-conditional-logic/).
## Submission form
### Adding the submission form
To add a submission form to a page, select the **Submission Form** block from the block inserter. And you'll see the form preview like this:
Clicking on the block will reveal the form settings on the right. All settings are self-explained and have their description.
The plugin also provides a shortcode to insert the submission form into a page:
```php
[mb_frontend_form id="field-group-id" post_fields="title,content"]
```
You can also submit data to a [MB Custom Table](/extensions/mb-custom-table/) model:
```php
[mb_frontend_form id="field-group-id" object_type="model"]
```
If you're using [MB Builder](/extensions/meta-box-builder/), go to **Meta Box > Custom Fields** admin page and copy the content in the **Shortcode** column for the field group that you created:
Below is the list of the settings. The attribute is used for the shortcode.
Name|Attribute|Description
---|---|---
ID|`id`|Field group ID(s). If multiple field groups, enter their IDs separated by commas. Optional.
Ajax|`ajax`|Enable Ajax submission. `true` or `false` (default).
Allow scroll|`allow_scroll`|Enable scroll to message after ajax submission. `false` or `true` (default).
Edit|`edit`|Allow users to edit the post after submitting. `true` or `false` (default). If `true` then ajax submission will be disabled.
Allow delete|`allow_delete`|Allow users to delete the submitted post. `true` or `false` (default).
Force delete|`force_delete`|Whether to delete the submitted post permanently or temporarily (move to Trash).
Show add more|`show_add_more`|Show add new button after submit. `true` or `false` (default).
Object type|`object_type`|The object type for the submitted data. Can be either `post` or `model`. Default is `post`.
Object ID|`object_id`| Optional. Used when you want to update an existing object. If you want to pass the ID of the current post, set it to `current`.
Post type|`post_type`|The submitted post type. Optional. Default is the first post type defined in the meta box. If the meta box is made for multiple post types, you should set this attribute to the correct one.
Post ID *(deprecated)*|`post_id`|The post ID. Optional. Used when you want to update an existing post. If you want to pass the ID of the current post, set it to `current`. This attribute is deprecated, use `object_id` instead.
Post status|`post_status`|The status for submitted posts. See [the list here](https://wordpress.org/documentation/article/post-status/).
Post fields|`post_fields`|List of post fields you want to show in the frontend, separated by commas. Supported the following fields: `title`, `content`, `excerpt`, `date`, and `thumbnail`.
Title field label|`label_title`| Label for the post title field.
Content field label|`label_content` | Label for the post content field.
Excerpt field label|`label_excerpt`| Label for the post excerpt field.
Date field label|`label_date` | Label for the post date field.
Thumbnail field label|`label_thumbnail` | Label for the post thumbnail field.
Submit button text|`submit_button`|The submit button text.
Add new button text|`add_button`|The add new button text.
Delete button text|`delete_button`|The delete button text.
Custom redirect URL|`redirect`|Custom redirect URL.
Confirmation text|`confirmation`|The text for the confirmation message when the form is successfully submitted.
Delete confirmation text|`delete_confirmation`|The text for the confirmation message when the post is deleted.
reCaptcha key|`recaptcha_key`|Google reCaptcha site key (version 3). Optional.
reCaptcha secret|`recaptcha_secret`|Google reCaptcha secret key (version 3). Optional.
### Hiding a field
When you set the form to display fields from a field group, all fields are displayed by default. If you want to hide a field from front-end forms, then you need to set a settings for it.
If you use [MB Builder](/extensions/meta-box-builder/) to build the field group, please enable the settings **Hide from front end** from the field's **Advanced** settings menu:
If you use code to register fields, please set the field as follows:
```php
[
'id' => 'gallery',
'name' => 'Gallery',
'type' => 'image_advanced',
// highlight-next-line
'hide_from_front' => true,
]
```
### Dynamic population
The dynamic population feature allows you to dynamically populate a shortcode attribute with a value. This value can be passed via the query string and/or hook.
#### Query string
You can populate the post ID for the shortcode via the query string by appending the dynamic population parameter for the attribute to the end of your form URL along with your custom value.
```
https://example.com/form-url/?rwmb_frontend_field_object_id=123
```
The query parameter is `rwmb_frontend_field_object_id`.
Note that *only* object ID is supported for populating via query string since version 2.2.0.
#### Hooks
Shortcode attributes can also be populated via WordPress hooks. This example below changes the `post_id` to `123`:
```php
add_filter( 'rwmb_frontend_field_value_post_id', 'my_custom_population_function', 10, 2 );
function my_custom_population_function( $value, $args ) {
if ( $args['id'] === 'your_meta_box_id' ) { // Only filter for a specific form.
$value = 123;
}
return $value;
}
```
This snippet would be pasted in your theme's `functions.php` file or your plugin's PHP file.
The filter has the following format:
```php
$value = apply_filters( "rwmb_frontend_field_value_{$attribute}", $value, $args );
```
The callback function accepts 2 parameters: the attribute value and the array of all attributes. You should use `$args['id]` to check if you're filtering for the right form.
### Templates
The plugin allows you to use custom template files for post fields and the confirmation message.
The plugin will look for a template file in the following order:
- Inside a folder `mb-frontend-submission` of your child theme
- Inside a folder `mb-frontend-submission` of your parent theme
- In the plugin's `templates` folder
To overwrite the output of post fields, please follow the steps below:
- Create a folder `mb-frontend-submission` in your theme.
- Copy a template file that you want to change from the plugin's `templates` folder to the new `mb-frontend-submission` folder, keeping the same folder structure.
- Modify the new template file.
### Field order
Sometimes you want to **mix post fields with custom fields** or change post content to a `textarea` field. You can do that with the following steps:
- Remove the `post_fields` attribute from the shortcode
- Add post fields as normal custom fields to your meta box settings, like this:
```php
$meta_boxes[] = [
'title' => 'Bill Submit',
'id' => 'bill',
'fields' => [
[
'name' => 'Submission Date',
'id' => 'submission_date',
'type' => 'date',
],
[
'name' => 'Title',
// highlight-next-line
'id' => 'post_title',
],
[
'name' => 'Type',
'id' => 'type',
'type' => 'select',
'options' => [
'docs' => 'Document',
'receipt' => 'Receipt',
],
],
[
'name' => 'Description',
'type' => 'textarea',
// highlight-next-line
'id' => 'post_content',
],
[
'name' => 'Thumbnail',
'type' => 'single_image',
// highlight-next-line
'id' => '_thumbnail_id',
],
],
]
```
To make the plugin recognize the post fields, you need to set correct IDs for them as follows:
Field|ID
---|---
Post title|`post_title`
Post content|`post_content`
Post excerpt|`post_excerpt`
Post date|`post_date`
Post thumbnail|`_thumbnail_id`
With this method, you're able to set the label for post fields or change settings (even field type) for them easily using any [field settings](/field-settings/).
### Validation
There are 2 ways to validate fields: on the front end with JavaScript and on the back end with PHP.
For front-end validation with JavaScript, please see [this documentation](/validation/).
To validate on the back end with PHP, please use the `rwmb_frontend_validate` filter as follows:
```php
add_filter( 'rwmb_frontend_validate', function( $validate, $config ) {
// Check only if you're on the right form.
if ( 'your-meta-box-id' !== $config['id'] ) {
return $validate;
}
// Check if users have selected files for an image upload field.
if ( empty( $_POST['image_upload_field'] ) ) {
$validate = false; // Return false to show an error message.
}
return $validate;
}, 10, 2 );
```
If you want to show a custom error message, return a string for the filter, like this:
```php
add_filter( 'rwmb_frontend_validate', function( $validate, $config ) {
if ( 'your-meta-box-id' !== $config['id'] ) {
return $validate;
}
if ( empty( $_POST['image_upload_field'] ) ) {
$validate = 'Please select at least one image to upload'; // Return a custom error message
}
return $validate;
}, 10, 2 );
```
### File upload
#### User capability
To be able to upload files or images with the media popup (via fields `file_advanced`, `file_upload`, `image_advanced`, `image_upload`), users have to log in and proper capability `upload_files` to access the Media Library. If your users don't have that capability (like if they have the "subscriber" role), then the upload fields don't work. In that case, you can add the capability for that role as follows:
```php
add_action( 'init', function () {
$subscriber = get_role( 'subscriber' );
$subscriber->add_cap( 'upload_files' );
} );
```
Another solution is using `file` or `image` fields. Both of them work similarly. They just don't have a nice UI, but they do the job very well.
#### Post thumbnail
Another improvement you might want to add is to use the media popup to pick an image as the post thumbnail. By default, it uses the `image` field, which provides a simple input for an image.
To do that, you need to change the field type for the thumbnail from `image` to `single_image`. Here are the steps:
- Create a folder `mb-frontend-submission` in your theme, inside that folder, create a sub-folder `post`.
- Copy the file `thumbnail.php` from the plugin's `templates/post` folder to the `post` folder above.
- Replace the content of the copied `thumbnail.php` with [this code](https://pastebin.com/6AFcPF7b).
Please note that to open the media popup, users need to log in and have the proper capability. See the section above for how to do that.
### Embedding forms
If you have a front-end submission form on site A, then you want to output it on site B by embedding the form within an iframe, there might be a problem with the cookie policy on browsers that prevent it from submitting.
To make it work please add this snippet to `functions.php` in your theme on site A:
```php
add_action( 'template_redirect', function () {
if ( session_status() !== PHP_SESSION_NONE || headers_sent() ) {
return;
}
$params = session_get_cookie_params();
session_set_cookie_params( $params['lifetime'], '/; samesite=None', $_SERVER['HTTP_HOST'], true, false );
session_start();
}, 9 );
```
The snippet above will set the cookie setting `samesite=None` and `Security=true`. Note that you can only use it on sites that use HTTPS (connection security) and on Chrome and Firefox. It doesn't work on Safari because Safari is blocking third-party cookies. Setting `samesite=None` also might be a security issue, so please be sure you want to do that. For more details, please [see this article](https://web.dev/samesite-cookies-explained/).
## User dashboard
Similar to the submission form, MB Frontend Submission provides a Gutenberg block for you to insert into a page. The block let users view and edit their submitted posts.
To insert a block, select the **User dashboard** block from the block inserter:
If you prefer to use shortcodes, use the following shortcode:
```php
[mb_frontend_dashboard edit_page="124"]
```
Below is the list of the settings. The attribute is used for the shortcode.
Name|Attribute|Description
---|---|--
Edit page|`edit_page`|The ID of the page, where users can submit posts.
Field group ID(s)|`id`|Overwrite field group ID(s) from the edit page. If multiple field groups, enter their IDs separated by commas.
Object type|`object_type`|The object type for the submitted data. Can be either `post` or `model`. Default is `post`.
Model name|`model_name`|The model name for the submitted data. Required if `object_type` is `model`.
Post type|`post_type`|Overwrite the submitted post type from the edit page.
Show welcome message|`show_welcome_message`|Show the welcome message `true` (default) or `false`.
Columns|`columns`|List of columns to be displayed in the dashboard, separated by commas. For example: `title`, `date`, and `status`...
Title column label|`label_title`|The label for the title column.
Date column label|`label_date`|The label for the date column.
Status column label|`label_status`|The label for the status column.
Actions column label|`label_actions`|The label for the actions column.
Post Action Link|`title_link`|The link action when clicking post titles: `edit` or `view` (default).
Add new button text|`add_new`|The add new button text.
:::warning
You **must** create a page for submitting posts first, then use its ID in the `edit_page` attribute.
:::
When users visit this page, they'll see a dashboard like this:
On this dashboard, users can:
- View a list of their submitted posts with the corresponding statuses
- Edit or delete submitted posts
- Or submit a new post
The plugin is smart enough to detect the correct settings from the submission form to the correct posts. So you can have *multiple* submission forms and multiple dashboards on the same website.
By default, the plugin **implicitly** gets the attributes for the submission form from the edit page. That's why you must set the edit page in the block, shortcode or page builder elements.
However, there are cases you want to **explicitly** set these attributes, you can do so by setting the **Field group ID(s)** or the **Post type** attributes from the block, shortcode or page builder elements settings. These values will overwrite the values in the edit page.
You can also set these attributes with a filter like this:
```php
add_filter( 'rwmb_frontend_dashboard_edit_page_atts', function( $attributes, $edit_page_id ) {
$attributes['post_type'] = 'book';
return $attributes;
}, 10, 2 );
```
Note that the plugin only needs the field group ID(s) (`id`) and/or post type (`post_type`) attributes.
## Integrations
MB Frontend Submission has integrations with **the block editor** (Gutenberg) and the following page builder plugins:
- Bricks
- Elementor
For these page builders, there is a new section named Meta Box when you add an element. There’ll be two new elements in this section, one is **Submission Form** and another is **User Dashboard**. They work the same way as in the corresponding blocks in Gutenberg with the live preview on the page and visually settings.
## Hooks
To allow developers to do other things when the form is submitted, we have created some actions and filters.
### General hooks
`rwmb_frontend_redirect`
This filter allows you to change the URL of the redirect page after the form is submitted. It accepts 1 parameter `$config` - the shortcode attributes.
```php
$redirect = apply_filters( 'rwmb_frontend_redirect', $redirect, $config );
```
Note that `$config['post_id']` has the submitted post ID.
Example: redirect to a page based on a submitted value:
```php
add_filter( 'rwmb_frontend_redirect', function( $redirect, $config ) {
// Make sure you work on the correct form.
if ( 'my-id' !== $config['id'] ) {
return $redirect;
}
// Get submitted data via $_POST.
$value = empty( $_POST['field_id'] ) ? null : $_POST['field_id'];
if ( 'yes' === $value ) {
$redirect = 'https://yourdomain.com/custom-page/';
}
return $redirect;
}, 10, 2 );
```
`rwmb_frontend_validate`
This filter is used to check if the form is validated. You can use this filter to add a custom check for the data before it's processed.
```php
apply_filters( 'rwmb_frontend_validate', $validate, $config );
```
The filter has 2 parameters:
- `$validate`: the returned value of validation. If `true`, then the validation is successful. `false` - if not and the plugin will show a default error message. If you want to show a custom error message, just return it as a string. See the **Validation** section above.
- `$config`: the form configuration.
### Form hooks
`rwmb_frontend_before_process`
This action fires before the form is processed, e.g. saved or updated. It accepts one parameter `$config` - the form configuration, taken from the shortcode attributes.
`rwmb_frontend_after_process`
This action fires after the form is processed, e.g. saved or updated. It accepts 2 parameters:
- `$config` - the form configuration, taken from the shortcode attributes.
- `$post_id` - the submitted post ID
You can use this action to do a custom redirect to your Thank you page or send an email notification.
```php
add_action( 'rwmb_frontend_after_process', function( $config, $post_id ) {
if ( 'my-meta-box' === $config['id'] ) {
wp_mail( 'admin@domain.com', 'New submission', 'A new post has been just submitted.' );
wp_safe_redirect( 'thank-you' );
die;
}
}, 10, 2 );
```
`rwmb_frontend_before_form`
This action fires before form output. It accepts one parameter `$config` - the form configuration, taken from the shortcode attributes.
`rwmb_frontend_after_form`
This action fires after form output. It accepts one parameter `$config` - the form configuration, taken from the shortcode attributes.
`rwmb_frontend_before_display_confirmation`
This action fires before the confirmation message is displayed. It accepts one parameter `$config` - the form configuration, taken from the shortcode attributes.
`rwmb_frontend_after_display_confirmation`
This action fires after the confirmation message is displayed. It accepts one parameter `$config` - the form configuration, taken from the shortcode attributes.
`rwmb_frontend_before_submit_button`
This action fires before the submit button is displayed. It accepts one parameter `$config` - the form configuration, taken from the shortcode attributes.
`rwmb_frontend_submit_button`
This filter allows you to change the submit button HTML. It accepts 2 parameters:
- `$submit_button` - the submit button HTML.
- `$post_id` - the post ID
`rwmb_frontend_after_submit_button`
This action fires after the submit button is displayed. It accepts one parameter `$config` - the form configuration, taken from the shortcode attributes.
`rwmb_frontend_before_delete`
This action fires before the post is deleted. It accepts one parameter `$config` - the form configuration, taken from the shortcode attributes.
`rwmb_frontend_after_delete`
This action fires after the post is deleted. It accepts 2 parameters:
- `$config` - the form configuration, taken from the shortcode attributes.
- `$post_id` - the deleted post ID
### Post data filters
`rwmb_frontend_insert_post_data`
This filter is used to modify the submitted post data before it's passed to the `wp_insert_post` function to **create a new post**. It accepts 2 parameters: the array of post data and the shortcode parameters.
```php
$data = apply_filters( 'rwmb_frontend_insert_post_data', $data, $config );
```
`rwmb_frontend_update_post_data`
This filter is used to modify the submitted post data before it's passed to the `wp_update_post` function to **update an existing post**. It accepts 2 parameters: the array of post data and the shortcode parameters.
```php
$data = apply_filters( 'rwmb_frontend_update_post_data', $data, $config );
```
### Post field filters
Sometimes you want to add more things to the post fields, such as making the post title required, adding a description for post content, or even adding a custom HTML before the post thumbnail. You can do that with the following post filter:
```php
// Post title
$field = apply_filters( 'rwmb_frontend_post_title', [
'type' => 'text',
'name' => 'Title',
'id' => 'post_title',
] );
// Post thumbnail
$field = apply_filters( 'rwmb_frontend_post_thumbnail', [
'type' => 'image',
'name' => 'Thumbnail',
'id' => '_thumbnail_id',
'max_file_uploads' => 1,
] );
// Post excerpt
$field = apply_filters( 'rwmb_frontend_post_excerpt', [
'type' => 'textarea',
'name' => 'Excerpt',
'id' => 'post_excerpt',
] );
// Post date
$field = apply_filters( 'rwmb_frontend_post_date', [
'type' => 'datetime',
'name' => 'Date',
'id' => 'post_date',
] );
// Post content
$field = apply_filters( 'rwmb_frontend_post_content', [
'type' => 'wysiwyg',
'name' => 'Content',
'id' => 'post_content',
] );
```
Each post field is treated as a normal Meta Box field (see here for the full list of [field settings](/field-settings/)).
So, to make the post title required, you can do like this:
```php
add_filter( 'rwmb_frontend_post_title', function( $field ) {
$field['required'] = true;
return $field;
} );
```
### Post actions
`rwmb_frontend_before_save_post`
This action fires before the post is created or updated.
```
do_action( 'rwmb_frontend_before_save_post', $object );
```
The action accepts 1 parameter: the instance of the `\MBFS\Post` class, which handles the submission. It has the following public properties that you can use:
- `$post_type`: The current post type
- `$post_id`: The submitted post ID
- `$fields`: The post fields
- `$config`: The configuration, taken from the shortcode attributes
`rwmb_frontend_after_save_post`
This action fires after the post is created or updated. At that time, all the custom fields in the meta box are already saved into the post meta.
```
do_action( 'rwmb_frontend_after_save_post', $object );
```
The action accepts 1 parameter: the instance of the `\MBFS\Post` class, which handles the submission. It has the following public properties that you can use:
- `$post_type`: The current post type
- `$post_id`: The submitted post ID
- `$fields`: The post fields
- `$config`: The configuration, taken from the shortcode attributes
### Dashboard
`rwmb_frontend_dashboard_edit_page_atts`
This filter allows you to explicitly set the attributes for the edit page. See **User Dashboard** section above.
```php
add_filter( 'rwmb_frontend_dashboard_edit_page_atts', function( $attributes, $edit_page_id ) {
$attributes['post_type'] = 'book';
return $attributes;
}, 10, 2 );
```
`rwmb_frontend_dashboard_query_args`
This filter is used for changing the query args for getting posts on the dashboard page. By default, the plugin will get posts that have the same author as the current user. If you want to change this query, then use this filter.
```php
add_filter( 'rwmb_frontend_dashboard_query_args', function( $args ) {
$args['cat'] = 1; // Get only posts in category ID = 1.
return $args;
} );
```
`rwmb_frontend_welcome_message`
This filter is used to change the welcome message. It accepts 3 parameters:
- `$message`: the message content (in HTML)
- `$user`: the current user
- `$query`: the post query
`rwmb_frontend_dashboard_edit_page_content`
This filter is used to change the edited page content. The edit page content is used for parsing the edit form configuration. It accepts only one parameter - the content in HTML.
`rwmb_frontend_dashboard_post_title`
This filter is used to change the title link of posts in the post table. It accepts 2 parameters:
- `$title`: the post title link (in HTML)
- `$post_id`: the post ID
`rwmb_frontend_dashboard_edit_action`
This filter is used to change the edit link for posts in the dashboard. It has 2 parameters: the edit link HTML and the post ID.
```php
add_filter( 'rwmb_frontend_dashboard_edit_action', function( $edit_action, $post_id ) {
$svg_icon = get_template_directory_uri() . 'icons/edit.svg';
return '';
}, 10, 2 );
```
`rwmb_frontend_dashboard_delete_action`
This filter is used to change the delete button for posts in the dashboard. It has 2 parameters: the delete button HTML and the post ID.
`rwmb_frontend_before_edit_action`
This action fires before the edit button is displayed.
`rwmb_frontend_before_delete_action`
This action fires before the delete button is displayed.
`rwmb_frontend_end_actions`
This action fires after all action buttons are displayed.
## FAQ
You can add more field group IDs to the attribute `id` of the form shortcode and separate them by commas.
`[mb_frontend_form id="meta-box-id-1,meta-box-id-2,meta-box-id-3" post_fields="title,content"]`
Each relationship box has the ID `{$relationship_id}_relationships_from` and `{$relationship_id}_relationships_to`. You can include these IDs in the form shortcode to show it on the front end.
`[mb_frontend_form id="meta-box-id-1,posts-to-page_relationships_from" post_fields="title,content"]`
You need to add the attribute `post_type` to the frontend submission shortcode
`[mb_frontend_form id="meta-box-id" post_fields="title,content" post_type="post-type-slug"]`
## Known issues
### Styling
The extension outputs the default fields' HTML with CSS comes from the Meta Box plugin. The style is basic and works in most cases. However, to make it match perfectly with your theme's style, you need to do some work with CSS.
### Caching
As you might know, Meta Box uses [nonces](https://developer.wordpress.org/apis/security/nonces/) to prevent misuse or malicious requests. As the nonce fields are outputted directly in the HTML, they might be cached by caching plugins such as W3 Total Cache, WP Super Cache, etc. And thus, the verification of the nonce might not work properly and break the form submission. In this case, please do not cache the page where the form is embedded (both caching plugins allow you to do that).
## Tutorials
- [Adding guest authors and guest posts](/tutorials/add-guest-authors/)
- [MB Frontend Submission: Dashboard, Ajax, reCaptcha & More](https://metabox.io/mb-frontend-submission-dashboard-ajax-recaptcha/)
- [How to Create a Classified Ads Website using Meta Box](https://metabox.io/create-classified-ads-website-using-meta-box/)
# MB Geolocation
MB Geolocation helps you fill in address fields (street address, zip code, city, state, and country) quickly by using Geocoding API from Google Maps/Open Street Maps.
## Configuration
To make the geolocation work, you need to configure 4 things:
- Enable the geolocation API
- Setup the field group settings
- Setup the ID for the address field to make it suggests addresses from geolocation API
- Setup the ID (or binding ID) for other fields to retrieve data from geolocation API when selecting an address
Follow each step below.
### Geolocation API
Create a project in the [Google Cloud Platform Console](https://console.cloud.google.com/google/maps-apis/overview), and enable the following APIs:
- Google Maps API
- Geocoding API
- Places API
After that, [create an API key](https://developers.google.com/maps/documentation/javascript/get-api-key) for Google Maps. You'll need this key to perform any call to Google Maps platform.
:::success Open Street Maps
If you use **Open Street Maps**, then you can bypass this step. Open Street Maps doesn't require any configuration.
:::
### Field group settings
If you use **Open Street Maps**, you need to *add an Open Street Maps field* to your field group. Then add `geo` to your field group custom settings in the MB Builder like this:
If you use code, then add this line to your field group settings:
```php
'geo' => true,
```
If you use **Google Maps**, it's _not_ required to add a Google Maps field to your field group. To enable geolocation, add the following custom settings in the field group settings in the MB Builder like this:
If you use code, then add this line to your field group settings:
```php
'geo' => [
'api_key' => 'YOUR API KEY',
],
```
:::info
If you have a Google Maps field in your field group, then you can set the Google API key once, either for the Geolocation extension (as above) or for the `map` field. No need to enter the same key for both of them.
:::
You can also add options to Geolocation, which can contains these properties:
- `types`: array of geocode types:
- `geocode`: only geocoding results, no business results.
- `address`: only geocoding results with a precise address.
- `establishment`: business results.
- `(cities)`: only results that match either `locality` or `administrative_area3`.
- `(regions)`: any result matching the following types:
- `locality`
- `sublocality`
- `postal_code`
- `country`
- `administrative_area1`
- `administrative_area2`
- `componentRestrictions`: restrict results to a specific country, must be ISO 3166-1 Alpha-2 compatible country code. You can find code information at [Wikipedia: List of ISO 3166 country codes](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes).
Examples:
```php
// Restrict the result in Australia only
'geo' => [
'api_key' => 'YOUR API KEY',
// highlight-start
'componentRestrictions' => [
'country' => 'au'
],
// highlight-end
],
// Return only business results
'geo' => [
'api_key' => 'YOUR API KEY',
// highlight-next-line
'types' => ['establishment'],
],
// Return only cities and business results
'geo' => [
'api_key' => 'YOUR API KEY',
// highlight-next-line
'types' => ['(cities)', 'establishment'],
],
```
### Address field
The address field is used to retrieve the suggestions from the Geolocation API. To add an address field, add a text field **with an ID that starts with `address`** (like `address` or `address_something`)...
### Other fields
When you select an address from autocomplete list, the geolocation API will return a list of address components. To make the field retrieve the data, **set the field's ID the same as one of the address components**.
For example, if you create a text field with ID `locality`, when you select an address, the city of the address will be filled into this text field.
Here is the list of components for **Google Maps**:
Component|Description
---|---
`street_address`|indicates a precise street address.
`route`|indicates a named route (such as "US 101").
`intersection`|indicates a major intersection, usually of two major roads.
`political`|indicates a political entity. Usually, this type indicates a polygon of some civil administration.
`country`|indicates the national political entity and is typically the highest order type returned by the Geocoder.
`administrative_area_level_1`|indicates a first-order civil entity below the country level. Within the United States, these administrative levels are states. Not all nations exhibit these administrative levels.
`administrative_area_level_2`|indicates a second-order civil entity below the country level. Within the United States, these administrative levels are counties. Not all nations exhibit these administrative levels.
`administrative_area_level_3`|indicates a third-order civil entity below the country level. This type indicates a minor civil division. Not all nations exhibit these administrative levels.
`administrative_area_level_4`|indicates a fourth-order civil entity below the country level. This type indicates a minor civil division. Not all nations exhibit these administrative levels.
`administrative_area_level_5`|indicates a fifth-order civil entity below the country level. This type indicates a minor civil division. Not all nations exhibit these administrative levels.
`colloquial_area`|indicates a commonly-used alternative name for the entity.
`locality`|indicates an incorporated city or town political entity.
`sublocality`|indicates a first-order civil entity below a locality. Some locations may receive one of the additional types: sublocality_level_1 through to sublocality_level_5. Each `sublocality`|level is a civil entity. Larger numbers indicate a smaller geographic area.
`neighborhood`|indicates a named neighborhood.
`premise`|indicates a named location, usually a building or collection of buildings with a common name
`subpremise`|indicates the first-order entity below a named location, usually a singular building within a collection of buildings with a common name.
`postal_code`|indicates a postal code as used to address postal mail within the country.
`natural_feature`|indicates a prominent natural feature.
`airport`|indicates an airport.
`park`|indicates a named park.
`post_box`|indicates a specific postal box.
`street_number`|indicates the precise street number.
`floor`|indicates the floor of a building address.
`room`|indicates the room of a building address.
`lat`|indicates latitude of the result
`lng`|indicates longitude of the result
`geometry`|same as `latitude,longitude`
`formatted_address`|returns human-readable complete address
`id`|unique id of current location
`url`|url of current location
`opening_hours`| Opening hours
`phone`|Phone number
`formatted_phone_number`|Formatted phone number
`international_phone_number`|International phone number
`website`|Website URL
`rating`|Rating value
`user_ratings_total`|Total number of ratings by users
For more information about address components visit: [Google Address Component Types](https://developers.google.com/maps/documentation/geocoding/intro#Types)
Here are the address components for **Open Street Maps**:
Component|Description
---|---
`building`|Building address
`house_number`|House number
`aeroway`|Aeroway
`road`|Road address
`neighbourhood`|Neighbourhood
`suburb`|Suburb
`village`|Village
`town`|Town
`city`|City
`county`|County
`state`|State
`postcode`|Postcode
`country`|Country
`country_code`|Country code
## Advanced
Sometimes you don't want the fields to have the *exact* ID as the address components, or if you want to combine multiple components into one field, then follow the guides below.
### Long and short names
Let's say we have a country named 'Australia'. The long name is 'Australia' and the short name is 'AU'. If we have a state named 'Queensland', 'Queensland' is the long name and 'QLD' is the short name.
By default, MB Geolocation will populate the long name of the field. But you can use the short name by **adding `_short` at the end of field ID**. For example: `administrative_area_level_1_short`, `country_short`.
:::warning
This feature is available for **Google Maps** only.
:::
### Custom binding
Let's say we have a field with id `dummy_field`, this field ID is not in the *address component* list so the plugin won't auto-populate data to it. To make the plugin auto-populate data (`administrative_area_level_1`) to that field, add the following parameter to the field:
With MB Builder:
or with code:
```php
'binding' => 'administrative_area_level_1', // returns 'Queensland'
```
You can tell that field to use the short version by prepending the `short:` keyword:
```php
'binding' => 'short:administrative_area_level_1', // returns 'QLD'
```
You can also merge two fields, and add any character you want to bind to that field. Like so:
```php
'binding' => 'city + " " + country', // returns QLD Australia
```
### Multiple addresses
In case you have multiple "groups" of address fields, such as address details for head office and address details for a company branch. In each group, there is an autocomplete address field. And it will auto-populate only fields in the group, e.g. the address for head office only populates the fields in the head office group, not in the company branch.
In this case, please set another attribute `'address_field' => 'address_id'` for *each* field in the group. See an example code below:
If you do with code, then your field group looks like this:
```php
/**
* Head office
*/
// Address
[
'id' => 'address_ho',
'name' => 'Address - Head Office',
],
// City
[
'id' => 'city_ho',
'name' => 'City - Head Office',
'binding' => 'locality',
// highlight-next-line
'address_field' => 'address_ho',
],
/**
* A company branch
*/
// Address
[
'id' => 'address_br',
'name' => 'Address - Branch',
],
// City
[
'id' => 'city_br',
'name' => 'City - Branch',
'binding' => 'locality',
// highlight-next-line
'address_field' => 'address_br',
],
```
## Two-way data binding
If you have a map field, then whenever you *change an address or manually change the value of latitude and longitude fields, the pin on the map will change* according to the new location.
And whenever you *change the pin location, the latitude and longitude will change* (if you have these fields).
However, if you change the pin location, the address field will *NOT* change.
# MB Group
import Helpers from '../_parts/_helpers.md';
**MB Group** helps you to organize custom fields into repeatable and collapsible groups. You can use this extension to group related fields into one group to create hierarchy. You can clone the whole group, or sub-group. There's no limitation on the nesting level.
## Tutorial
If this is your first time using [MB Group](/extensions/meta-box-group/), start with this beginner-friendly guide:
👉 [How to Create a Group of Custom Fields with MB Group](https://metabox.io/create-group-of-custom-fields-with-meta-box-group/)
The rest of this page is a detailed reference. Feel free to come back whenever you need to check specific settings or examples.
## Settings
MB Group introduces a new field type: `group`. Here are its available settings:
| Name | Description |
|----------------|-------------|
| `name` | Field label. Works like other fields. Optional. |
| `id` | Field ID, used to store the group's values (including all sub-fields). |
| `type` | Must be set to `group`. |
| `fields` | An array of sub-fields. Each sub-field is declared like a normal field. |
| `clone` | Makes the group clonable (repeater). |
| `sort_clone` | Allows drag-and-drop reordering of clones. `true` or `false`. |
| `collapsible` | Makes the group collapsible. `true` or `false` (default `false`). Optional. |
| `save_state` | Save the collapse/expand state? `true` or `false` (default `false`). Optional. |
| `default_state`| Default state when the page loads: `collapsed` or `expanded` (default). |
| `group_title` | Title of collapsible groups. See [Collapsible Groups](#collapsible-groups). |
### Example: Simple group with sub-fields
To add a group, create a field with `type => group` and list its sub-fields inside the `fields` parameter:
```php
add_filter( 'rwmb_meta_boxes', function ( $meta_boxes ) {
$meta_boxes[] = [
'title' => 'Album Tracks',
'fields' => [
[
'id' => 'standard',
'type' => 'group', // Group!
'clone' => true, // Clone whole group?
'sort_clone' => true, // Drag and drop clones to reorder them?
// List of sub-fields.
'fields' => [
[
'name' => 'Track name',
'id' => 'text',
],
[
'name' => 'Release Date',
'id' => 'date',
'type' => 'date',
],
[
'name' => 'Genre',
'id' => 'genre',
'type' => 'select_advanced',
'options' => [
'pop' => 'Pop',
'rock' => 'Rock',
],
],
],
],
],
];
return $meta_boxes;
} );
```
Here's how it looks:
### Nested groups
You can even put a group **inside another group**, creating multi-level nested structures:
```php
add_filter( 'rwmb_meta_boxes', function ( $meta_boxes ) {
$meta_boxes[] = [
'title' => 'Multi-level nested groups',
'fields' => [
[
'id' => 'group',
'type' => 'group',
'fields' => [
[
'name' => 'Text',
'id' => 'text',
],
// highlight-start
[
'name' => 'Sub group',
'id' => 'sub_group',
'type' => 'group',
'fields' => [
// Normal field (cloned)
[
'name' => 'Sub text',
'id' => 'sub_text',
],
],
],
// highlight-end
],
],
],
];
return $meta_boxes;
} );
```
✅ MB Group supports **unlimited nesting levels**.
### Collapsible groups
Want to make your groups collapsible? Just set:
```php
'collapsible' => true
```
Collapsible groups support extra settings:
| Name | Description |
| --------------- | ------------------------------------------------------------------------------------ |
| `save_state` | Save the expanded/collapsed state? `true` or `false`. Default `false`. |
| `default_state` | Default state when the page loads: `collapsed` or `expanded` (default). |
| `group_title` | Title of each group item. Can include static text, clone index, or sub-field values. |
#### Dynamic group titles
You can mix static text, clone index, and sub-field values in the `group_title`:
```php
'group_title' => 'Branch {#}: {sub_field_1} - {sub_field_2}',
```
- `{#}` → group index (if clonable).
- `{sub_field_id}` → value of a sub-field.
- Combine as many as you need.
#### Example: Collapsible group with nested groups
```php
add_filter( 'rwmb_meta_boxes', function ( $meta_boxes ) {
$meta_boxes[] = [
'title' => 'Company Branches',
'fields' => [
[
'id' => 'g1',
'name' => 'Branches',
'type' => 'group',
'clone' => true,
'collapsible' => true,
'group_title' => '{name}', // ID of the subfield
'fields' => [
[
'name' => 'Name',
'id' => 'name',
],
[
'name' => 'Address',
'id' => 'address',
],
[
'id' => 'contacts',
'type' => 'group',
'clone' => true,
'collapsible' => true,
'group_title' => '{person}',
'fields' => [
[
'id' => 'person',
'name' => 'Person',
],
[
'id' => 'phone',
'name' => 'Phone',
],
],
],
],
],
],
];
return $meta_boxes;
} );
```
## Data storage
- Group values are saved as an array of sub-field values (including nested groups).
- Data is stored in the database as a serialized array.
- Sub-field data is saved "as is" (no extra sanitizing or transformation).
:::warning
It's important to understand that when a field is placed inside a **group**, **its value is saved exactly as it is**. The plugin **does not apply any sanitization or transformation** when saving or retrieving field values. This behavior helps avoid heavy processing, especially when working with complex structures or deeply nested groups.
Example:
If you add a `date` field inside a group and set a `save_format` that differs from the display format, the `save_format` will **not** be applied. In this case, the saved value will always match the **displayed value** - no formatting changes are made during saving.
:::
## Getting sub-field values
To retrieve group data, use `rwmb_meta()`:
```php
$group_value = rwmb_meta( 'group_id' ) ?: [];
```
This returns an associative array of sub-field IDs and values:
```php
[
'sub_field_1' => 'value 1',
'sub_field_2' => 'value 2',
]
```
To access a sub-field:
```php
$value = $group_value['sub_field_1'] ?? '';
echo $value;
```
If the group is cloneable, `rwmb_meta()` returns an array of groups, like this:
```php
[
[ 'sub_field_1' => 'value 1', 'sub_field_2' => 'value 2' ],
[ 'sub_field_1' => 'value 3', 'sub_field_2' => 'value 4' ],
]
```
Loop through them:
```php
$groups = rwmb_meta( 'group_id' ) ?: [];
foreach ( $groups as $group ) {
echo $group['sub_field_1'] ?? '';
}
```
### Example: Contacts group
Registering a group of contacts:
```php
add_filter( 'rwmb_meta_boxes', function ( $meta_boxes ) {
$meta_boxes[] = [
'title' => 'Contacts',
'fields' => [
[
'id' => 'contacts',
'type' => 'group',
'clone' => true,
'fields' => [
[ 'id' => 'name', 'name' => 'Name' ],
[ 'id' => 'email', 'name' => 'Email' ],
[ 'id' => 'phone', 'name' => 'Phone' ],
],
],
],
];
return $meta_boxes;
} );
```
Displaying contacts in `single.php`:
```php
$contacts = rwmb_meta( 'contacts' ) ?: [];
foreach ( $contacts as $contact ) {
echo '
';
echo '
Contact info
';
echo '
Name: ' . $contact['name'] . '
';
echo '
Email: ' . $contact['email'] . '
';
echo '
Phone: ' . $contact['phone'] . '
';
echo '
';
}
```
### Outputting groups with page builders
- ✅ Elementor and Oxygen: can output group sub-fields directly.
- ❌ Other builders (e.g., Beaver Builder, Divi): use an [MB View](/extensions/mb-views/) or a shortcode
Example shortcode (group with `title`, `images`, and `desc`):
```php
add_shortcode( 'my_group', function() {
$group = rwmb_meta( 'group_field_id' );
if ( empty( $group ) ) {
return '';
}
$output = '';
// Title
$title = $group['title'] ?? '';
$output .= $title ? '
';
}
// Description
$desc = $group['desc'] ?? '';
$output .= $desc ? wpautop( $desc ) : '';
return $output;
} );
```
Usage: Add `[my_group]` into your post/page content or page builder module.
### Sub-field values
`rwmb_meta()` returns **raw values** for sub-fields. It does not format them like it does for individual fields.
| Field type | Value |
| -------------------------- | --------------------------- |
| `taxonomy`, `user`, `post` | Object ID(s) |
| File & image fields | Attachment ID(s) |
| `map`, `osm` | `"latitude,longitude,zoom"` |
| `oembed` | URL |
| `wysiwyg` | Raw content (no ``) |
Example: getting image info from sub-fields:
```php
$group = rwmb_meta( 'group_id' );
$image_ids = $group['image_key'] ?? [];
foreach ( $image_ids as $id ) {
$image = RWMB_Image_Field::file_info( $id, ['size' => 'thumbnail'] );
echo '';
}
```
## Setting default values
There are 2 ways to set default values:
- Per sub-field → using `std` on each field.
- Whole group → using `std` on the group.
### Per sub-field
```php
add_filter( 'rwmb_meta_boxes', function( $meta_boxes ) {
$meta_boxes[] = [
'title' => 'Test Group Default Value',
'fields' => [
[
'type' => 'group',
'id' => 'group',
'fields' => [
[
'id' => 'name',
'name' => 'Name',
// highlight-next-line
'std' => 'My Name',
],
[
'type' => 'email',
'id' => 'email',
'name' => 'Email',
// highlight-next-line
'std' => 'myemail@domain.com',
],
],
]
],
];
return $meta_boxes;
} );
```
Result:
### Whole group
Instead of setting `std` for each field, define an array for the group:
```php
add_filter( 'rwmb_meta_boxes', function( $meta_boxes ) {
$meta_boxes[] = [
'title' => 'Test Meta Box',
'fields' => [
[
'type' => 'group',
'id' => 'group',
'fields' => [
[
'id' => 'name',
'name' => 'Name',
],
[
'type' => 'email',
'id' => 'email',
'name' => 'Email',
],
],
// highlight-start
'std' => [
'name' => 'My name',
'email' => 'myemail@domain.com',
],
// highlight-end
]
],
];
return $meta_boxes;
} );
```
If the group is **cloneable**, `std` should be an array of group values:
```php
'std' => [
[ 'name' => 'Name 1', 'email' => 'email1@domain.com' ],
[ 'name' => 'Name 2', 'email' => 'email2@domain.com' ],
],
```
And here is the result:
See this video for demonstration:
## Changing clone button text
Change the button label with `add_button`:
```php
[
'type' => 'group',
'name' => 'Tracks',
'id' => 'tracks',
// highlight-next-line
'add_button' => 'Add another track',
'fields' => [
// Sub-fields here.
],
],
```
## Clone default values
When cloning a group:
- If the group has `'clone_default' => true`, all sub-fields will use their default values.
- If a sub-field is cloneable, its own `clone_default` takes priority.
Learn more: [`clone_default` parameter](/cloning-fields/)
## Changing group titles with JavaScript
You can filter group titles with JavaScript:
```js
jQuery( function() {
// Change "myVendor/myPlugin" to your unique namespace
rwmb.hooks.addFilter( 'group.title', 'myVendor/myPlugin', function( title ) {
// Change the title and return the value here.
return title + ' Some random string';
} );
} );
```
## Known issues
- When cloning nested groups, input `id` attributes may change in unpredictable ways. Avoid relying on them in custom JavaScript.
- For `wysiwyg` fields inside cloneable groups, **don't end the field ID with `_{number}`** (like `_12`). This pattern is reserved by the clone script. Use another format instead.
# MB Include Exclude
This extension helps you to define advanced location rules for where to show field groups.
## Settings
To add include, exclude conditions to your meta box to show/hide it, you need to add parameter `include` or `exclude` accordingly to the meta box configuration.
Each parameter (`include`, `exclude`) is an array and has the same following elements:
- `relation`: The logical operator to combine conditions: `AND` or `OR`. Default is `OR`. Case insensitive. Optional.
If one of the following conditions matched (`relation` = `OR`) or all of the following conditions matched (`relation` = `AND`), then the meta box is shown (`include`) or hidden (`exclude`).
Parameter | Description
--- | ---
`ID` | List of post IDs, match if current post ID is in the list. Can be array or comma separated. Optional.
`parent` | List of post parent IDs, match if parent ID of the current post is in the list. Can be array or comma separated. Optional.
`slug` | List of post slugs, match if current post slug is in the list. Can be array or comma separated. Optional.
`template` | List of page templates, match if the current post has a page template in the list. Can be array or comma separated. Optional.
`category` | List of categories IDs or names or slugs, match if the current post has a category in the list. Can be array or comma separated. Optional.
`tag` | List of tag IDs or names or slugs, match if the current post has a tag in the list. Can be array or comma separated. Optional.
`{$taxonomy_slug}` | List of custom taxonomy terms' IDs or names or slugs. Here `taxonomy_slug` is the slug of the taxonomy (like `section`, `region`, etc.). Match if the current post has a term in the list. Can be array or comma separated. Optional.
`parent_category` | List of parent categories IDs or names or slugs, match if the current post has a parent category in the list. Can be array or comma separated. Optional.
`parent_tag` | List of parent tag IDs or names or slugs, match if the current post has a parent tag in the list. Can be array or comma separated. Optional.
`parent_{$taxonomy_slug}` | List of parent custom taxonomy terms' IDs or names or slugs. Here `taxonomy_slug` is the slug of the taxonomy (like `section`, `region`, etc.). Match if the current post has a parent term in the list. Can be array or comma separated. Optional.
`user_role` | List of user roles (`administrator`, `editor`, etc.), match if the current user has the role in the list. Can be array or comma separated. Optional.
`user_id` | List of user IDs, match if the current user has user ID in the list. Can be array or comma separated. Optional.
`edited_user_role`|Role of the being edited user. Works on the user profile or user edit screens only. Requires [MB User Meta](/extensions/mb-user-meta/) extension.
`edited_user_id`|User ID of the being edited user. Works on the user profile or user edit screens only. Requires [MB User Meta](/extensions/mb-user-meta/) extension.
`is_child` | Boolean, match if the current post/page is a child page or not. Optional.
`custom` | Name of the custom function that performs the check (returns `true` or `false`). This function will take 1 parameter the meta box array. Match if the function returns `true`. Optional. Since v1.0.1, function name can be a string or array(object, method name) or array(class, static method name)
## Sample code
```php
add_filter( 'rwmb_meta_boxes', 'prefix_include_exclude_demo' );
function prefix_include_exclude_demo( $meta_boxes ) {
$meta_boxes[] = array(
'title' => 'Include Meta Box',
// Register this meta box for posts matched below conditions
'include' => array(
// With all conditions below, use this logical operator to combine them. Default is 'OR'. Case insensitive. Optional.
'relation' => 'OR',
// List of post IDs. Can be array or comma separated. Optional.
'ID' => array( 1, 2 ),
// List of post parent IDs. Can be array or comma separated. Optional.
'parent' => array( 3, 4 ),
// List of post slugs. Can be array or comma separated. Optional.
'slug' => array( 'contact', 'about' ),
// List of page templates. Can be array or comma separated. Optional.
'template' => array( 'full-width.php', 'sidebar-page.php' ),
// List of categories IDs or names or slugs. Can be array or comma separated. Optional.
'category' => array( 1, 'Blog', 'another' ),
// List of tag IDs or names or slugs. Can be array or comma separated. Optional.
'tag' => array( 1, 'fun' ),
// Custom taxonomy. Optional.
// Format: 'taxonomy' => list of term IDs or names or slugs (can be array or comma separated)
'location' => array( 12, 'USA', 'europe' ),
'os' => array( 'Windows', 'mac-os' ),
// List of parent categories IDs or names or slugs. Can be array or comma separated. Optional.
'parent_category' => 'Parent',
// List of parent tag IDs or names or slugs. Can be array or comma separated. Optional.
'parent_tag' => 'Parent',
// Parent custom taxonomy. Optional.
// Format: 'parent_taxonomy' => list of term IDs or names or slugs (can be array or comma separated)
'parent_location' => array( 12, 'USA', 'europe' ),
// Check if current post/page is a child page
'is_child' => true,
// List of user roles. Can be array or comma separated. Optional.
'user_role' => 'administrator',
// List of user IDs. Can be array or comma separated. Optional.
'user_id' => array( 1, 2 ),
// Custom condition. Optional.
// Format: 'custom' => 'callback_function'
// The function will take 1 parameter which is the meta box itself
'custom' => 'manual_include',
),
'fields' => array(
array(
'name' => 'Name',
'id' => 'name',
'type' => 'text',
),
),
);
// 2nd meta box
$meta_boxes[] = array(
'title' => 'Exclude Meta Box',
// Don't register this meta box for posts matched below conditions
'exclude' => array(
'relation' => 'OR',
'ID' => array( 1, 2 ),
'parent' => array( 3, 4 ),
'slug' => array( 'contact', 'about' ),
'template' => array( 'full-width.php', 'left-sidebar.php' ),
'category' => array( 1, 'News' ),
'tag' => array( 1, 'fun' ),
'user_role' => array( 'administrator', 'editor' ),
'user_id' => array( 1, 2 ),
'location' => array( 12, 'USA', 'europe' ),
'os' => array( 'Windows', 'mac-os' ),
'is_child' => true,
'custom' => 'manual_exclude',
),
'fields' => array(
array(
'name' => 'Job',
'id' => 'job',
'type' => 'text',
),
),
);
return $meta_boxes;
}
function prefix_include_exclude_manual_include( $meta_box ) {
if ( $meta_box['title'] == 'Include Meta Box' )
return true;
return false;
}
```
## Using with Sage
[Sage](https://roots.io/sage/) is a starter theme made by Roots.io. The latest version 9 uses [Laravel Blade](https://laravel.com/docs/5.3/blade) as a template system. When using the MB Include Exclude extension to detect page template in Sage, it's important to remember that the extension uses the value WordPress stores in the database, e.g. the value in the Page Template dropdown, which is `views/mytemplatename.blade.php`. So the code for `template` rule will be:
```php
'template' => 'views/mytemplatename.blade.php',
```
# MB Pods Migration
MB Pods Migration extension helps you to migrate field groups, custom field data, and relationships from Pods to Meta Box.
:::warning
This extension only migrates the data created by Pods within a site. It doesn't migrate your website from local to the development environment (you'll need another plugin for this) nor the way you use the data like getting the data and displaying it on the front end. After the migration, just go to the database and check how it changes.
:::
## Backup the database
Before migrating data, make sure you have a backup of your database. During the migration process, because of the difference in [data format](/database/), the plugin will attempt to modify the existing data in custom fields created by Pods. We try to do it at a very minimum level and create a backup of fields for some specific cases, but it's still important to make a backup just in case something goes wrong.
## Migrate
Before migrating, make sure you keep Pods, Meta Box (required) and extensions (optional) activated. To know which extensions you might need, please see the **How it works** section below. Normally, if you use Meta Box AIO and keep all extensions activated, you don't have to worry about this.
To migrate, go to **Meta Box > Pods Migration** and click the **Migrate** button.
The plugin will show the process of migrating. When it's done, you'll see the text "Done".
## How it works
MB Pods Migration tries to migrate all the following data from Pods to Meta Box. Please note that not all data types and settings in Pods have an equivalent in Meta Box. The plugin will try to migrate as much as it can. The details are explained below:
### Post types and taxonomies
The plugin will migrate all custom post types and custom taxonomies created in Pods to Meta Box. This job requires the [MB Custom Post Type](/extensions/mb-custom-post-type/) extension. All the settings like labels and icons are migrated as well.
:::warning
**We must remove Pods post types and taxonomies** after migration, as we cannot change their status to 'Inactive'. Therefore, please ensure that all data is processed before proceeding with the deletion.
:::
### Field groups
Pods field groups are migrated to Meta Box's field groups, which requires [MB Builder](/extensions/meta-box-builder/). Most of the field group settings are the same as in Meta Box.
:::warning
**We must remove Pods field groups** after migration, as we cannot change their status to 'Inactive'. Therefore, please ensure that all data is processed before proceeding with the deletion.
:::
For **field group locations**, the basic rules are already supported in Meta Box and extensions. You might need extensions such as:
- [MB Term Meta](/extensions/mb-term-meta/): If you set locations for taxonomies.
- [MB User Meta](/extensions/mb-user-meta/): If you set locations for users.
- [MB Settings Page](/extensions/mb-settings-page/): If you set locations for settings page.
Besides, if you use complex locations, then you'll need [MB Include Exclude](/extensions/meta-box-include-exclude/) extension. Due to the difference in how plugins create rules, the plugin works the following way:
- If there's only one location group: the plugin will migrate all rules with operator `AND`.
- If there are multiple location groups: the plugin will take the first rule of each group and combine them with operator `OR`.
### Custom fields data
Most Pods field types work well with Meta Box, such as text, radio, select, etc. However, there's still a difference in how plugins store values in the database and we try to mimic the effect as much as possible. The settings for fields in Pods were previously stored in individual rows in the database (in a complex manner). We have now migrated them to a single 'settings' meta key and stored them in one row.
:::info Meta key
Pods stores the field values in the database with the meta key = field ID, which is the same as Meta Box. So, in most cases, we reuse these values. Only in cases that the data format is not compatible with Meta Box, we'll modify the value to match.
:::
### Settings Page
The plugin also migrates all Settings Page from Pods to Meta Box. You'll need the [MB Builder](/extensions/meta-box-builder/) and [MB Settings Page](/extensions/mb-settings-page/) to do this. We'll migrate the settings and data of all Pods settings page to Meta Box.
:::warning
**We must remove Pods settings page** after migration, as we cannot change their status to 'Inactive'. Therefore, please ensure that all data is processed before proceeding with the deletion.
:::
### Relationships
The plugin also migrates all relationships from Pods to Meta Box. You'll need the [MB Builder](/extensions/meta-box-builder/) and [MB Relationships](/extensions/mb-relationships/) to do this. As the settings are quite different between the plugins, we'll migrate the settings of all Pods relationships to many-to-many relationships in Meta Box.
Of course, the data of relationships (the connections between items) are also migrated.
:::warning
**We must remove Pods relationships** after migration, as we cannot change their status to 'Inactive'. Therefore, please ensure that all data is processed before proceeding with the deletion.
:::
# MB Rank Math
import LiteYouTubeEmbed from 'react-lite-youtube-embed';
import 'react-lite-youtube-embed/dist/LiteYouTubeEmbed.css';
MB Rank Math helps you to add content of custom fields to Rank Math Content Analysis to have better SEO score.
## Settings
To let Rank Math get a field's content to analyze, add `'rank_math_analysis' => true` to the field:
```php
[
'name' => 'My custom editor',
'id' => 'custom_content',
'type' => 'wysiwyg',
'rank_math_analysis' => true,
],
```
The plugin supports all types of fields, such as text, textarea and wysiwyg.
This is the video tutorial:
# MB Relationships
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
MB Relationships helps you create relationships between posts, terms, and users in WordPress. When you edit an item (post, term, or user), you can select other items to connect to. It works with all post types, custom taxonomies, and users, and supports many-to-many, one-to-many, many-to-one, and one-to-one relationships.
This is an example of a many-to-many relationship between events (a custom post type) and speakers (users).
The plugin uses a custom table for storing relationships and integrates with default WordPress queries to retrieve the connected items easily. Using a custom table has several benefits:
- Bidirectional by nature
- Easier querying items in both directions (`from` and `to`) or querying sibling items
- Not polluting the post/term/user meta tables
- Better performance
The custom table is automatically created when the plugin is activated.
## Creating relationships
You can create a relationship in either of the following ways:
- **Using [MB Builder](/extensions/meta-box-builder/)**, which provides a UI for creating relationships. This is a premium extension already bundled in [Meta Box Lite](https://metabox.io/lite/) or [Meta Box AIO](https://metabox.io/aio/).
- **Using code**.
Before going into the detailed settings of a relationship, note that when a relationship is created, you'll see a meta box (usually on the right side - this position can be changed). Inside that meta box, there is a field ([`post`](/fields/post/), [`taxonomy_advanced`](/fields/taxonomy-advanced/), or [`user`](/fields/user/) depending on the object type) for selecting connected items. The field is cloneable by default, or a single-select dropdown when **Has one relationship** is enabled. The settings are divided into 3 parts: settings for the relationship, the meta box, and the field.
Now let's see how to create a relationship with MB Builder.
### Using MB Builder
To create a relationship, go to **Meta Box > Relationships** and click **Add New**.
Here you can enter all the settings for the relationship and each side of the relationship (**From** and **To**).
#### Relationship settings
Name | Description
---|---
Delete data in database? | Whether to delete relationship data from the database when the relationship is deleted.
Reciprocal relationship | Whether the relationship is reciprocal, e.g. a relationship between items of the same type. If you enable this, make sure the settings for the "From" and "To" sides are the same.
When editing an item, the plugin shows a meta box for selecting connected items. For reciprocal relationships between items of the same type, the plugin shows 2 meta boxes (one for each "from" and "to" side) unless you enable this setting, which limits the UI to a single meta box.
#### Side settings
For each side, there are 3 tabs of settings:
- **General**: for general settings such as object type and post type.
- **Meta Box**: for extra meta box settings. These settings are the same as the field group settings when creating custom fields.
- **Field**: for extra field settings. These settings are the same as the field settings ([post](/fields/post/), [taxonomy_advanced](/fields/taxonomy-advanced/), or [user](/fields/user/) depending on the object type).
Name | Description
---|---
Object type | The type of object for this side. If you choose "Term" or "User", make sure [MB Term Meta](/extensions/mb-term-meta/) or [MB User Meta](/extensions/mb-user-meta/) is activated.
Post type | If you select object type = "Post", the post type settings appear so you can select the post type.
Taxonomy | If you select object type = "Term", the taxonomy settings appear so you can select the taxonomy.
Has one relationship | When enabled, each item on this side can connect to only one item on the other side. The field becomes a single-select dropdown, and the plugin enforces the limit when saving data. When enabled on the other side, items that are already connected elsewhere are hidden from the dropdown.
Empty message | The custom message displayed when there are no connections. Leave blank to use the default message "No connections".
Show admin filter | Add a select dropdown to filter posts by this relationship. Works only for posts.
Show as admin column | Show the connections in the admin list table for posts, terms, or users. When enabled, additional settings appear below.
Column position | The position of the admin column. Set it before, after, or in place of an existing column by choosing an option from the dropdown and selecting or entering the target column ID. The plugin provides a list of common WordPress columns - press the down arrow key to browse them. If you use a [custom admin column](/extensions/mb-admin-columns/), enter its column ID here.
Column title | Custom admin column title. Leave blank to use the default title from the relationship meta box.
Item link type | How each connected item appears in the admin column: linked to the edit screen, linked to view it on the frontend, or without links.
The plugin automatically creates meta boxes to let you select connected items. The meta box settings are very much like a [normal meta box](/creating-fields-with-code/#field-group-settings) when you create custom fields, but simpler.
Name | Description
---|---
Title | The custom meta box title. Leave blank to default to "Connected To" or "Connected From".
Context | Where to show the meta box.
Priority | The priority of the meta box. Meta boxes with higher priority appear first.
Style | The meta box style: default (with wrapper) and seamless (no wrapper).
Collapse by default | Whether to collapse the meta box when the edit page loads.
Custom CSS class | If you want to style your meta box, then enter a custom CSS class here.
To select connected items, the plugin uses Meta Box's [post](/fields/post/), [taxonomy advanced](/fields/taxonomy-advanced/), or [user](/fields/user/) field according to the object type of the relationship. This tab shows the settings for the field.
:::warning
These settings apply to the field displayed **on the other side** of the relationship - where you select items for this side.
So, if you have a relationship from `post` to `user` and you are configuring the "From" side (for `post`), the `post` field appears only when you are editing a `user` (the "To" side).
:::
Name | Description
---|---
Label | The field label. Leave empty to hide the label.
Label description | A description displayed below the field label.
Input description | A description displayed below the field input.
Placeholder | The placeholder text for the select dropdown.
Query args | Custom query args to get posts, terms, or users to select from. A set of key-value pairs representing arguments for `WP_Query` (posts), `get_terms` (terms), or `get_users` (users).
Max items | The maximum number of selected items. For one-to-one or one-to-many relationships, use **Has one relationship** in the General tab instead. `Max items` only limits how many rows appear in the field UI and does not enforce uniqueness on the other side.
Add more text | The custom text for the "Add more" button.
Before | Custom HTML to output before the field.
After | Custom HTML to output after the field.
Custom CSS class | If you want to style the field, then enter a custom CSS class here.
### Using code
The code below registers a relationship **from posts to pages**:
```php
add_action( 'mb_relationships_init', function() {
MB_Relationships_API::register( [
'id' => 'posts_to_pages',
'from' => 'post',
'to' => 'page',
] );
} );
```
This code shows 2 meta boxes on the post and page edit screens:
- For posts: a meta box to select connected pages.
- For pages: a meta box showing posts connected to that page.
If you want to register a relationship **from categories to posts**, use the following code:
```php
add_action( 'mb_relationships_init', function () {
MB_Relationships_API::register( [
'id' => 'categories_to_posts',
'from' => [
// highlight-start
'object_type' => 'term',
'taxonomy' => 'category',
// highlight-end
],
'to' => 'post',
] );
} );
```
Or register a relationship **from users to posts**:
```php
add_action( 'mb_relationships_init', function () {
MB_Relationships_API::register( [
'id' => 'users_to_posts',
'from' => [
// highlight-next-line
'object_type' => 'user',
],
'to' => 'post',
] );
} );
```
To register a **one-to-many** relationship (each product has one brand, each brand has many products), enable `has_one_relationship` on the side where each item has only one partner (the product/From side in this example):
```php
add_action( 'mb_relationships_init', function () {
MB_Relationships_API::register( [
'id' => 'products_to_brands',
'from' => [
'object_type' => 'post',
'post_type' => 'product',
'has_one_relationship' => true,
],
'to' => [
'object_type' => 'post',
'post_type' => 'brand',
],
] );
} );
```
For a **one-to-one** relationship, set `has_one_relationship` to `true` on both `from` and `to`.
#### Syntax
The main API function `MB_Relationships_API::register` has the following parameters:
Name|Description
---|---
`id`|The relationship ID (or type). Used to distinguish this relationship from others. Required.
`from`|The "from" side of the relationship. Required. See below for details.
`to`|The "to" side of the relationship. Required. See below for details.
`reciprocal`|Whether the relationship is reciprocal (`true` or `false`). Optional.
Both sides `from` or `to` accept various parameters for the connection and meta box:
- If you pass **a string** to `from` or `to`, the plugin treats it as the **post type**. The relationship is created between posts of the specified post types.
- If you pass **an array** to `from` or `to`, the array accepts the following parameters:
Name|Description
---|---
`object_type`|The object type the relationship is created from/to: `post` (default), `term` or `user`. Optional.
`post_type`|The post type if the `object_type` is set to `post`. Default `post`. Optional.
`taxonomy`|The taxonomy if the `object_type` is set to `term`.
`has_one_relationship`|Whether each item on this side can connect to only one item on the other side (`true` or `false`). Default `false`. For one-to-one, set `true` on both `from` and `to`.
`empty_message`|The message displayed when there are no connections.
`meta_box`|Meta box settings, has the [same settings as a normal meta box](/creating-fields-with-code/#field-group-settings). Below are common settings you might want to change:
-- `title`|The meta box title. Default is "Connect To" for "from" side and "Connected From" for "to" side.
`field`|Field settings, has the same settings as a [post](/fields/post/), [user](/fields/user/) or [taxonomy](/fields/taxonomy/) field according to the object type. Below are common settings you might want to change:
-- `name` | Field title.
-- `placeholder` | Placeholder text.
-- `query_args`|Custom query arguments to get objects of `object_type`. Passed to `WP_Query()`, `get_terms()`, or `get_users()` depending on `object_type`.
-- `max_clone` | Maximum number of connections. Does not enforce uniqueness on the other side. Use `has_one_relationship` for one-to-one or one-to-many relationships.
:::warning
The field settings apply to the field displayed **on the other side** of the relationship - where you select items for this side.
So, if you have a relationship from `post` to `user` and you are configuring the "From" side (for `post`), the `post` field appears only when you are editing a `user` (the "To" side).
:::
#### Admin column
The plugin supports showing connected items in the admin list table of posts/terms or users. To enable this feature, add the `admin_column` parameter to the `from` or `to` relationship configuration:
```php
MB_Relationships_API::register( [
'id' => 'posts_to_pages',
'from' => [
'object_type' => 'post',
// highlight-next-line
'admin_column' => true,
],
'to' => [
'object_type' => 'post',
'post_type' => 'page',
// highlight-next-line
'admin_column' => 'after title',
],
] );
```
Similar to [MB Admin Columns](/extensions/mb-admin-columns/), the plugin supports 3 formats of the parameter:
1. A boolean `true`: display the admin column at the end of the list table. The column title matches the connection meta box title.
1. A string such as `"before title"`: specify the column position. The first word is the placement (`"before"`, `"after"`, or `"replace"`) and the second is the target column ID.
1. An array of advanced settings, as below:
```php
'admin_column' => [
'position' => 'after title',
'title' => 'Price',
'link' => 'edit',
],
```
Key|Description
---|---
`position`|Specify where to insert the new column. It's the same as described in the #2 method above.
`title`|Column title. Optional. Default is the meta box title.
`link`|Configure the link for items in the admin column. Can be `view` (link to the frontend - default), `edit` (link to the edit screen), or `false` (no link).
### Bi-directional relationships
While relationships are registered with distinct "from" and "to" sides, the connections themselves are bi-directional. You can query in either direction without issue. The query API is explained in the next section.
The data is stored in the database as a pair of (from_id, to_id), making it independent of either side.
## Getting connected items
### API
Using the API is the fastest and simplest way to get connected items:
```php
$pages = MB_Relationships_API::get_connected( [
'id' => 'posts_to_pages',
'from' => get_the_ID(),
] );
foreach ( $pages as $p ) {
echo $p->post_title;
}
```
If you need more control over connected items (like sorting or limiting the number of items), see the sections below for each type of content.
### Posts
To get pages connected to a specific post, use the following code:
```php
[
'id' => 'posts_to_pages',
'from' => get_the_ID(), // You can pass object ID or full object
],
'nopaging' => true,
] );
while ( $connected->have_posts() ) : $connected->the_post();
?>
[
'id' => 'posts_to_pages',
'to' => get_the_ID(), // You can pass object ID or full object
],
'nopaging' => true,
] );
```
That's all.
**Why use `WP_Query()`?**
There are 3 reasons to use `WP_Query()`:
1. **Flexibility** - You can combine relationship queries with other criteria. For example, get related posts *and* filter by category in a single query. Without `WP_Query()`, you would need two separate queries.
1. **Performance** - `WP_Query()` is optimized for posts and runs a single database query. It returns full post objects by default, or just IDs if you set `'fields' => 'ids'`.
1. **Familiarity** - `WP_Query()` is standard in WordPress development. There is no need for a separate query API for the same purpose.
Also note that in the example above, `nopaging` is set to `true`, which disables pagination so the query returns all connected posts.
For the full list of supported parameters for `WP_Query()`, please see the [documentation](https://developer.wordpress.org/reference/classes/wp_query/).
### Terms
Similar to posts, getting connected terms is simple:
```php
$terms = get_terms( [
'taxonomy' => 'category',
'hide_empty' => false,
'relationship' => [
'id' => 'categories_to_posts',
'to' => get_the_ID(), // You can pass object ID or full object
],
] );
foreach ( $terms as $term ) {
echo $term->name;
}
```
We use the WordPress `get_terms()` function with an additional `relationship` parameter for the same reasons as posts.
For the full list of supported parameters for `get_terms()`, please see the [documentation](https://developer.wordpress.org/reference/functions/get_terms/).
### Users
Similar to posts, getting connected users is simple:
```php
$users = get_users( [
'relationship' => [
'id' => 'users_to_posts',
'to' => get_the_ID(), // You can pass object ID or full object
],
] );
foreach ( $users as $user ) {
echo $user->display_name;
}
```
We use the WordPress `get_users()` function with an additional `relationship` parameter for the same reasons as posts.
For the full list of supported parameters for `get_users()`, please see the [documentation](https://codex.wordpress.org/Function_Reference/get_users).
### Current item
In the examples above, we use `get_the_ID()` to get the current post ID. That function does not work when querying connected posts from a relationship such as `categories_to_posts` on a term archive.
In those cases, use the following functions:
Function|Description
---|---
[`get_queried_object()`](https://codex.wordpress.org/Function_Reference/get_queried_object)|Returns the currently queried object. On a single post or page, it returns the post object. On a category archive, it returns the category object, and so on. Note that `from` and `to` accept both an object ID and a full object.
[`get_queried_object_id()`](https://developer.wordpress.org/reference/functions/get_queried_object_id/)|Returns the ID of the currently queried object. Same as above, but returns only the ID.
[`get_current_user_id()`](https://developer.wordpress.org/reference/functions/get_current_user_id/)|Returns the current user ID.
## Getting sibling items
Assume you have 2 custom post types: `student` and `class`. Each student can join 1 or more classes (many-to-many relationship). How do you get the classmates of a given student?
To get siblings of a post, add `'sibling' => true` to the query:
```php
$siblings = new WP_Query( [
'relationship' => [
'id' => 'posts_to_pages',
'to' => get_the_ID(),
// highlight-next-line
'sibling' => true,
],
'nopaging' => true,
] );
```
The code is similar to the above section, except for the extra `sibling` parameter. That parameter works for all post, term, or user queries.
## Post archive
All the examples above work well for a single post, term, or user. On a blog archive page, however, querying connected posts per item creates dozens of extra queries - one per post on the page.
To solve this problem, we need to use the following code:
```php
global $wp_query, $post;
MB_Relationships_API::each_connected( [
'id' => 'posts_to_pages',
'from' => $wp_query->posts, // 'from' or 'to'.
] );
while ( have_posts() ) : the_post();
// Display connected pages
foreach ( $post->connected as $p ) :
echo $p->post_title;
// More code here...
endforeach;
endwhile;
```
### How does it work?
On each request, WordPress automatically runs a query that finds the appropriate posts to display. These posts are stored in the global `$wp_query` variable.
The API function `MB_Relationships_API::each_connected()` will take a list of posts from `$wp_query->posts` and pull the related pages from the database (with a single database query) and assign them to each post via the `connected` property. So, you can loop through `$post->connected` and display connected pages.
If you use a custom query instead of the default WordPress query, pass the array of post objects to the function:
```php
$my_query = new WP_Query( [
// your parameters
] );
MB_Relationships_API::each_connected( [
'id' => 'posts_to_pages',
'from' => $my_query->posts, // Set to $my_query.
] );
while ( $my_query->have_posts() ) : $my_query->the_post();
// Display connected pages
foreach ( $post->connected as $p ) :
echo $p->post_title;
// More code here.
endforeach;
endwhile;
```
The property name can be customized with `'property' => 'your_property_name'`. See the sections below.
### Multiple connections
If you have multiple relationships between objects, you can call `each_connected()` multiple times:
```php
// Get connected pages and assign them to property 'connected_pages'.
MB_Relationships_API::each_connected( [
'id' => 'posts_to_pages',
'from' => $wp_query->posts,
'property' => 'connected_pages',
] );
// Get connected users and assign them to property 'artists'.
MB_Relationships_API::each_connected( [
'id' => 'users_to_posts',
'from' => $wp_query->posts,
'property' => 'artists',
] );
while ( have_posts() ) : the_post();
// Display connected pages
foreach ( $post->connected_pages as $post ) : setup_postdata( $post );
the_title();
...
endforeach;
wp_reset_postdata(); // Set $post back to original post
// Display connected users
foreach ( $post->artists as $artist ) :
echo $artist->display_name;
endforeach;
endwhile;
```
### Nesting
Since `each_connected()` accepts an array of post objects, nested queries are straightforward:
```php
$my_query = new WP_Query( [
'post_type' => 'movie'
] );
MB_Relationships_API::each_connected( [
'id' => 'movies_to_actors',
'from' => $my_query->posts,
'property' => 'actors',
] );
while ( $my_query->have_posts() ) : $my_query->the_post();
// Another level of nesting
MB_Relationships_API::each_connected( [
'id' => 'actors_to_producers',
'from' => $post->actors,
'property' => 'producers',
] );
foreach ( $post->actors as $post ) : setup_postdata( $post );
echo '
Connected Producers
';
foreach ( $post->producers as $post ) : setup_postdata( $post );
the_title();
...
endforeach;
endforeach;
wp_reset_postdata();
endwhile;
```
## Query by multiple relationships
For example, if you have event-to-band and event-to-artist relationships and want to get all bands and artists connected to an event, use the following:
```php
$query = new WP_Query( [
'relationship' => [
'relation' => 'OR',
[
'id' => 'events_to_bands',
'from' => get_the_ID(),
],
[
'id' => 'events_to_artists',
'from' => get_the_ID(),
],
],
'nopaging' => true,
] );
while ( $query->have_posts() ) {
$query->the_post();
echo get_the_title() . ' ';
}
wp_reset_postdata();
```
## Managing connections programmatically
The plugin provides public APIs to create or delete connections between two items in code.
### `has`
This function checks whether two objects have a specific relationship.
```php
$has_connection = MB_Relationships_API::has( $from, $to, $id );
if ( $has_connection ) {
echo 'They have a relationship.';
} else {
echo 'No, they do not have any relationship.';
}
```
Name|Description
---|---
`$from`|The ID of the "from" object.
`$to`|The ID of the "to" object.
`$id`|The relationship ID.
### `add`
This function adds a relationship between two objects.
```php
MB_Relationships_API::add( $from, $to, $id, $order_from = 1, $order_to = 1 );
```
This function checks whether the two objects already have a relationship and adds one only if they do not. If **has one relationship** is enabled, it also returns `false` when either side already has a connection.
When the `add` function runs, the plugin fires the following hook:
```php
do_action( 'mb_relationships_add', $from, $to, $id, $order_from, $order_to );
```
### `delete`
This function deletes a specific relationship between two objects.
```php
MB_Relationships_API::delete( $from, $to, $id );
```
This function deletes a relationship between two objects only if one exists.
When the `delete` function runs, the plugin fires the following hook:
```php
do_action( 'mb_relationships_delete', $from, $to, $id );
```
## Shortcode
The plugin provides a single flexible shortcode to display connected items.
```php
[mb_relationships id="posts_to_pages" direction="from" mode="ul"]
```
It accepts the following parameters:
Name|Description
---|---
`id`|Relationship ID. Required.
`items`|List of item IDs to get connected items from or to. Optional. If omitted, the shortcode uses the current object ID.
`direction`|Direction to query: `from` (default) or `to`. Optional.
`mode`|How to display connected items: `ul` (unordered list - default), `ol` (ordered list), `inline` (comma-separated), or `custom`.
`separator`|The separator between connected items if `mode` is set to `custom`. Optional.
## Database
The relationship data is stored in a custom table `mb_relationships` with the following columns:
Column|Description
---|---
`ID`|The connection ID
`from`|The ID of the "from" object
`to`|The ID of the "to" object
`type`|The relationship ID (type)
`order_from`|The order of the item for the "from" side
`order_to`|The order of the item for the "to" side
This structure allows us to create simple and efficient queries. All columns are also indexed to optimize for speed.
If you use the extension as a separate plugin (not bundled inside another), the table is created during plugin activation. This is ideal because the plugin checks for the table only once.
If you bundle the extension inside another plugin, the table is checked and created when the extension loads. The check is fast, but it still adds a small query on each request.
## REST API
The plugin provides REST API endpoints so you can retrieve and update related items from external sources.
Note: each relationship must first be created using [any of the supported methods](#creating-relationships).
### Check for the existence of a connection
Send a `GET` request to `/wp-json/mb-relationships/v1/{id}/exists?from={from ID}&to={to ID}`.
By default, this endpoint does not require authentication or authorization; use the `mb_relationships_rest_api_can_read_relationships` and/or `mb_relationships_rest_api_can_read_relationships_public` filter to modify this.
Example:
```shell
curl --request GET --url 'https://example.test/wp-json/mb-relationships/v1/posts_to_pages/exists?from=14773&to=13577'
```
```json
{
"has_relationship": true,
"relationship": "posts_to_pages",
"to": 13577,
"from": 14773
}
```
### Get all "to" objects for a specified "from" object
Send a `GET` request to `/wp-json/mb-relationships/v1/{id}/connected-from/{from ID}`.
By default, this endpoint does not require authentication or authorization; use the `mb_relationships_rest_api_can_read_relationships` and/or `mb_relationships_rest_api_can_read_relationships_public` filter to modify this.
Example:
```shell
curl --request GET --url 'https://example.test/wp-json/mb-relationships/v1/posts_to_pages/connected-from/14773'
```
```json
{
"relationship": "posts_to_pages",
"from": 14773,
"to": [
13577,
13578,
13579,
],
}
```
### Get all "from" objects for a specified "to" object
Send a `GET` request to `/wp-json/mb-relationships/v1/{id}/connected-to/{to ID}`.
By default, this endpoint does not require authentication or authorization; use the `mb_relationships_rest_api_can_read_relationships` and/or `mb_relationships_rest_api_can_read_relationships_public` filter to modify this.
Example:
```shell
curl --request GET --url 'https://example.test/wp-json/mb-relationships/v1/posts_to_pages/connected-to/13577'
```
```json
{
"relationship": "posts_to_pages",
"from": [
14773,
14775,
14777,
],
"to": 13577,
}
```
### Create a new connection
Send a `POST` request to `/wp-json/mb-relationships/v1/{id}` with body parameters `from` and `to`.
By default, this endpoint requires a user with `publish_posts` capability (administrator role); use the `mb_relationships_rest_api_can_create_relationships` and/or `mb_relationships_rest_api_can_create_relationships_public` filter to modify the capabilities.
Example:
```shell
curl --request POST \
--url https://example.test/wp-json/mb-relationships/v1/posts_to_pages \
--header 'Authorization: Basic dXNlcjpwYXNzd29yZA==' \
--header 'Content-Type: multipart/form-data' \
--form from=14773 \
--form to=13952
```
```json
{
"has_relationship": true,
"relationship": "posts_to_pages",
"to": 13577,
"from": 14773
}
```
### Delete a connection
Send a `DELETE` request to `/wp-json/mb-relationships/v1/{id}?from={from ID}&to={to ID}`.
By default, this endpoint requires a user with `delete_posts` capability (administrator role); use the `mb_relationships_rest_api_can_delete_relationships` and/or `mb_relationships_rest_api_can_delete_relationships_public` filter to modify the capabilities.
Example:
```shell
curl --request DELETE \
--url 'https://example.test/wp-json/mb-relationships/v1/team_member_to_location?from=14773&to=13952' \
--header 'Authorization: Basic dXNlcjpwYXNzd29yZA=='
```
```json
{
"has_relationship": false,
"relationship": "posts_to_pages",
"to": 13577,
"from": 14773
}
```
# MB Rest API
import LiteYouTubeEmbed from 'react-lite-youtube-embed';
import 'react-lite-youtube-embed/dist/LiteYouTubeEmbed.css';
[MB Rest API](https://metabox.io/plugins/mb-rest-api/) helps you get and update custom fields via the WordPress Rest API. It's very helpful if you develop an application that uses WordPress as a back end such as a mobile app, or if you need to integrate WordPress with another system.
The extension works only with custom fields created by Meta Box and extensions. For custom custom fields or fields created by other plugins, please refer to [WordPress documentation](https://developer.wordpress.org/rest-api/).
## Endpoints
For posts, terms, users, and comments, MB Rest API doesn't create new Rest API endpoints. Instead, the plugin **extends the [existing WordPress endpoints](https://developer.wordpress.org/rest-api/reference/) for getting and updating data**.
Any custom field groups added to WordPress data like posts (including all custom post types), users, and categories (including all custom taxonomies), will be available in their respective WP REST API endpoints, namely:
```
/wp/v2/{post-type}
posts, pages, custom-post-types, etc.
/wp/v2/{post-type}/{post_id}
/wp/v2/{custom-taxonomy}
categories, tags, custom-taxonomy, etc.
/wp/v2/{custom-taxonomy}/{term_id}
/wp/v2/users
/wp/v2/users/{user_id}
/wp/v2/comments
/wp/v2/comments/{comment_id}
```
**For [settings pages](https://metabox.io/plugins/mb-settings-page/)**, because WordPress doesn't have any endpoints to get and update options, the plugin provides a custom endpoint as follows:
```
/meta-box/v1/settings-page
```
We'll see how to use these endpoints below.
## Request methods
MB Rest API uses standard methods as follows:
- `GET`: for getting Meta Box fields
- `POST`: for updating Meta Box fields and requires you to authenticate to perform the request.
## Getting custom fields for posts
Assuming you have a [custom post type](/custom-post-types/) called "Event" and you [create a field group](/custom-fields/) "Event details" for it like this:
And then enter the data for an event:
**Instead of creating extra Rest endpoints, which introduce a new API and syntax, MB Rest API extends the [existing WordPress endpoint for posts](https://developer.wordpress.org/rest-api/reference/posts/#retrieve-a-post) to add data for Meta Box's fields.**
So if the event post ID is `5837`, then you'll need to make a `GET` request to retrieve post data via the standard WordPress post endpoint: `https://domain.com/wp-json/wp/v2/event/5837`.
Here is a sample cURL request:
```bash
curl https://domain.com/wp-json/wp/v2/event/5837
```
or you can [get the data with JavaScript via the Fetch API](https://metabox.io/send-get-post-request-with-javascript-fetch-api/) like this:
```js
const request = await fetch( 'https://domain.com/wp-json/wp/v2/event/5837' );
const response = await request.json();
console.log( response );
```
:::warning Custom post type rest API support
If you use Rest API for a custom post type, make sure you enable Rest API support for it. You can do that with our [MB Custom Post Types & Custom Taxonomies](/extensions/mb-custom-post-type/) or with code according to the [WordPress docs](https://developer.wordpress.org/rest-api/extending-the-rest-api/adding-rest-api-support-for-custom-content-types/). In this article, we're using the "Event" post type which has Rest API supports, and the Rest API base is `event`.
:::
The response is a JSON string that contains full post details (which come from the default WordPress Rest API response) and **also custom fields from Meta Box**. **The Meta Box fields are available in the `meta_box` key** of the response (which is highlighted in the red rectangle in the screenshot from Insomnia above).
Here is the full JSON response with Meta Box fields highlighted:
```json
{
"id": 5837,
"date": "2023-07-10T11:41:57",
"date_gmt": "2023-07-10T04:41:57",
"guid": {
"rendered": "http:\/\/mb.test\/?post_type=event&p=5837"
},
"modified": "2023-09-27T09:25:51",
"modified_gmt": "2023-09-27T02:25:51",
"slug": "php-day-in-london-july-2023",
"status": "publish",
"type": "event",
"link": "http:\/\/mb.test\/event\/php-day-in-london-july-2023\/",
"title": {
"rendered": "PHP Day in London – July 2023"
},
"content": {
"rendered": "",
"protected": false
},
"featured_media": 0,
"template": "",
"topic": [
85
],
// highlight-start
"meta_box": {
"vanue": "City of London, Greater London, England, United Kingdom",
"map": {
"latitude": "51.5156177",
"longitude": "-0.0919983",
"zoom": "14"
},
"date": "2023-09-30 08:00",
"speakers": [
{
"name": "Brian Garney",
"company": "Hometown",
"work_title": "Developer"
},
{
"name": "Ryan Coords",
"company": "365Devs",
"work_title": "CTO"
}
],
"price": "50",
"buy_ticket_url": "https:\/\/amazon.com\/events\/london\/129.html"
},
// highlight-end
"_links": {
"self": [
{
"href": "http:\/\/mb.test\/wp-json\/wp\/v2\/event\/5837"
}
],
"collection": [
{
"href": "http:\/\/mb.test\/wp-json\/wp\/v2\/event"
}
],
"about": [
{
"href": "http:\/\/mb.test\/wp-json\/wp\/v2\/types\/event"
}
],
"wp:attachment": [
{
"href": "http:\/\/mb.test\/wp-json\/wp\/v2\/media?parent=5837"
}
],
"wp:term": [
{
"taxonomy": "topic",
"embeddable": true,
"href": "http:\/\/mb.test\/wp-json\/wp\/v2\/topic?post=5837"
}
],
"curies": [
{
"name": "wp",
"href": "https:\/\/api.w.org\/{rel}",
"templated": true
}
]
}
}
```
If you have multiple field groups for a post, then **all fields are merged into a single key `meta_box`** in the response.
If you're using an API testing app like [Postman](https://www.postman.com/) or [Insomnia](https://insomnia.rest/), then you can preview the response in a beautiful format. This is the same request and response created with Insomnia, our favorite API client that we'll use throughout this article (click to enlarge the image):
:::success Tip
If you don't have Postman or Insomnia and don't want to use a command line, you can simply open the Rest API URL in your browser (Firefox or Google Chrome). They'll show you the response in JSON. Firefox even automatically formats it beautifully.
:::
:::info Data format
Note that the data returned from the Rest API is auto-formatted. For example, for maps, you'll see an array of latitude, longitude, and zoom as in the example above (not the plain text "latitude,longitude,zoom" as in the database). For other fields, like images and files, you'll get more information for the fields, just like you do with the helper functions [`rwmb_meta`](/functions/rwmb-meta/) or [`rwmb_get_value`](/functions/rwmb-get-value/).
:::
## Updating custom fields for posts
To update custom fields via Rest API, we'll need to perform a `POST` request to the same Rest endpoint. Because `POST` request allows you to change data, you'll need to authenticate your requests, using one of the [available authentication methods](#authentication). In this request, we'll need to pass the data as a JSON encoded object, which contains a key `meta_box` for Meta Box fields:
```json
{
"meta_box": {
"field_1": "value_1",
"field_2": "value_2"
}
}
```
Below is an example of a `POST` request to update an event using cURL:
```bash
curl --request POST \
--url http://mb.test/wp-json/wp/v2/event/5837/ \
--user 'USERNAME:PASSWORD'
--header 'Content-Type: application/json' \
--data '{
"title": "London PHP Day 2023",
"meta_box": {
"price": "45",
"buy_ticket_url": "https://ticketbox.com/e/5837"
}
}'
```
If you use JavaScript, you can make a `POST` request with the WordPress [apiFetch](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-api-fetch/) utility:
```js
import apiFetch from '@wordpress/api-fetch';
apiFetch( {
path: '/wp/v2/event/5837',
method: 'POST',
data: {
title: "London PHP Day 2023",
meta_box: {
price: "45",
buy_ticket_url: "https://ticketbox.com/e/5837"
}
},
} ).then( res => console.log( res ) );
```
(Note that you can use [vanilla JavaScript with Fetch API to send a `POST` request](https://metabox.io/send-get-post-request-with-javascript-fetch-api/). In this example, we use the WordPress library for simplicity and clarity.)
Or if you prefer to use an API testing tool like Postman or Insomnia, you can do that as well (click the image to enlarge):
The response from the update requests is not important as long as the returned status is `200 OK`. This response is simply the same as retrieving data via `GET`, which can be used to examine the data after updating.
In case you use [a group field](/extensions/meta-box-group/), and you want to update a whole group, you can pass it as a full JSON object like this:
```json
{
"title": "London PHP Day 2023",
"meta_box": {
"price": "45",
"buy_ticket_url": "https://ticketbox.com/e/5837",
"speakers": [
{
"name": "Brian Garney",
"company": "eLightUp",
"work_title": "Developer"
},
{
"name": "Ryan Coords",
"company": "365Devs",
"work_title": "CTO"
}
]
}
}
```
## Getting & updating custom fields for terms, users, comments
If you want to get fields' values for other object types like terms or users, simply change the Rest API endpoint. WordPress provides a [full list of endpoint references](https://developer.wordpress.org/rest-api/reference/) that you can take a look at (`1234` is a sample ID):
Posts, pages, and custom post types:
```bash
https://domain.com/wp-json/wp/v2/posts/
https://domain.com/wp-json/wp/v2/posts/1234
https://domain.com/wp-json/wp/v2/pages/
https://domain.com/wp-json/wp/v2/pages/1234
https://domain.com/wp-json/wp/v2/post-type-slug/
https://domain.com/wp-json/wp/v2/post-type-slug/1234
```
Categories, tags, and custom taxonomies:
```bash
https://domain.com/wp-json/wp/v2/categories/
https://domain.com/wp-json/wp/v2/categories/1234
https://domain.com/wp-json/wp/v2/tags/
https://domain.com/wp-json/wp/v2/tags/1234
https://domain.com/wp-json/wp/v2/custom-taxonomy-slug/
https://domain.com/wp-json/wp/v2/custom-taxonomy-slug/1234
```
Users:
```bash
https://domain.com/wp-json/wp/v2/users/
https://domain.com/wp-json/wp/v2/users/1234
```
Comments:
```bash
https://domain.com/wp-json/wp/v2/comments/
https://domain.com/wp-json/wp/v2/comments/1234
```
## Getting settings pages
Unlike posts, terms, or users, WordPress doesn't have any endpoints to get and update options, so the plugin provides a custom endpoint for settings pages as follows:
```
/meta-box/v1/settings-page
```
To get settings page data, simply create a `GET` request to this endpoint with a **required parameter `id`, which is the settings page ID**. Please note that to get settings page data, you need to have a proper capability. See the [authentication](#authentication) section below for details.
Here is an example with cURL:
```bash
curl --request GET \
--url 'https://domain.com/wp-json/meta-box/v1/settings-page?id=website-settings' \
--user 'USERNAME:PASSWORD'
```
Or via JavaScript with WordPress [apiFetch](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-api-fetch/) library:
```js
import apiFetch from '@wordpress/api-fetch';
apiFetch( {
path: `/meta-box/v1/settings-page?id=website-settings`,
} ).then( res => console.log( res ) );
```
The response is a JSON with all settings page data:
```json
{
"address": "4812 Jones Avenue, Winston Salem, NC 27108",
"phone": "+1-336-720-4261",
"email": "info@jourrapide.com"
}
```
You can also perform the request in Postman or Insomnia like this:
## Updating settings pages
To update a settings page, simply make a `POST` request to the settings page's endpoint `/meta-box/v1/settings-page` with data as JSON like this:
```json
{
"id": "settings-page-id",
"data": {
"field_1": "value_1",
"field_2": "value_2",
}
}
```
Here is an example with cURL:
```bash
curl --request POST \
--url http://mb.test/wp-json/meta-box/v1/settings-page \
--user 'USERNAME:PASSWORD' \
--header 'Content-Type: application/json' \
--data '{
"id": "website-settings",
"data": {
"address": "412 Jones Avenue, Winston Salem, NC 27108",
"phone": "+1-336-720-4621",
"email": "contact@jourrapide.com"
}
}'
```
or via JavaScript with WordPress [apiFetch](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-api-fetch/) library:
```js
import apiFetch from '@wordpress/api-fetch';
apiFetch( {
path: '/meta-box/v1/settings-page',
method: 'POST',
data: {
id: "website-settings",
data: {
address: "412 Jones Avenue, Winston Salem, NC 27108",
phone: "+1-336-720-4621",
email: "contact@jourrapide.com"
}
},
} ).then( res => console.log( res ) );
```
You can also perform the request in Postman or Insomnia like this:
## Hiding a field
By default, Meta Box returns all fields for the REST API responses. If you want to hide a field from the responses, then you need to set a settings for it.
If you use [MB Builder](/extensions/meta-box-builder/) to build the field group, please enable the settings **Hide from REST API** in the **Advanced** panel from the field's **Settings** panel:
If you use code to register fields, please set the field as follows:
```php
[
'id' => 'gallery',
'name' => 'Gallery',
'type' => 'image_advanced',
// highlight-next-line
'hide_from_rest' => true,
]
```
## Authentication
For **posts, terms, users, and comments**, authentication is required when you **update data** via Rest API. The plugin uses the default WordPress authentication methods. This means that if you are building something in the WordPress dashboard, the code will be run in an already logged-in session, and no specific authentication is needed.
If you build something using the REST API endpoints outside a logged-in session (for example a JavaScript application powered by the REST API), you will need to authenticate for any POST requests. Please refer to the [WordPress documentation](https://developer.wordpress.org/rest-api/using-the-rest-api/authentication/) for doing this.
For **settings pages**, authentication is **required for both getting and updating data**. In addition, as the settings page has a parameter `capability`, it requires the current user that is making the request must have that specific capability.
For example, if you create a settings page for users with `manage_options` capability (admins), then when making requests to get and update settings page data, make sure you have the same `manage_options` capability.
## Video tutorial
Here is a quick video tutorial we created to demonstrate how to use Postman to get and update custom fields for posts:
# MB Revision
MB Revision adds support for custom fields in WordPress revision that helps you to track changes of custom fields.
## Enabling revision support
First of all, please make sure that you didn't turn off revision in WordPress. To check this, please open your `wp-config.php` and see if this line presents:
```php
define( 'WP_POST_REVISIONS', false );
```
If you can't find it, that means revision is turned on, which is great!
To enable revision support for a meta box, add a new setting to the meta box as follows:
```php
'revision' => true,
```
Now whenever you update a post, WordPress will create a revision for it. And MB Revision ensures all the values of the custom fields are copied from the parent post to that revision.
## Comparing the changes
When you update a post, WordPress automatically creates a revision for that post. You can see the list of revisions in the **Revisions** meta box below the main editor:
Also, in the **Publish** meta box, you'll see a link to browse all revisions:
Clicking either on any revision in the list or on *Browse* link brings you to the revision comparison screen. There you'll see something like this:
Except title and content, which are post fields, other items on this screen are custom fields created by Meta Box. There you'll see highlighted lines or words, which are added or removed by users.
If the custom field has simple value (like a string), it will display fully here. If the custom field has structural value (array), it will display here as a JSON-encoded string. Using JSON allows you to see the values of each element in the array as well as the structure in general.
Please note that the extension works well with [MB Group](/extensions/meta-box-group/) extension.
## Restoring the revision
If you find out that the current version of the post is incorrect, you can compare it with the previous version and optionally restore it. In order to restore a revision, lick on the **Restore this revision** button on the comparison screen.
MB Revision will copy values of the custom fields from the revision to the parent post. So your post will have the correct values of custom fields like it used to be.
## Notes
Because WordPress supports revision for posts and custom post types only, the extension doesn't work for [term meta](/extensions/mb-term-meta/), [user meta](/extensions/mb-user-meta/) or [settings pages](/extensions/mb-settings-page/).
Please make sure you either not define `WP_POST_REVISIONS` or set it to a proper value in `wp-config.php`. This constant disables or limits the number of revisions. Therefore, it might cause unexprected result. Please see [WordPress Codex](https://codex.wordpress.org/Revisions#Revision_Options) for more information.
# MB Settings Page
import Helpers from '../_parts/_helpers.md';
import LiteYouTubeEmbed from 'react-lite-youtube-embed';
import 'react-lite-youtube-embed/dist/LiteYouTubeEmbed.css';
MB Settings Page helps you create settings pages for your website. You can use it to create a theme options page, or a settings page for your plugin, or a custom settings page for clients' websites.
The plugins provide several styles for settings pages where you can have tabs or meta boxes. We try to keep the styles similar to the default WordPress UI as much as possible.
Settings page with WordPress-native tabsSettings page with left tabs
Settings page with meta boxes
:::success
You can also combine styles, for example using tabs with meta boxes.
:::
## Creating settings pages
To create a settings page, go to **Meta Box » Settings Pages** and click **Add New**.
On the new screen, you'll see all details for the settings page.
:::info
The instruction above uses [MB Builder](/extensions/meta-box-builder/), an extension providing the UI to create fields, and is already bundled in [Meta Box Lite](https://metabox.io/lite/) and [Meta Box AIO](/extensions/meta-box-aio/). If you prefer to use code, please see below.
:::
### Settings
There are several settings for a settings page. All of them are self-explained. We also add some tooltips next to the setting title to give you more information if needed. Here is the list of the settings with the explanation:
Name | Description
---|---
Menu type | Whether to show the settings page as a top-level menu or a submenu of an existing menu. Depending on the menu type, several settings below will appear.
Show menu after | Select the position of the menu. Available only when menu type is Top-level menu.
Default first submenu title | If you create a top-level settings page with some sub-settings pages, you can set the default first submenu title here.
Icon type | What type of menu icon. Available only when menu type is Top-level menu. Supports Dashicons, Font Awesome, SVG, and custom URL.
Icon | The icon for the menu. Available only when the icon type is Dashicons or Font Awesome.
Icon SVG | The custom SVG icon for the menu. Available only when the icon type is SVG.
Icon URL | The URL for the custom icon. Available only when the icon type is Custom URL.
Parent menu | If you select menu type "Submenu", then you can select the parent menu for this sub-menu here.
Required capability | The required capability to access the settings page.
Custom CSS class | Custom CSS for the wrapper div in the settings page, so you can add your styling.
Style | How do you want to style the settings page? Supports "Boxes" which has same the style as normal WordPress meta boxes (like in the edit post screen with the classic editor) and "No boxes" which has the same style as WordPress settings pages.
Columns | The number of columns in the meta boxes. Can be 1 (the same as WordPress settings pages) or 2 (the same as the edit post screen).
Tabs | Array of tabs (key => label) for the settings page.
Tab style | Specify the tab style, which can be "Top" (WordPress-native style) or "Left".
Custom submit button | The custom text for submit button.
Custom message | The custom message is displayed when saving options.
Help content | The content displayed when clicking on the "Help" button on the top right (near the "Screen Options" button) and is organized in tabs. Each tab has its own title and content.
Customizer | Whether to show the settings page in the Customizer as a panel. See the "Creating Customizer settings" section for details.
Customizer only | Whether to show only as a Customizer panel, no admin settings page.
Network | Make the settings page network-wide (in a multisite environment).
Each settings page also has its own ID and option that specifies which option in the database to store data into. By default, the plugin set the option name the same as the ID. You can change it if you want on the **Settings Page** on the top of the settings page:
:::info ID vs. option name
ID is for internal use for Meta Box, like the settings page URL or reference in the field group definition. The option name is for storing and getting data from the database. They can be the same (works in most cases) or different.
:::
:::success
If you want to use make the data of the settings page compatible with Customizer settings for the current theme, e.g. using theme mods to store the data, then set the option name to `theme_mods_$themeslug`.
:::
You can create as many settings pages as you want. You can also create a top-level settings page and several sub-settings pages.
## Using code
If you're a developer and prefer using code to create settings pages, use the filter `mb_settings_pages`. This is a sample code to create a theme options page under the Appearance menu:
```php
add_filter( 'mb_settings_pages', function ( $settings_pages ) {
$settings_pages[] = [
'id' => 'theme-slug',
'option_name' => 'theme_slug',
'menu_title' => 'Theme Options',
'parent' => 'themes.php',
];
return $settings_pages;
} );
```
The `mb_settings_pages` filter takes an array of settings pages as the argument. The callback function must return an array of settings pages.
Each settings page is defined by an array of the following options, which is similar to the UI in the **MB Builder** extension above:
Name|Description
---|---
`id`|Settings page ID. Required.
`option_name`|Option name where settings data is saved to. Optional. Takes `id` if missed. If you want to use theme mods, then set this to `theme_mods_$themeslug`.
`class`|Custom CSS for the wrapper div.
`menu_title`|Menu title. Optional. Takes `page_title` if missed.
`page_title`|Page title. Optional. Takes `menu_title` if missed. Note: either `menu_title` or `page_title` (or both) must have value.
`capability`|Required capability to access the settings page. Optional. Default `edit_theme_options`.
`icon_url`|The icon for the menu. Supports [Dashicons](https://developer.wordpress.org/resource/dashicons/) (`dashicons-icon-name`), [FontAwesome free](https://fontawesome.com/search?o=r&m=free) (`fa fa-home`), SVG (`data:image/svg+xml;base64...`) and custom URL.
`position`|Menu position (number). See below for the list of default WordPress menu positions.
`parent`|The ID of the parent page, if you want the settings page to be a submenu. Optional. Can be a WordPress menu or custom settings page menu. See below for the list of WordPress page IDs.
`submenu_title`|Set this to the default submenu title (first submenu) if the settings page is a top-level menu. Optional.
`help_tabs`|The content is displayed when clicking on the Help button on the top right (near the Screen Options button). See below for details.
`style`|How do you want to style the settings page? Supports `boxes` which has same the style as normal WordPress meta boxes (like in the edit post screen) and `no-boxes` which has the same style as WordPress settings pages. In `no-boxes` style, each meta box is a section of the settings page.
`columns`| The number of columns in the meta boxes. Can be 1 (the same as WordPress settings pages) or 2 (the same as the edit post screen).
`tabs`|Array of tabs for the settings page. See the "Tabs" section for more details.
`tab_style`|Specify the tab style, which can be `default` (WordPress-native style) or `left` (tabs are put on the left of the settings page). See the "Tabs" section below for details.
`submit_button`|The custom text for submit button. Optional.
`message`|The custom message displayed when saving options. Optional.
`customizer`|Whether to show the settings page in the Customizer as a panel. `true` or `false` (default). Optional. See below for details.
`customizer_only`|Whether to show only as a Customizer panel, no admin settings page. `true` or `false` (default). Optional.
`network`|Make the settings page network-wide (in a multisite environment). `true` or `false` (default). Optional.
### WordPress menus
This is the list of default WordPress menus with their ID (used for the `parent` parameter) and position (used for the `position` parameter):
Menu|ID|Position
---|---|---
Dashboard|`index.php`|2
Posts|`edit.php`|5
Media|`upload.php`|10
Links|`link-manager.php`|15
Pages|`edit.php?post_type=page`|20
Comments|`edit-comments.php`|25
Appearance|`themes.php`|60
Plugins|`plugins.php`|65
Uses|`users.php`|70
Tools|`tools.php`|75
Settings|`options-general.php`|80
### Tabs
The list of tabs is defined in the `tabs` parameter. A tab can have or doesn't have an icon and can be set like this:
```php
'tabs' => [
'general' => 'General Settings', // No icon
'design' => [ // With icon
'label' => 'Design Customization',
'icon' => 'dashicons-admin-customizer',
],
],
```
The `icon` parameter can be a [Dashicons](https://developer.wordpress.org/resource/dashicons/) icon or the URL of your custom icon. You can also use another icon library like FontAwesome by specifying its class (e.g. `fa fa-home`), but in that case, you have to enqueue the font yourself.
This screenshot shows the left tab navigation with icons:
### Help tabs
WordPress has a nice feature that allows us to define instructions, and guidelines in the "Help" section of each admin screen. To see the help content, click the "Help" button on the top right, near the "Screen Options" button.
The content is organized into tabs and you can set it in the MB Builder's UI or with code.
If you use code, set the help tabs as follows:
```php
'help_tabs' => [
[
'title' => 'General',
'content' => '
This tab displays the general information about the theme.
',
],
[
'title' => 'Homepage',
'callback' => 'my_custom_function',
'priority' => 10,
],
],
```
Each tab has the following parameters:
Parameter|Description
---|---
`title`|The tab title.
`content`|The tab content.
`callback`|Custom callback to render the tab content. Optional.
`priority`|The priority of the tab, used for ordering. Optional. Default 10.
## Settings fields
After creating a settings page, you need to create settings fields for it. Creating settings fields for settings pages is [similar as for posts](/custom-fields/#how-to-create-custom-fields). You can do it [with UI using MB Builder](/extensions/meta-box-builder/#creating-custom-fields) or [with code](/creating-fields-with-code/).
If you use MB Builder to create fields, make sure to select the correct settings page in the Location settings:
If you use code, then you need to hook to `rwmb_meta_boxes` and set a param `settings_pages` to the settings page(s) you want to add to, like this:
```php
add_filter( 'rwmb_meta_boxes', function ( $meta_boxes ) {
$meta_boxes[] = [
'id' => 'general',
'title' => 'General',
'context' => 'normal',
// highlight-start
'settings_pages' => 'theme-slug',
'tab' => 'general',
// highlight-end
'fields' => [
[
'name' => 'Logo',
'id' => 'logo',
'type' => 'file_input',
],
],
];
return $meta_boxes;
} );
```
:::warning
When using tabs, you must define the `tab` parameter for all meta boxes to make them appear in corresponding tabs. Missing the `tab` parameter makes the meta boxes hidden.
:::
Note:
- If you want to add the meta box to 2 or more settings pages, set it to an array of settings pages' IDs.
- If you set the settings page to have 2 columns, then the value for `context` accepts `normal` for the main content area and `side` for the right sidebar.
## Customizer
**MB Settings Pages** allows you to create settings panels & sections for the Customizer. Using Customizer gives users a better experience because they can preview the settings in real time.
### Panels & sections
When creating Customizer settings, it's important to understand that:
- A settings page is mapped to a Customizer panel
- Each meta box in the settings page is mapped to a Customizer section
To bring a settings page to the Customizer, turn on the **Customizer** settings when you create the settings page as follows:
Then go to the **Appearance » Customize** and you'll see the settings page is available as follows:
A new panel in the Customizer
Meta boxes become Customize sections
By default, the settings page is available in the both Customizer as well as in the admin area. If you don't want it in the admin area, choose the **Customizer only**.
If you use code, use the following code:
```php
add_filter( 'mb_settings_pages', function ( $settings_pages ) {
$settings_pages[] = [
'id' => 'rubik',
'option_name' => 'theme_mods_justread',
'menu_title' => 'Theme Options',
'parent' => 'themes.php',
// highlight-start
'customizer' => true,
'customizer_only' => true,
// highlight-end
];
return $settings_pages;
} );
```
This is a quick video that demonstrates how to use MB Settings Page to create custom panels, sections, and fields in the Customizer with code:
### Top-level sections
Sometimes you don't want the top-level panel that creates too much hierarchy (panel → sections → fields). You just want top-level sections (sections → fields). That will help users to navigate to your settings in the Customizer faster and easier.
:::warning
This can be done with code only.
:::
In that case, you need to do 2 steps:
**Step 1:** Remove the code that registers settings pages as you don't need settings pages anymore. If you use MB Builder, delete the settings page entry.
**Step 2:** In each meta box, replace the parameter `'settings_pages' => 'rubik'` with `'panel' => ''`, like this:
```php
add_filter( 'rwmb_meta_boxes', function ( $meta_boxes ) {
$meta_boxes[] = [
'id' => 'general',
'title' => 'General',
// highlight-next-line
'panel' => '',
'fields' => [
[
'name' => 'Logo',
'id' => 'logo',
'type' => 'file_input',
],
],
];
return $meta_boxes;
} );
```
And you'll see the section on the Customizer like this:
What if you want the _section to be inside another panel_? Like inside another plugin's panel? Set the `panel` parameter to ID of the target panel: `'panel' => 'panel_id'`.
### Compatibility
At the moment, all Meta Box fields are supported in the Customizer, except [file](/fields/file/) and [image](/fields/image/) field types. These field types will be converted to the [file_advanced](/fields/file-advanced/) and [image_advanced](/fields/image-advanced/) automatically to avoid any problems. Other upload field types such as [file_advanced](/fields/file-advanced/), [file_upload](/fields/file-upload/), [image_advanced](/fields/image-advanced/), [image_upload](/fields/image-upload/), [single_image](/fields/single-image/) still work well.
The good news is all the extensions such as [MB Conditional Logic](/extensions/meta-box-conditional-logic/), [MB Tabs](/extensions/meta-box-tabs/) are supported. That will help you create much better experiences for your users.
:::warning postMessage transport
The `postMessage` transport for the Customizer is not supported yet, which means changes are updated by refreshing the whole page instead of updating only the needed part of the page.
:::
## Network settings pages
A network settings page is a settings page that provides settings for all the websites in the network (multisite environment). For example, you might want to enter a Google Maps API key for all the websites or set the contact phone number for all of them.
Using _MB Settings Page_, you’re now able to do that easily. If you use MB Builder to create the settings page, simply switch on the **Network** option.
If you use code, add `'network' => true` to the settings pages args, like this:
```php
add_filter( 'mb_settings_pages', function ( $settings_pages ) {
$settings_pages[] = [
'id' => 'custom-options',
'option_name' => 'custom_options',
'menu_title' => 'Custom Options',
'icon_url' => 'dashicons-welcome-widgets-menus',
// highlight-next-line
'network' => true,
];
return $settings_pages;
} );
```
Don't forget to _network activate_ Meta Box and MB Settings Pages. And now, when you go to the network admin area, you'll see a settings page like the screenshot above.
## Backup & restore settings
Backup is a **special field type** added by the plugin that allows you to back up and restore the settings.
If you use MB Builder to create fields, please add a normal textarea field, go to tab Advanced of the field settings, and add a custom settings with the key "type" and value "backup" as follows:
If you use code, you need to create a special field with `'type' => 'backup'`, like this:
```php
$meta_boxes[] = [
'id' => 'colors',
'title' => 'Colors',
'settings_pages' => 'theme-slug',
'fields' => [
[
'name' => 'Text Color',
'id' => 'text-color',
'type' => 'color',
],
[
'name' => 'Backup',
// highlight-next-line
'type' => 'backup',
],
],
];
```
It will show a textarea field in your settings page like this:
When you add it to your settings page, it will show all of your settings in JSON. And you can just copy it and save it to a file to back up the settings. To restore the settings, just paste the JSON again and click the Save Settings button.
The backup field inherits from [`textarea`](/fields/textarea/) so you can customize it the way you want: change the field name, description, input size, etc. This field doesn't require an `ID`. And of course, you should have only one backup field on your settings page.
:::warning
The backup field only works if it is a top field. It does not work if it is a subfield in a group.
:::
## Hooks
**`mb_settings_page_load` action**
This action fires when a settings page is loaded. It's used internally to:
- Register meta boxes and custom fields in the settings page, and
- Save the submitted data.
These actions use the default priority `10`. So you can hook to this action to do something *after* the data is saved with a higher priority (like `20`):
```php
add_action( 'mb_settings_page_load', function ( $args ) {
if ( $args['id'] === 'YOUR SETTINGS PAGE ID' ) {
// Do something
}
}, 20 );
```
**`mb_settings_page_after_title` action**
This action fires after outputting the page title. You can use it to output anything like instructions to users.
**`mb_settings_page_submit_buttons` action**
This action fires after the submit button is rendered, which allows you to add more custom buttons next to the submit button.
## Data
By using Settings API, all the fields' values will be saved as an array in a single option in the WordPress options table with the option name is `option_name` in the settings page configuration. Each field is an element of the array with the corresponding key (field ID). It's the recommended way by WordPress that doesn't make your options table bloat.
## Getting field value
You're able to use helper function [rwmb_meta()](/functions/rwmb-meta/) to get field value as follows:
```php
$value = rwmb_meta( $field_id, ['object_type' => 'setting'], $option_name );
echo $value;
```
For network settings, please use the following code:
```php
$value = rwmb_meta( $field_id, ['object_type' => 'network_setting'], $option_name );
echo $value;
```
Notes:
- In the 2nd parameter, you need to pass `'object_type' => 'setting'` or `'object_type' => 'network_setting'`
- In the last parameter, you need to pass the option name for the settings page
Other parameters are the same as for posts. Please see [this documentation](/displaying-fields-with-code/) for details.
:::warning
It requires the extension version 1.2+ to use the helper function. If you're using an older version, please [update now](/updates/).
:::
# MB Show Hide
MB Show Hide helps you to toggle the visibility of a meta box based on some conditions such as categories, page template or post format.
MB Show Hide is a simplified version of [MB Conditional Logic](/extensions/meta-box-conditional-logic/). MB Conditional Logic can control the visibility of custom fields and other HTML elements and supports more types of conditions.
## Settings
To add show, hide conditions to your meta box, you need to add parameter `show` or `hide` accordingly to the meta box configuration.
Each parameter (`show`, `hide`) is an array and has the same following elements:
- `relation`: The logical operator to combine conditions: `AND` or `OR`. The default value is `OR`. Case insensitive. Optional.
If one of the following conditions matched (`relation` = `OR`) or all of the following conditions matched (`relation` = `AND`), then the meta box is shown or hid.
Parameter|Description
--|--
`template`|List of page templates, match if the current page has a page template in the list. Array. Case insensitive. Optional.
`post_format`|List of post formats, match if the current post has a format in the list. Array. Case insensitive. Optional.
`category`|List of categories IDs or names (NO slugs), match if the current post has a category in the list. Array. Case sensitive. Optional.
`taxonomy_slug`|List of custom taxonomy terms' IDs or names (NO slugs). Here `taxonomy_slug` is the slug of the taxonomy (like `section`, `region`, etc.). Match if the current post has a term in the list. Array. Case sensitive. Optional.
`is_child`|Boolean. Match if the current page is a child page or not. Optional.
`input_value`| Array of pairs of CSS selectors and values. Match if the inputs (with specified CSS selector) has the defined value. Note: the `relation` is also applied to rules here. Added in version 0.2.
Since version 4.7, WordPress has added support for [post type templates](https://make.wordpress.org/core/2016/11/03/post-type-templates-in-4-7/). To make it work with `template` rule in Show Hide, you need to update to version 1.2.0+ and set the syntax to:
```php
'template' => array( 'post:my-template.php', 'my_post_type:template-one.php' ),
```
e.g, the value should be in form of `post_type:template-file.php`. If the `post_type:` is missing, then the plugin automatically understands that the template is used for pages only.
## Sample code
```php
add_filter( 'rwmb_meta_boxes', 'prefix_show_hide_demo_register' );
function prefix_show_hide_demo_register( $meta_boxes ) {
$meta_boxes[] = array(
'title' => 'MB Show Hide Demo: Show',
// Show this meta box for posts matched below conditions
'show' => array(
// With all conditions below, use this logical operator to combine them. Default is 'OR'. Case insensitive. Optional.
'relation' => 'OR',
// List of page templates (used for page only). Array. Optional.
'template' => array( 'tpl/blog.php', 'tpl/homepage.php' ),
// List of post formats. Array. Case insensitive. Optional.
'post_format' => array( 'Standard', 'Gallery' ),
// List of categories IDs or names (NOT slugs). Array. Case sensitive. Optional.
'category' => array( 3, 'Unpublished', 'Template' ),
// Custom taxonomy. Optional.
// Format: 'taxonomy' => list of term IDs or names (NOT slugs). Array. Case sensitive. Optional.
'location' => array( 12, 'USA', 'europe' ),
'os' => array( 'Windows', 'mac-os' ),
// Check if page is a child page
'is_child' => true,
// Check the value of selector. Format: array( selector, value )
// Added in version 0.2
'input_value' => array(
'#hide-demo-mb' => 'yes',
'#hide-demo-mb-2' => 'yes',
'input[name=hide-demo-mb-3]' => true, // If it's a checkbox then true == checked
),
),
'fields' => array(
array(
'name' => 'Name',
'id' => 'name',
'type' => 'text',
),
),
);
// 2nd meta box
$meta_boxes[] = array(
'title' => 'MB Show Hide Demo: Hide',
// Hide this meta box for posts matched below conditions
'hide' => array(
// With all conditions below, use this logical operator to combine them. Default is 'OR'. Optional.
'relation' => 'OR',
// List of page templates. Can be array or comma separated. Optional.
'template' => array( 'full-width.php', 'left-sidebar.php' ),
// List of categories IDs or names or slugs. Can be array or comma separated. Optional.
'category' => array( 1, 'News' ),
// Custom taxonomy. Optional.
// Format: 'taxonomy' => list of terms (can be array or comma separated of IDs or names or slugs)
'location' => array( 12, 'USA', 'europe' ),
'os' => array( 'Windows', 'mac-os' ),
// Check if page is a child page
'is_child' => true,
// Check the value of selector. Format: array( selector, value )
// Added in version 0.2
'input_value' => array(
'#hide-demo-mb' => 'yes',
'#hide-demo-mb-2' => 'yes',
'input[name=hide-demo-mb-3]' => true, // If it's a checkbox then true == checked
),
),
'fields' => array(
array(
'name' => 'Job',
'id' => 'job',
'type' => 'text',
),
),
);
return $meta_boxes;
}
```
# MB Tabs
MB Tabs helps you to put custom fields into tabs for a better view. Tabs can have icons and can be put on the left side of the meta box.
:::info Tabs in settings pages
Tabs in the settings pages are created separately with different settings by the [MB Settings Page](/extensions/mb-settings-page) extension. This extension is for grouping fields inside a field group only.
:::
## Creating tabs
First, you need to create custom fields as usual. Go to **Meta Box » Custom Fields** and [create a field group](/custom-fields/#how-to-create-custom-fields) with the custom fields you need.
Then adding tabs to the field group. **Tab is a special field type** and is available in the field list.
:::info
The instruction above uses [MB Builder](/extensions/meta-box-builder/), an extension providing the UI to create fields, and is already bundled in [Meta Box Lite](https://metabox.io/lite/) and [Meta Box AIO](/extensions/meta-box-aio/). If you prefer to use code, please see below.
:::
To add a tab, click the **+ Add Field** button and search for **Tab**:
After adding tabs, you need to **reorder** tabs among the fields. **The fields that follow a tab will belong to this tab**.
## Tab settings
Each tab has its own settings like label or icon. To see and change the tab settings, click the field on the preview, in the left panel, you can see:
Below is the meaning of each setting:
Name|Description
---|---
Label|The tab label
ID|The tab ID, which is used internally by the plugin
Type|The field type, must be "Tab"
Icon type|The icon type, you can choose between Dashicons (default), Font Awesome, or custom URL. Optional.
If you choose the tab icon type Dashicons, you'll see a list of icons to pick from (as in the screenshot above).
If you want to use a FontAwesome icon for the tab, then select Icon type "Font Awesome" and enter the [icon CSS class](https://fontawesome.com/icons?d=gallery&m=free) in the next input.
If you have a custom image for the tab icon, then select Icon type "Custom URL" and enter the icon URL in the next input.
## Tab style
The plugin provides 3 styles for tabs: "default", "box", and "left" as you can see below:
To change a tab style, click on the Settings icon to have the field group settings, and choose one style in the **Tab style**:
You can also set the default active tab here by entering the tab ID in the **Default active tab ID**.
Now you have your tabs ready. Please edit a post to see them in action!
## Using code
If you're a developer and prefer using code to create tabs, this is a sample code to create simple tabs:
```php
add_filter( 'rwmb_meta_boxes', function ( $meta_boxes ) {
$meta_boxes[] = [
'title' => 'MB Tabs Demo',
// highlight-start
'tabs' => [
'contact' => 'Contact',
'social' => 'Social Media',
],
// highlight-end
'fields' => [
[
'name' => 'Name',
// highlight-next-line
'tab' => 'contact',
],
[
'name' => 'Email',
// highlight-next-line
'tab' => 'contact',
],
[
'name' => 'Facebook',
// highlight-next-line
'tab' => 'social',
],
[
'name' => 'Twitter',
// highlight-next-line
'tab' => 'social',
],
],
];
return $meta_boxes;
} );
```
To create tabs for your meta box, you need to add these parameters to your meta box settings:
Parameter|Description
---|---
`tabs`|Array of tabs. See below for details.
`tab_style`|The tab style: `default` (like tabs for Categories), `box` (like tabs for Visual and Text modes of the main editor) or `left` (like tabs in the Help screen)
`tab_default_active`|Default active tab ID.
`tab_remember`|Remember the last active tab when saving the post. Boolean. Default is `false`.
The list of tabs is defined in the `tabs` parameter. A tab can have or doesn't have an icon and can be set like this:
```php
'tabs' => [
'contact' => 'Contact', // No icon
'social' => [ // With icon
'label' => 'Social Media',
'icon' => 'dashicons-share',
]
],
```
The plugin supports the following icon type for tabs:
- [Dashicons](https://developer.wordpress.org/resource/dashicons/): set `icon` to the class name of Dashicons, e.g. `dashicons-email`.
- Icon font: set `icon` to the icon class name. For example, if you want to use Font Awesome, set `'icon' => 'fa fa-home'`. Note that you have to enqueue the CSS for your custom font icon yourself. The plugin only supports Dashicons by default.
- Custom URL: set `icon` to the URL of the image
Then for each field in the meta box, you need to **specify which tab it belongs to** by adding a parameter `'tab' => 'tab-id'` where `tab-id` is one of the tab IDs you have registered above.
# 0066-extensions-22-meta-box-template
---
title: 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. .
```yml
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:
```php
[
'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:
```yml
- Item 1
- Item 2
- Item 3
```
You can also use short syntax like this:
```yml
[Item 1, Item 2, Item 3]
```
Both are equivalent to the following PHP code:
```yml
[ '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:
```yml
key1: value1
key2: value2
key3: value3
```
alternatively:
```yml
{key1: value1, key2: value2, key3: value3}
```
which is equivalent to this PHP code:
```yml
[
'key1' => 'value1',
'key2' => 'value2',
'key3' => 'value3'
]
```
### Nested arrays
Nested arrays (sequences or mappings) can be defined with 1 or more spaces:
```yml
fields:
- name: Name
id: name
type: text
- name: Image
id: image
type: image_advanced
```
which is equivalent to:
```php
[
'fields' => [
[
'name' => 'Name',
'id' => 'name',
'type' => 'text',
],
[
'name' => 'Image',
'id' => 'image',
'type' => 'image_advanced',
],
],
]
```
:::tip
- 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](https://symfony.com/doc/current/components/yaml/yaml_format.html) to follow. If you want the full reference, you can read it at [YAML homepage](https://www.yaml.org/spec/1.2/spec.html).
## 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.
:::warning
Please refer to [field group settings](/creating-fields-with-code/) and [field settings](/field-settings/) when defining keys.
:::
**If you register single meta box**, then enter field group settings and its fields like this:
```yml
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:
```yml
# 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()`](https://codex.wordpress.org/Function_Reference/get_theme_root) function, without trailing slash
`%template%`|Path to current theme directory. Same as [`get_template_directory()`](https://codex.wordpress.org/Function_Reference/get_template_directory) function, without trailing slash
`%stylesheet%`|Path to current child theme directory. Same as [`get_stylesheet_directory()`](https://codex.wordpress.org/Function_Reference/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/
```
:::tip
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:
```php
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;
} );
```
# MB Term Meta
import Helpers from '../_parts/_helpers.md';
import FAQ from '@site/src/components/FAQ';
MB Term Meta helps you to add custom fields to taxonomies.
## Settings
Creating custom meta boxes for taxonomies is similar to posts. The only difference is you need to specify `taxonomies` settings which the meta box will be added to:
```php
add_filter( 'rwmb_meta_boxes', function ( $meta_boxes ) {
$meta_boxes[] = [
'title' => 'Standard Fields',
// highlight-next-line
'taxonomies' => 'category', // List of taxonomies. Array or comma-separated string.
'fields' => [
[
'name' => 'Featured?',
'id' => 'featured',
'type' => 'checkbox',
],
[
'name' => 'Featured Content',
'id' => 'featured_content',
'type' => 'wysiwyg',
],
[
'name' => 'Featured Image',
'id' => 'image_advanced',
'type' => 'image_advanced',
],
[
'name' => 'Color',
'id' => 'color',
'type' => 'color',
],
],
];
return $meta_boxes;
} );
```
## Data
WordPress provides an identical way to store values in the meta tables for post / term / user. This extension utilizes that API and stores field value in the term meta exactly like post meta.
## Getting field value
You're able to use helper function [rwmb_meta()](/functions/rwmb-meta/) to get field value for terms.
```php
$term_id = get_queried_object_id();
$value = rwmb_meta( $field_id, ['object_type' => 'term'], $term_id );
echo $value;
```
:::info
- In the 2nd parameter, you need to pass `'object_type' => 'term'`, and
- The last parameter is the term ID. To get the ID of the the current category/term page, please use the function `get_queried_object_id()`.
:::
Other parameters are the same as for post. Please see [this documentation](/displaying-fields-with-code/) for details.
:::warning
It requires the extension version 1.1+ to use the helper function. If you're using an older version, please [update now](/updates/).
:::
## FAQ
Please use this code to output term meta in a view
`{% set custom_field = mb.rwmb_meta( 'field_id', { object_type: 'term' }, term_id ) %}
{{ custom_field }}`
# MB Testimonials
## Overview
MB Testimonials is a WordPress plugin that helps you add testimonials to your website easily. It has **7 beautiful pre-made** templates that you can customize with HTML / CSS. In addition, you can display the testimonials in two styles: grid and slider.
**Note**: MB Testimonials plugin is only available for the [Lifetime Bundle](https://metabox.io/pricing/).
## Installation
First, you need to install and activate Meta Box from [wordpress.org](https://wordpress.org/plugins/meta-box/). Next, download MB Favorite Posts plugin from the [My Account](https://metabox.io/my-account/) page, then upload the .zip file from the **Admin Dashboard**.
**Note**: MB Testimonials and [other solutions](https://metabox.io/product-category/solutions/) are not included in Meta Box AIO, so you can install them independently without Meta Box AIO.
## Add Testimonials
Go to **Testimonials** > **Add New**:
Next, fill in the name and the information for the testimonial:
Click **Add more** to add other testimonials or click **Remove** to delete them:
In addition, you can drag and drop to arrange testimonials easily:
## Configure the Testimonials
In the **Settings** section, choose a built-in template in the **Display** tab:
Right below the templates, go to the **Click here** section to show the code of the chosen template. You can customize the template by editing the code with HTML. Also, you can delete the code and create a new template.
In the **Styling** tab, set up the parameters of the testimonials as you want:
Finally, don’t forget to click **Publish**.
## Display Testimonials on the Front End
After publishing, the plugin will generate a shortcode for the Testimonials post that we’ve created.
Copy and paste this shortcode to pages, posts, widgets, ... where you want to display the testimonials.
The testimonials will display on the front end as follows:
# MB Text Limiter
MB Text Limiter helps you to limit the number of characters or words entered for text and textarea fields.
## Settings
Assume you have a text field with the following settings:
```php
[
'title' => 'My Text Field',
'id' => 't',
'type' => 'text',
],
```
And you want to limit the number of characters for that field to 40. Doing that by adding `'limit' => 40` to the field:
```php
[
'title' => 'My Text Field',
'id' => 't',
'type' => 'text',
'limit' => 40,
],
```
If you need to limit by words, just add `'limit_type' => 'word'`:
```php
[
'title' => 'My Text Field',
'id' => 't',
'type' => 'text',
'limit' => 40,
'limit_type' => 'word',
],
```
That's all!
Note that this extension works only with [text](/fields/text/) and [textarea](/fields/textarea/) fields.
# MB Toolset Migration
import LiteYouTubeEmbed from 'react-lite-youtube-embed';
import 'react-lite-youtube-embed/dist/LiteYouTubeEmbed.css';
MB Toolset Migration extension helps you to migrate field groups, custom field data, and relationships from Toolset to Meta Box.
:::warning
This extension only migrates the data created by Toolset within a site. It doesn't migrate your website from local to the development environment (you'll need another plugin for this) nor the way you use the data like getting the data and displaying it on the front end. After the migration, just go to the database and check how it changes.
:::
## Backup the database
Before migrating data, make sure you have a backup of your database. During the migration process, because of the difference in [data format](/database/), the plugin will attempt to modify the existing data in custom fields created by Toolset. We try to do it at a very minimum level and create a backup of fields for some specific cases, but it's still important to make a backup just in case something goes wrong.
## Migrate
Before migrating, make sure you keep Toolset, Meta Box (required) and extensions (optional) activated. To know which extensions you might need, please see the **How it works** section below. Normally, if you use Meta Box AIO and keep all extensions activated, you don't have to worry about this.
To migrate, go to **Meta Box > Toolset Migration** and click the **Migrate** button.
The plugin will show the process of migrating. When it's done, you'll see the text "Done".
## How it works
MB Toolset Migration tries to migrate all the following data from Toolset to Meta Box. Please note that not all data types and settings in Toolset have an equivalent in Meta Box. The plugin will try to migrate as much as it can. The details are explained below:
### Post types and taxonomies
The plugin will migrate all custom post types and custom taxonomies created in Toolset to Meta Box. This job requires the [MB Custom Post Type](/extensions/mb-custom-post-type/) extension. All the settings like labels and icons are migrated as well.
:::warning
**We do not remove Toolset post types and taxonomies** after migration, for safety. Instead, we changed their status to 'Inactive'. You can remove them later after all the data is processed.
:::
### Field groups
Toolset field groups are migrated to Meta Box's field groups, which requires [MB Builder](/extensions/meta-box-builder/). Most of the field group settings are the same as in Meta Box.
:::warning
**We do not remove Toolset field groups** after migration, for safety. Instead, we changed their status to 'Inactive'. You can remove them later after all the data is processed.
:::
For **field group locations**, the basic rules are already supported in Meta Box and extensions. You might need extensions such as:
- [MB Term Meta](/extensions/mb-term-meta/): If you set locations for taxonomies.
- [MB User Meta](/extensions/mb-user-meta/): If you set locations for users.
Besides, if you use complex locations, then you'll need [MB Include Exclude](/extensions/meta-box-include-exclude/) extension. Due to the difference in how plugins create rules, the plugin works the following way:
- If there's only one location group: the plugin will migrate all rules with operator `AND`.
- If there are multiple location groups: the plugin will take the first rule of each group and combine them with operator `OR`.
### Custom fields data
Most Toolset field types work well with Meta Box, such as text, radio, select, etc. However, there's still a difference in how plugins store values in the database. Because of that, we'll process the following:
1. **Convert meta keys** in the database. Toolset sets meta keys for fields with the format `wpcf-{$field_id}`. The plugin will change the meta key to just `$field_id` for simplicity.
2. For **media fields**, Toolset stores URLs in the database. We'll change them to IDs.
2. For **fields that have multiple values** such as checkbox list, Toolset saves their values as serialized arrays. We'll migrate them multiple rows in the database (similar to what `add_post_meta` does with the last parameter `false`).
3. For **repeatable groups**, Toolset saves values of each sub-fields in a row in the database (in a complicated way). We'll migrate them into groups (which requires [MB Group](/extensions/meta-box-group/)).
:::info Field backup
For these fields, as the data format is different, for safety, we create a backup for each field value. The new field value is stored with the key `_ts_bak_{$field_id}`.
:::
### Relationships
The plugin also migrates all relationships from Toolset to Meta Box. You'll need the [MB Builder](/extensions/meta-box-builder/) and [MB Relationships](/extensions/mb-relationships/) to do this. As the settings are quite different between the plugins, we'll migrate the settings of all Toolset relationships to many-to-many relationships in Meta Box.
Of course, the data of relationships (the connections between items) are also migrated.
:::warning Database tables
For safety, we don't remove Toolset relationships tables (3) after the migration.
:::
# MB Tooltip
MB Tooltip helps you to add help information via tooltips.
## Settings
To add a tooltip to a meta field, add `tooltip` parameter for that field. You can define tooltip in one of following formats:
- `'tooltip' => 'Tooltip content',`
- `'tooltip' => array( 'icon' => 'info', 'position' => 'top', 'content' => 'Tooltip content', 'allow_html' => true )`
e.g. if the `tooltip` is a string, the plugin will use icon info and take the string as the tooltip content. If the `tooltip` is an array, then it accepts the following parameters:
Parameter|Description
---|---
`icon`|The tooltip icon. It can be `info` (default), `help` or *URL to custom icon image*. Since version 0.1.1, you can *use any Dashicons* for the icon by specifying its name, for example `dashicons-email`. For full list of Dashicons, please read [this page](https://developer.wordpress.org/resource/dashicons/).
`position`|The tooltip position. Can be `top` (default), `bottom`, `left` or `right`. Optional.
`content`|Tooltip content.
`allow_html`|Whether to render HTML in the tooltip content: `true` (default) or `false`.
## Sample code
This code below adds tooltip to 3 fields:
```php
add_filter( 'rwmb_meta_boxes', 'meta_box_tooltip_demo_register' );
function meta_box_tooltip_demo_register( $meta_boxes ) {
$meta_boxes[] = array(
'title' => 'MB Tooltip Demo',
'fields' => array(
array(
'name' => 'Default',
'id' => 'name',
'type' => 'text',
// Add tooltip to field label, in one of following formats
// 1) 'tooltip' => 'Tooltip Content'
// 2) 'tooltip' => array( 'icon' => 'info', 'content' => 'Tooltip Content', 'position' => 'top' )
// 3) 'tooltip' => array( 'icon' => 'https://url-to-icon-image.png', 'content' => 'Tooltip Content', 'position' => 'top' )
//
// In 1st format, icon will be 'info' by default
// In 2nd format, icon can be 'info' (default), 'help' or any Dashicons (see https://developer.wordpress.org/resource/dashicons/)
// In 3rd format, icon can be URL to custom icon image
//
// 'position' is optional. Value can be 'top' (default), 'bottom', 'left', 'right'
'tooltip' => 'Info icon, top position',
),
array(
'name' => 'Help icon',
'id' => 'job',
'type' => 'text',
'tooltip' => array(
'icon' => 'help',
'content' => 'Right position',
'position' => 'right',
),
),
array(
'name' => 'Dashicon',
'id' => 'email',
'type' => 'text',
'tooltip' => array(
'icon' => 'dashicons-email',
'content' => 'Dashicon',
'position' => 'right',
),
),
array(
'name' => 'Custom image',
'id' => 'email',
'type' => 'text',
'tooltip' => array(
'icon' => 'https://imgur.elightup.com/ZQI2DNx.png',
'content' => 'Custom icon',
'position' => 'right',
),
),
),
);
return $meta_boxes;
}
```
## Adding tooltip for inputs
The default behavior adds tootips for field labels. Since version 1.1, the plugin supports adding tooltips for field inputs. Because of variation in the UI, the plugin supports only these fields: date time fields, text input fields (`text`, `url`, `email`, `number`, `password`) and select fields.
The option for this feature is `tooltip_input`, which accepts the same parameters as for `tooltip`.
# MB User Meta
import Helpers from '../_parts/_helpers.md';
MB User Meta helps you to add custom fields to user profile.
The extension works only on the back end. If you want to edit user profile on the front end, please see [MB User Profile](/extensions/mb-user-profile/).
## Adding fields to user profile
Registering custom fields for users is similar to posts. The only difference here is you need to specify a parameter `'type' => 'user'`:
```php
add_action( 'rwmb_meta_boxes', function( $meta_boxes ) {
$meta_boxes[] = array(
'title' => 'Contact Info',
'type' => 'user', // THIS: Specifically for user
'fields' => array(
array(
'name' => 'Mobile phone',
'id' => 'mobile',
'type' => 'tel',
),
array(
'name' => 'Work phone',
'id' => 'work',
'type' => 'tel',
),
array(
'name' => 'Address',
'id' => 'address',
'type' => 'textarea',
),
array(
'name' => 'City',
'id' => 'city',
'type' => 'select_advanced',
'options' => array(
'hanoi' => 'Hanoi',
'hcm' => 'Ho Chi Minh City'
),
),
),
);
$meta_boxes[] = array(
'title' => 'Custom avatar',
'type' => 'user', // THIS: Specifically for user
'fields' => array(
array(
'name' => 'Upload avatar',
'id' => 'avatar',
'type' => 'image_advanced',
'max_file_uploads' => 1,
),
),
);
return $meta_boxes;
} );
```
Result:
## Data
WordPress provides an identical way to store values in the meta tables for post / term / user. This extension utilizes that API and stores field value in the user meta exactly like post meta.
## Getting field value
You're able to use helper function [rwmb_meta()](/functions/rwmb-meta/) to get field value:
```php
$value = rwmb_meta( $field_id, ['object_type' => 'user'], $user_id );
echo $value;
```
The code is very similar to getting post meta. The differences are:
- In the 2nd parameter, you need to pass `'object_type' => 'user'`, and
- In the last parameter, you need to pass the user ID
Other parameters are the same as for posts. Please see [this documentation](/displaying-fields-with-code/) for details.
:::warning
It requires the extension version 1.1+ to use the helper function. If you're using an older version, please [update now](/updates/).
:::
# MB User Profile
MB User Profile helps you to add information to the user profile and edit these details on the front end. It also includes a register form, login form, and edit profile form that you can embed anywhere using shortcodes.
Note: this extension already includes **MB User Meta**.
## Registration form
To insert a registration form to a page, select the **Registration Form** block from the block inserter. And you'll see the form preview like this:
Clicking on the block will reveal the form settings on the right. All settings are self-explained and have their description.
You can also use the registration shortcode to display the registration form:
```php
[mb_user_profile_register]
```
Below is the list of the settings. The attribute is used for the shortcode.
Name|Attribute|Description
---|---|---
ID|`id`|Field group ID(s) [created for users](/extensions/mb-user-meta/), separated by commas. Optional. Leave blank to show the default registration form.
Redirect URL|`redirect`|Redirect URL, to which users will be redirected after a successful registration.
Form ID|`form_id`|ID (HTML attribute) of the form.
Title|`label_title`|Label for the title of the form. Default empty.
Username field label|`label_username`|Label for the username input field.
Email field label|`label_email`|Label for the email input field.
Password field label|`label_password`|Label for the password input field.
Confirm password field label|`label_password2`|Label for the confirm password input field.
Submit button text|`label_submit`|Label for the submit button.
Username field ID|`id_username`|ID (HTML attribute) of the username input field.
Email field ID|`id_email`|ID (HTML attribute) of the email input field.
Password field ID|`id_password`|ID (HTML attribute) of the password input field.
Confirm password field ID|`id_password2`|ID (HTML attribute) of the confirm password input field.
Submit button ID|`id_submit`|ID (HTML attribute) of the submit button.
Confirmation text|`confirmation`|Confirmation message if registration is successful.
Send confirmation email|`email_confirmation`|Send a confirmation email when registering (you need to set up an email SMTP to make this function work properly). If this param is `true`, the system will also check the confirmation status when the user login. All previous users are set and confirmed.
Password strength|`password_strength`|Set the required password strength. Available options: `strong`, `medium`, `weak`, `very-weak`, or `false` to disable password strength meter.
Use email for username|`email_as_username`|Use email for username. If this param is `true`, then the username field will disappear.
Always show|`show_if_user_can`|Always show the form if the current user has the proper capability. Should be a [WordPress capability](https://wordpress.org/support/article/roles-and-capabilities/). Useful if admins want to register for other people.
Role for the new user|`role`|Role for the new user. If `append_role` is set to `true`, then the new role is appended, so users will have 2 roles: the default roles set by WordPress and this role. Default empty.
Append role|`append_role`|Whether to append the role to users instead of setting only one role for users.
reCaptcha key|`recaptcha_key`|Google reCaptcha site key (version 3). Optional.
reCaptcha secret|`recaptcha_secret`|Google reCaptcha secret key (version 3). Optional.
## Login form
To insert a login form to a page, select the **Login Form** block from the block inserter. And you'll see the form preview like this:
Clicking on the block will reveal the form settings on the right. All settings are self-explained and have their description.
You can also use the login shortcode to display the login form:
```php
[mb_user_profile_login]
```
Below is the list of the settings. The attribute is used for the shortcode.
Name|Attribute|Description
---|---|---
Redirect URL|`redirect`|Redirect URL, to which users will be redirected after successful login.
Form ID|`form_id`|ID (HTML attribute) of the form.
Title|`label_title`|Label for the title of the form. Default empty.
Username field label|`label_username`|Label for the username input field.
Password field label|`label_password`|Label for the password input field.
Remember checkbox label|`label_remember`|Label for the remember checkbox field.
Lost password field label|`label_lost_password`|Label for the lost password link.
Submit button text|`label_submit`|Label for the submit button.
Username field ID|`id_username`|ID (HTML attribute) of the username input field.
Password field ID|`id_password`|ID (HTML attribute) of the password input field.
Remember checkbox ID|`id_remember`|ID (HTML attribute) of the remember checkbox field.
Submit button ID|`id_submit`|ID (HTML attribute) of the submit button.
Confirmation text|`confirmation`|Confirmation message if login is successful.
Default username value|`value_username`|Default value for the username field.
Default remember|`value_remember`|Default value for the remember checkbox field - `true` or `false` (default).
reCaptcha key|`recaptcha_key`|Google reCaptcha site key (version 3). Optional.
reCaptcha secret|`recaptcha_secret`|Google reCaptcha secret key (version 3). Optional.
## Edit profile form
To insert an edit profile form to a page, select the **Edit Profile Form** block from the block inserter. And you'll see the form preview like this:
Clicking on the block will reveal the form settings on the right. All settings are self-explained and have their description.
You can also use the edit profile shortcode to display the edit profile form:
```php
[mb_user_profile_info id="field-group-id"]
```
Below is the list of the settings. The attribute is used for the shortcode.
Name|Attribute|Description
---|---|---
ID|`id`|Field group ID(s) [created for users](/extensions/mb-user-meta/), separated by commas. All fields from field groups will be included in the profile form. Required.
User ID|`user_id`|User ID, whose info will be edited. If not specified, the current user ID is used.
Redirect URL|`redirect`|Redirect URL, to which users will be redirected after successful submission.
Form ID|`form_id`|ID (HTML attribute) of the form.
Title|`label_title`|Label for the title of the form. Default empty.
Password field label|`label_password`|Label for the password input field.
Confirm password field label|`label_password2`|Label for the confirm password input field.
Submit button text|`label_submit`|Label for the submit button.
Password field ID|`id_password`|ID (HTML attribute) of the password input field.
Confirm password field ID|`id_password2`|ID (HTML attribute) of the confirm password input field.
Submit button ID|`id_submit`|ID (HTML attribute) of the submit button.
Confirmation text|`confirmation`|Confirmation message if the form submission is successful.
Password strength|`password_strength`|Set the required password strength. Available options: `strong`, `medium`, `weak`, `very-weak`, or `false` to disable password strength meter.
reCaptcha key|`recaptcha_key`|Google reCaptcha site key (version 3). Optional.
reCaptcha secret|`recaptcha_secret`|Google reCaptcha secret key (version 3). Optional.
### Default fields
By default, the user profile form doesn't include any default user fields, such as first name, last name, or biography. To be able to edit these fields, please [create a field group for users](/extensions/mb-user-meta/) with those fields, keeping the same field IDs as WordPress's.
For example, the code below creates a meta box for editing the user's first name, last name, and biography:
```php
add_filter( 'rwmb_meta_boxes', function( $meta_boxes ) {
$meta_boxes[] = [
'title' => 'Default Fields',
'id' => 'default-fields',
'type' => 'user', // NOTICE THIS
'fields' => [
[
// highlight-next-line
'id' => 'first_name',
'name' => 'First Name',
'type' => 'text',
],
[
// highlight-next-line
'id' => 'last_name',
'name' => 'Last Name',
'type' => 'text',
],
[
// highlight-next-line
'id' => 'description',
'name' => 'Biography',
'type' => 'textarea',
],
],
];
return $meta_boxes;
} );
```
And use it in the user edit profile form with this shortcode:
```php
[mb_user_profile_info id="default-fields"]
```
To make the plugin recognize the user fields, you need to set the correct ID for them:
Field|ID
---|---
User email|`user_email`
User nicename|`user_nicename`
User URL|`user_url`
Display name|`display_name`
First name|`first_name`
Last name|`last_name`
Registration date|`user_registered`
Biography|`description`
Rich editing|`rich_editing`
Syntax highlighting|`syntax_highlighting`
Admin color|`admin_color`
Comment shortcuts|`comment_shortcuts`
Show the admin bar on the front|`admin_bar_front`
User role|`role`
:::warning
These default fields do not work as sub-fields in a group.
:::
### User password
To let users change their password, please use the field group ID `rwmb-user-info` in the shortcode below:
```php
[mb_user_profile_info id="rwmb-user-info"]
```
## Settings
MB User Profile has a settings page under **Meta Box > User Profile** that allows you to change some settings for the plugin.
- **Force password change**: force users to change their password after the first login.
- **Email confirmation success page**: select a page to show when users successfully confirm their email. If no page is selected, a default message will be displayed.
- **Email confirmation error page**: select a page to show when there are errors when users confirming their email. If no page is selected, a default message will be displayed.
## Email templates
MB User Profile sends emails to users when:
- They reset their passwords
- They register and are requested to confirm by email
To overwrite the emails created by the plugin, please:
- Create a folder `mb-user-profile` in your theme (or your child theme)
- Copy the email templates from the MB User Profile's `templates` folder to the `mb-user-profile` folder that you've just created above
- Edit the new templates files
Now the emails sent by the plugin will use the templates in your theme.
## Hooks
### `rwmb_profile_redirect`
This filter allows you to change the URL of the redirect page after the form is submitted. It accepts 2 parameters: redirect URL and form config - the shortcode attributes.
```php
$redirect = apply_filters( 'rwmb_profile_redirect', $redirect, $config );
```
You can use this filter to change the redirect URL after a user updated his profile.
```php
add_filter( 'rwmb_profile_redirect', function( $redirect, $config ) {
if ( 'my-meta-box' === $config['id'] ) {
$redirect = 'https://domain.com/thank-you/';
}
return $redirect;
}, 10, 2 );
```
### `rwmb_profile_before_process`
This action fires before the form is processed. It accepts one parameter `$config` - the form configuration, taken from the shortcode attributes.
### `rwmb_profile_after_process`
This action fires after the form is processed, e.g. saved or updated. It accepts 2 parameters:
- `$config` - the form configuration, taken from the shortcode attributes.
- `$user_id` - the submitted user ID
You can use this action to do a custom redirect to your Thank you page or send an email notification.
```php
add_action( 'rwmb_profile_after_process', function( $config, $user_id ) {
if ( 'my-meta-box' === $config['id'] ) {
wp_mail( 'admin@domain.com', 'New submission', 'A new user has been just submitted.' );
wp_safe_redirect( 'thank-you' );
die;
}
}, 10, 2 );
```
### `rwmb_profile_before_form`
This action fires before form output. It accepts one parameter `$config` - the form configuration, taken from the shortcode attributes.
### `rwmb_profile_after_form`
This action fires after form output. It accepts one parameter `$config` - the form configuration, taken from the shortcode attributes.
### `rwmb_profile_before_display_confirmation`
This action fires before the confirmation message is displayed. It accepts one parameter `$config` - the form configuration, taken from the shortcode attributes.
### `rwmb_profile_after_display_confirmation`
This action fires after the confirmation message is displayed. It accepts one parameter `$config` - the form configuration, taken from the shortcode attributes.
### `rwmb_profile_before_submit_button`
This action fires before the submit button is displayed. It accepts one parameter `$config` - the form configuration, taken from the shortcode attributes.
`rwmb_profile_after_submit_button`
This action fires after the submit button is displayed. It accepts one parameter `$config` - the form configuration, taken from the shortcode attributes.
### `rwmb_profile_validate`
This filter is used to check if the form is validated. You can use this filter to add a custom check for the data before it's processed.
If you return any value other than `true`, the form will not be processed and the error message will be displayed. So, you can return a string as an error message.
```php
$is_valid = apply_filters( 'rwmb_profile_validate', $is_valid, $config );
```
Example:
```php
add_filter( 'rwmb_profile_validate', function ($is_valid) {
$email = $_POST['user_email'] ?? '';
if ( $email === 'alex@example.com' ) {
$is_valid = 'Email is already taken';
}
return $is_valid;
} );
```
### `rwmb_profile_insert_user_data`
This filter is used to modify the submitted user data before it's passed to the `wp_insert_user` function to **create a new user**. It accepts 2 parameters: the array of user data and the shortcode parameters.
```php
$data = apply_filters( 'rwmb_profile_insert_user_data', $data, $config );
```
Please note that this filter works only for default user fields such as user email or password. For changing custom field data, please use [`rwmb_{$field_id}_value`](/filters/rwmb-value/) filter.
### `rwmb_profile_update_user_data`
This filter is used to modify the submitted user data before it's passed to the `wp_update_user` function to **update an existing user**. It accepts 2 parameters: the array of user data and the shortcode parameters.
```php
$data = apply_filters( 'rwmb_profile_update_user_data', $data, $config );
```
Please note that this filter works only for default user fields such as user email or password. For changing custom field data, please use [`rwmb_{$field_id}_value`](/filters/rwmb-value/) filter.
### Default form fields
To modify the default register, login, or edit profile form fields, please use the following filters:
```php
$fields = apply_filters( 'rwmb_profile_register_fields', $fields );
$fields = apply_filters( 'rwmb_profile_login_fields', $fields );
$fields = apply_filters( 'rwmb_profile_info_fields', $fields );
```
### `rwmb_profile_before_save_user`
This action fires before the user is created or updated.
```php
do_action( 'rwmb_profile_before_save_user', $object );
```
The action accepts 1 parameter: the instance of the `MB_User_Profile_User` class, which handles the submission. It has the following public properties that you can use:
- `$user_id`: The submitted user ID
- `$config`: The configuration, taken from the shortcode attributes
### `rwmb_profile_after_save_user`
This action fires after the user is created or updated. At that time, all the custom fields in the meta box are already saved into the user meta.
```php
do_action( 'rwmb_profile_after_save_user', $object );
```
The action accepts 1 parameter: the instance of the `MB_User_Profile_User` class, which handles the submission. It has the following public properties that you can use:
- `$user_id`: The submitted user ID
- `$config`: The configuration, taken from the shortcode attributes
## Known issues
### Upload files/images
To be able to upload files or images (via fields `file_advanced`, `file_upload`, `image_advanced`, `image_upload`), users have to log in and proper capability upload_files to access the Media Library. If your users don't have that capability (like if they have the subscriber role), then the upload fields don't work. In that case, you can add the capability for that role as follows:
```php
add_action( 'init', function () {
$subscriber = get_role( 'subscriber' );
$subscriber->add_cap( 'upload_files' );
} );
```
Another solution is using `file` or `image` fields. Both of them work similarly. They just don't have a nice UI, but they do the job very well.
### Styling
The extension outputs the default fields' HTML with CSS comes from the Meta Box plugin. The style is basic and works in most cases. However, to make it match perfectly with your theme's style, you need to do some work with CSS.
### Caching
As you might know, Meta Box uses [nonces](https://developer.wordpress.org/apis/security/nonces/) to prevent misuse or malicious requests. As the nonce fields are outputted directly in the HTML, they might be cached by caching plugins such as W3 Total Cache, WP Super Cache, etc. And thus, the verification of the nonce might not work properly and break the form submission. In this case, please do not cache the page where the form is embedded (caching plugins allow you to do that).
# MB Views
import LiteYouTubeEmbed from 'react-lite-youtube-embed';
import 'react-lite-youtube-embed/dist/LiteYouTubeEmbed.css';
MB Views helps you to get Meta Box fields and build your templates in the front end fast and easily.
With MB Views, you can just select the fields you want to show, fill in some parameters and done! The extension supports all custom fields built with Meta Box, and also post fields (such as post title and post content), site settings, user fields, and even query fields.
You can also customize all templates in WordPress, even for post types that don't have Meta Box fields.
## Video tutorial
In this video, we show you step-by-step how to use *MB Views* to create singular and archive templates for a custom post type. We also show you the basis of Twig and how to set location rules.
## Creating a view
To create a view, go to **Meta Box > Views** and click the **Add New** button.
In the view screen, you'll see 2 areas:
- Template editors: where you can enter template code for the view. It contains 3 editors for the template, CSS, and JavaScript.
- Settings: where you can set location rules for the view.
In the main editor, you can enter any HTML or *shortcodes* for the template. All shortcodes will be parsed automatically in the front end.
## Insert fields
To insert a field, click the **Insert Field** button. It will open a panel on the right, where you can see all available fields.
Fields are categorized into 4 tabs:
- Post: contains all post fields and custom fields for posts.
- Site: contains all site fields and settings fields (created by [MB Settings Page](/extensions/mb-settings-page/) plugin).
- User: contains all user fields and custom fields for users (created by [MB User Meta](/extensions/mb-user-meta/) plugin).
- Query: contains loop and pagination for archive pages.
To insert a field, click on the field title to insert it. The field might have additional parameters (such as choosing image size for the image field). And in that case, the plugin will open a popup for you to enter or select options.
When you're done entering the field options, click the **Insert** button to insert the field in the editor. The plugin will generate a snippet and insert it into the editor.
If a field doesn't have options, then the plugin will insert a snippet into the editor immediately without opening a popup.
### Main query
The items on the Insert Field tab only work with the main query. We can understand when setting Type and Location for the View. For example, you can only use the item "Term ID" when the Type is Archive and Location is Taxonomy Archive, if you use the item "Post ID", it will not work.
### Cloneable fields
Cloneable fields are marked with a *repeat* icon, like this:
To insert a cloneable field, click on the field title, like inserting a normal field.
The plugin will generate a snippet for the field, like this:
```
{% for clone in post.tickets %}
Content here might be different depending on the field type
{% endfor %}
```
This is a `for` loop, created by using the Twig template engine. You'll find more details about it below. The content inside the `for` loop might be different depending on the field type.
### Group fields
Group fields are marked with an arrow on the left, just like in the image above. Clicking on the arrow will toggle the group sub-fields.
To insert a sub-field, click on the sub-field title, like inserting a normal field. Depending on the field type, it will open a popup for additional options or not.
:::warning Inserting sub-fields of cloneable groups
If you have a cloneable group, before inserting sub-fields, you **must** insert the `for` loop for the group first. To insert the group, click on the group title. See the Cloneable Fields section above for details.
:::
### Relationship fields
Relationships created with [MB Relationships](/extensions/mb-relationships/) extension can be inserted in the tab **Query**.
Once you registered a relationship, it will show 2 fields here: one for the "from" side, and one for the "to" side. Clicking a field will insert a loop of connected items, and inside the loop, you can insert post/term/user fields as usual.
See tutorial: [How To Display Relationships?](https://metabox.io/mb-views-how-to-display-relationships/)
## Include other views
The plugin allows you to include other views, which helps you to break down large templates into smaller ones and reuse them in other views.
To insert a view, go to the tab **Query**, and click on the view you want to insert. Note that when you include a view into another view, they have access to the same context as the current view. This means that any variable defined in the main view will be available in the included view.
See tutorial: [Creating and Including Template Parts in MB Views](https://metabox.io/mb-views-creating-including-template-parts/)
## Running PHP functions
To run PHP functions, use the `mb` proxy. It acts as a transformer between views and PHP.
Assume you want to get another post in WordPress with post ID 123, you can write a simple PHP code:
```php
$post = get_post( 123 );
echo $post->post_title;
```
With the `mb` proxy, you can call the `get_post()` function like this:
```html
{% set post = mb.get_post( 123 ) %}
{{ post.post_title }}
```
Here you see, the normal PHP function is prefixed by `mb.`, e.g. `get_post` becomes `mb.get_post`. So if you want to call a function `my_custom_function`, you need to write `mb.my_custom_function`. The parameters passed to the function remain the same.
### Custom query
Relate to the Main query above, if you use the function `get_posts()` or `get_post()`, it will return [post object](https://developer.wordpress.org/reference/classes/wp_post/).
```php
WP_Post Object
(
[ID] =>
[post_author] =>
[post_date] =>
[post_date_gmt] =>
[post_content] =>
[post_title] =>
[post_excerpt] =>
[post_status] =>
[comment_status] =>
[ping_status] =>
[post_password] =>
[post_name] =>
[to_ping] =>
[pinged] =>
[post_modified] =>
[post_modified_gmt] =>
[post_content_filtered] =>
[post_parent] =>
[guid] =>
[menu_order] =>
[post_type] =>
[post_mime_type] =>
[comment_count] =>
[filter] =>
)
```
These properties are different from the Post items in the Insert Field tab and you can only use these properties to get the post information. For the post meta, you can use the helper function `rwmb_meta()` or WordPress functions to retrieve it.
```html
{% set args = { post_type: 'post', posts_per_page: -1 } %}
{% set posts = mb.get_posts( args ) %}
{% for post in posts %}
Post title: {{ post.post_title }}
Single image:
{% set image = mb.rwmb_meta( 'single_image', '', post.ID ) %}
Post thumbnail: {{ mb.get_the_post_thumbnail( post.ID, 'thumbnail' ) }}
{% endfor %}
```
In case you want to set arguments for functions, use the `set` syntax. Twig allows you to set complex variables, like [lists with keys and values](https://twig.symfony.com/doc/1.x/templates.html#literals) and then you can pass it to the function:
```html
{% set my_var = ["first", "second"] %}
{% set my_var = {first: "first value", second: "second value"}
{% set value = mb.custom_function( my_var ) %}
```
## Custom data
The plugin allows you to pass custom data to the shortcode via custom attributes. This allows you to build flexible views and show them in multiple places with custom data.
For example, you want to display user info in a view. While fetching custom user data is fine, you might want to set user details (like "name" and "age") in some specific cases. You can pass "name" and "age" to a view shortcode like this:
```
[mbv id="your-view-id" name="Brian" age="50"]
```
And in your view template, you can use this data directly like this:
```html
Name: {{ name }}
Age: {{ age }}
```
## Locations
Each view can serve multiple pages on your website. To set where the view appears, go to **Settings** meta box below the editor:
There are several options:
### Type
What type of page do you want to set the view for? Supports:
- Singular pages
- Archive pages
- Action: the view will display when an action fires
- Code: you can use PHP or [WordPress conditional tags](https://developer.wordpress.org/themes/basics/conditional-tags/) to set the rules where to show the view.
- Shortcode: you need to use a shortcode to insert the view to the location you want. The shortcode is available *after* you save the view.
- Block: For [MB Blocks](/extensions/mb-blocks#using-mb-views), blocks can then use `render: "view:view-name"` to render the view.
### Location Rules
Where you set the rules for the singular and archive pages. Location rules are divided into groups, and in each group, you can set multiple rules.
Rules inside a group are combined with `OR` logical operator, which means the views will serve this page if either condition is satisfied.
Groups are combined with `AND` logical operator, which means the views will serve this page if all conditions are satisfied.
With the combination of `OR` and `AND`, you can build complex rules for views.
### Render type
After choosing location rules, you can decide where to render the view for those chosen pages. You have 2 options:
- Render the whole page layout, including the header and footer. This option is useful when you want to build a completely new page on your site.
- Render the whole layout between the header and footer. Using this option, you have full control to build the layout.
- Render only for the post content area. Using this option, you leave the layout to the theme and control only the post content area.
### Position
If you choose to render the view for the post content area, then you can set it to appear before, after, or replace the content area.
### Order
The order settings is used to set the loading order for views. If you have multiple views for the same page, then views with a lower order will render first.
## Hooks
### `mbv_location_validate`:
This filter is used to allow developers to create custom rules for location validation. It accepts 3 parameters:
- `$result`: the validation result
- `$view`: the view object (which is a post object)
- `$type`: the view type
For example, if you have a view that displays for all archive pages, but you don't want it to appear on pages that have query string `?custom_var=1`, you can do like this:
```php
add_filter( 'mbv_location_validate', function( $result, $view, $type ) {
// Run for 'my-view-name' only.
if ( $view->post_name !== 'my-view-name' ) {
return $result;
}
if ( isset( $_GET['custom_var'] ) && $_GET['custom_var'] == 1 ) {
return false;
}
return $result;
}, 10, 3 );
```
### `mbv_location_action_active`
This filter is used to allow developers to create custom rules for location validation for the views that have been displayed on a specific action (type = action). It accepts 3 parameters:
- `$active`: is the view active
- `$view`: the view object (which is a post object)
- `$action`: the action name
For example, if you have a view that displays on `wp_footer`, but you don't want it to appear on pages that have query string `?custom_var=1`, you can do like this:
```php
add_filter( 'mbv_location_action_active', function( $active, $view, $action ) {
// Run for 'my-view-name' only.
if ( $view->post_name !== 'my-view-name' || $action !== 'wp_footer' ) {
return $active;
}
if ( isset( $_GET['custom_var'] ) && $_GET['custom_var'] == 1 ) {
return false;
}
return $active;
}, 10, 3 );
```
### `mbv_twig_env`
This filter allows you to change the Twig instance to render the view.
```php
add_filter( 'mbv_twig_env', function( $twig ) {
// return your own $twig instance.
return $twig;
} );
```
### `mbv_data`
This filter allows you to add/change/remove data sent to Twig to render the view.
```php
add_filter( 'mbv_data', function( $data, $twig ) {
$data['custom_var1'] = 'Value 1';
$data['custom_var2'] = 'Value 2';
return $data;
}, 10, 2 );
```
## Twig
When editing a template for views, you can use any HTML/CSS/JavaScript.
In some cases, when you need to set a condition for an HTML section or loop through all values of an array, then you can use Twig.
[Twig](https://twig.symfony.com/) is a powerful template engine for PHP, which allows you to write conditions (`if..else`), control structure (`for`), and use filters to transform the output.
For example, if you want to output an image if the post doesn't have a featured image, then you can use the following snippet:
```
{% if post.thumbnail.full %}
{% else %}
{% endif %}
```
If a field has multiple values, then you can use `for`-loop to render all the values, like this:
```
{% for country in post.countries %}
{{ country }}
{% endfor %}
```
You can also use filters to transform the value, like this:
```
{{ post.date | date( 'm/d/Y' ) }}
```
For details about using Twig, please see the [documentation](https://twig.symfony.com/doc/3.x/templates.html).
## External template files
MB Views also allows you to write templates in external files in your themes/plugins and include or use it inside views or with `[mbv]` shortcode.
Using external template files has some benefits:
- You can write templates in Twig instead of PHP, which is a beautiful syntax. Twig templates also support getting WordPress and Meta Box's values easier
- You can put template files under version control like Git to track changes and never lose anything
- You can deploy (upload) templates to other websites with ease via (S)FTP, Git, or any CI/CD
Let's see how to do that:
### Adding template paths
First, you need to register the paths, where the plugin looks for template files. Use the `mbv_fs_paths` as follows:
```php
// Load template files from the 'views' folder in your theme.
add_filter( 'mbv_fs_paths', function( $paths ) {
$paths[] = get_template_directory() . '/views';
return $paths;
} );
// Or shorter
add_filter( 'mbv_fs_paths' , function( $paths ) {
return array_merge( $paths, [ get_template_directory() . '/views' ] );
} );
// Shortest with arrow functions in PHP 7.4+
add_filter( 'mbv_fs_paths' , fn( $paths ) => array_merge( $paths, [ get_template_directory() . '/views' ] ) );
```
You can also register multiple paths, the plugin will try to load templates from these paths, in the registered order:
```php
add_filter( 'mbv_fs_paths' , function( $paths ) {
return array_merge( $paths, [
get_template_directory() . '/views',
get_template_directory() . '/default',
] );
} );
```
Or you can use the filesystem loader to add paths:
```php
add_action( 'mbv_fs_loader_init', function( $fs_loader ) {
// Add a path.
$fs_loader->addPath( get_template_directory() . '/views' );
// Prepend a path, which changes the order of registered paths and thus the order to load template files.
$fs_loader->prepend( get_template_directory() . '/default' );
} );
```
### Using external views
You can include external views in your views using this snippet:
```
{% include 'header.twig' %}
```
This snippet will load the `header.twig` template from the registered paths (in the examples above - the `views` directory in your theme). If you register multiple paths, then the plugin will search for the template in these paths and return the first found template file. So, pay attention to the order of registered paths.
You can also render the template with the `[mbv]` shortcode as follows:
```
[mbv name="header.twig"]
```
Note that the file extension doesn't matter. You can name the file `header.twig`, `header.html`, or anything. It's only used to search for the template files.
### Namespace
When loading template files, the order of registered paths define the order of paths where the plugin search for a template. However, there are some cases when you have templates with the same name but used for a different purpose, such as a `header.twig` for the homepage and another `header.twig` for the rest of the website. You might use different names for files, but there's a better option is using namespaces.
To add a template with a namespace, use the code below:
```php
add_action( 'mbv_fs_loader_init', function( $fs_loader ) {
// Add 'views/home' folder under the namespace 'home'
$fs_loader->addPath( get_template_directory() . '/views/home', 'home' );
// Add another namespace
$fs_loader->addPath( get_template_directory() . '/views/default', 'default' );
} );
```
Usage:
```
{% include '@home/header.twig' %}
{% include '@default/header.twig' %}
// or with shortcodes
[mbv name="@home/header.twig"]
[mbv name="@default/header.twig"]
```
# MB WPAI Integration
MB WPAI Integration integrates WP All Import with Meta Box which ported from ACF Integration. It creates a section in WP All Import plugin to map Meta Box's fields to import data. Allows you to handle more complex fields and settings.
## Before you start
This plugin mimic the way ACF Integration works and under the hood, so it's recommend you to read [ACF Integration documentation](https://www.wpallimport.com/documentation/how-to-import-advanced-custom-fields-acf-from-csv/) first.
Also, you need to deactivate ACF Integration addon if you're using it.
## Start importing fields
MB WPAI will create a section called "Meta Box Add-On" in the WP All Import, drag and drop page. Same as ACF Integration. In this section, you can drag and drop matching fields to map them together.
### Step 1: Create a new import
Navigate to **All Import › New Import** and upload a valid import file. Our plugin will automatically identify the file type, i.e., CSV, Excel, XML, etc.
Next, choose from the drop-down list the post type that has the Advanced Custom Fields attached.
In this example, we're importing Meta Box fields to **Posts**.
Click **Continue to Step 2** to move on to the next step.
Keep in mind that your Meta Box fields need to be created and defined for posts prior to importing data.
### Step 2: Review the Import File
The **Review Import File** page appears next. Here, you can review and confirm that the import data looks correct:
The import has detected 3 records to import. To make sure that the data is correct, you can review each record with the gray arrows at the top.
In this step, you can add filers via the **Manage Filtering Options** section, if they are needed.
This example uses an XML. You can also use spreadsheet files.
Once you confirm that the data looks good, click **Continue to Step 3**.
### Step 3: Map the Incoming Data Elements to Meta Box Fields
This brings you to the Drag & Drop interface, which allows you to map the data elements to their respective target fields.
To map the data, drag each desired data element from the panel on the right to its corresponding field on the left.
The **Meta Box Add-On** section is where you define fields to import.
Locate that section by scrolling down and then enable the group to import:
You can map each individual Meta Box field as required:
You can also concatenate multiple fields into one Meta Box field, or add any static text to the field.
Once all of the relevant data elements are mapped to their target fields, click on **Continue to Step 4** at the bottom to move to the next step.
Before proceeding, make sure that you map all other fields related to the post type or custom post type that you're importing.
### Step 4: Configure the Remaining Settings and Run the Import
The **Import Settings** interface is where you configure the remaining import settings and other options:
Specifically, you need to define a **Unique Identifier** for the import. WP All Import uses the unique identifier to keep track of imported records. To create it, simply click on **Auto-detect**.
You can also define this unique identifier by manually dragging and dropping fields from the right.
Here you can modify the import behavior if it is run again (to update, delete, or create new records found on the import file). You can set up **Scheduling Options** and **Configure Advanced Settings**. With most imports, there's no need to modify any of these settings.
Click the blue **Continue** button at the end to move to the next step.
### Step 5: Verify That the Meta Box Fields Were Created Correctly
Next, you see the **Confirm & Run** interface. In the **Import Summary** section, you can review the import, what's in the import file, and other import settings.
If everything looks good, click on **Confirm & Run Import** to start the import.
When it completes, you will see the **Import Complete** screen:
That's it! The import correctly processed the posts and Meta Box fields from this example.
You can review the imported fields by checking any of the imported posts in **Posts › All Posts**.
## Advanced usage
### Concatenate fields
You can concatenate multiple fields into one Meta Box field, or add any static text to the field. This is useful in many situations when you want to combine multiple fields into one field, or add a prefix or suffix to the field.
For example, you have 2 fields: `first_name` and `last_name` and you want to concatenate them into `full_name` field. You can do it by dragging and dropping the fields to the `full_name` field like this:
Or if you have only file name in the import file, but you want to add the full URL to the field, you can do it like this:
#### Concatenate cloneable fields
Concatenation also works with cloneable fields. For example, you have a cloneable field `photos` and you want to add the full URL to each photo. You can do it like this:
```
https://photo.example.com/{photos/photo}
```
In this case, the plugin will loop through all photos and add the full URL to each photo.
### Cloneable fields
#### Using "+ Add more" button (Fixed Repeater Mode)
The easiest way to import cloneable fields is using the "+ Add more" button. Simply like how you do in editing post, click the button to add more fields and map them to the import file. This way is suitable for small number of fields, or files with a fixed number of columns.
#### Using selector "all" and "nth" in XPath (Variable Repeater Mode)
If you have a large number of fields, or the number of columns in the import file is dynamic, you can leverage XPath syntax to import them.
This applied for both cloneable and non-cloneable fields, groups and sub-fields.
For example, you have an XML file with the following structure:
```xml
...
.........
...
```
To import all photos, you can use the following XPath:
```
{photos/photo}
```
For more information about XPath, please read [W3 Schools tutorial](https://www.w3schools.com/xml/xpath_intro.asp).
To check if your XPath is correct, you can use [XPather](http://xpather.com/).
#### Cloneable Data Placements
By default, all cloneable data are imported to the first group. For example, the previous example will import all photos to the first group.
However, you can change the placement of the data by using the following syntax:
```
{photos[.]/photo}
```
Using the "dot" syntax will tell the plugin to move each item to the parent segment. In this case, it will import each photo to a new group.
#### Concatenate cloneable fields
We can also concatenate cloneable fields. For example, you have an XML file with the following structure:
```xml
...
cat.jpgdog.jpg
```
You can add `https://photo.example.com/{photos/photo}` to the `photos` field to get the full URL of the photo.
### Group fields
Working with group fields is similar to other fields. Except that the group fields itself is a container of other fields so we will have a new special field called "For each" to handle how we import data to the group fields.
#### Map fields to group fields
To map fields to group fields, simply drag and drop the fields to the group fields like we do with other fields.
#### Adding cloneable group (Fixed Repeater Mode)
Cloneable group fields work the same as cloneable fields. You can simply the "+ Add more" button to add more groups and map fields to them.
#### For each syntax (Variable Repeater Mode)
As mentioned above, the group fields is a container of other fields. So we need to tell the plugin how to import data to the group fields. This is done by using the "For each" syntax.
For example, you have an XML file with the following structure:
```xml
...
Catcat.jpgDogdog.jpg
...
```
To import each photo and its data to a new group, you can use the following XPath for **For each** field:
```
{photos/photo}
```
#### Sub-fields scope
In the previous example, we have 2 sub-fields: `title` and `url`. These sub-fields are only available inside the group fields. So we need to tell the plugin to import them to the group fields. This is done by using the "dot" syntax.
For example, to import the `title` field into sub-field, we can use the following XPath:
```
{.title}
```
Similarly, to import the `url` field into sub-field, we can use the following XPath:
```
{.url}
```
Let's put them together for more clarity:
```
For each: {photos/photo}
We import:
Title: {.title} (same as {photos/photo/title} but scoped to the group)
URL: {.url} (same as {photos/photo/url} but scoped to the group)
```
**Note:**
- If the sub-fields are not inside the group fields, you can use the normal XPath syntax to import them.
- You are not limited to only direct children xml nodes but also any level inside the group fields. For example: `{.meta/orientation/width}` also works.
- You can also use other features like concatenation, cloneable syntax... with sub-fields.
## Known issues
- When you clone a group, the later group xpath maybe override the previous group xpath when you save the first time.
You'll need to save the import again to fix it. This is due to group.js file currently doesn't work well outside of the post edit screen.
We'll fix it in the next version.
## FAQ
**Does it work with WP All Import free edition?**
Yes, it does.
# MB Yoast SEO Integration
MB Yoast SEO Integration helps you to add content of custom fields to Yoast SEO Content Analysis to have better SEO score.
## Settings
To let Yoast SEO get a field's content to analyze, add `'add_to_wpseo_analysis' => true` to the field:
```php
[
'name' => 'My custom editor',
'id' => 'custom_content',
'type' => 'wysiwyg',
'add_to_wpseo_analysis' => true,
],
```
The plugin supports all types of fields, such as text, textarea and wysiwyg.
# Meta Box AIO
Meta Box AIO is a special plugin that contains all the extensions. It allows you to install only one plugin and have everything, so you can have the plugin list short and clean.
Meta Box AIO includes the Meta Box framework, so you don't have to install it separately.
## Settings page
The plugin has a settings page under *Meta Box → Extensions*, where you can enable/disable the extensions you need/don't need.
Check/uncheck the checkbox to enable/disable the corresponding extensions. Then click **Save Changes**.
## Filters
While the settings page and the notification to install free extensions are great for users, developers might want to hide them from normal users. To do that, Meta Box AIO provides some filters:
### `mb_aio_show_settings`
This filter is used to show/hide the settings page. The callback function should return `true` to show the settings page, or `false` to hide it.
To hide the settings page, use the following code:
```
add_filter( 'mb_aio_show_settings', '__return_false' );
```
### `mb_aio_extensions`
This filter allows you to change the list of enabled premium extensions. Thus, enable/disable modules by just coding.
This filter takes a list of enabled extensions (their slugs), and returns the filtered list.
For example, the code below enables only the [MB Builder](/extensions/meta-box-builder/) extension:
```php
add_filter( 'mb_aio_extensions', function( $extensions ) {
$extensions = ['meta-box-builder'];
// You can also do
// $extensions[] = 'meta-box-builder';
return $extensions;
} );
```
## Tools
These are the Meta Box tools for managing custom fields and custom post types. They help you clean up and optimize your WordPress database.
This set of tools is only available in **Meta Box AIO**. To use it, go to **Meta Box** > **Tools**:
:::warning Important
Please back up your database before using any of these tools. This can't be reversed.
:::
### Remove orphan fields
This tool removes all custom fields that are not attached to a valid post, term, or user.
Just click on the **Remove** button, then Meta Box will notify you of the number of custom fields that have been deleted for each object.
### Remove custom fields
Use this tool to remove the specific fields via their field ID.
Simply enter the meta key and choose the object type (post, term, user or all of them).
### Change custom field key
This is useful when you want to change the custom field key without losing existing data. Meta Box allows you to select the meta key from the suggestion list.
After that, you can check the update meta key in the database.
### Change post type
This tool is to change the slug of a post type, page, or media. For the post type, its posts will be converted to the new one.
## Notes
When an extension is enabled in Meta Box AIO and is activated as an individual plugin, the individual plugin will has higher priority and will be used. The version bundled inside Meta Box AIO will not be used.
This behavior is expected and has a good benefit: whenever we release a new version for individual extensions, you can try them first on your website to ensure compatibility before updating the whole Meta Box AIO package.
# Autocomplete
import Screenshots from '@site/src/components/Screenshots';
import Choice from '../_parts/_choice.md';
The autocomplete field creates a simple text input with autocomplete feature. You can select multiple values from the predefined list.
This field uses jQuery UI library to perform the autocomplete action.
## Screenshots
## Settings
Besides the [common settings](/field-settings/), this field has the following specific settings, the keys are for use with code:
Name | Key | Description
--- | --- | ---
Choices | `options` | List of choices, each per line. If you need to set values and labels, use the format "value: Label" for each choice. When using with code, this setting is an array of `'value' => 'Label'`. It can be an URL to a remote resource that returns the array of data in JSON format.
Size of the input box | `size` | Input size. Default `30`. Optional.
This is a sample field settings array for registering this field with code:
```php
[
'name' => 'Autocomplete',
'id' => 'field_id',
'type' => 'autocomplete',
'options' => [
'java' => 'Java',
'javascript' => 'JavaScript',
'php' => 'PHP',
'csharp' => 'C#',
'kotlin' => 'Kotlin',
'swift' => 'Swift',
],
],
```
## Getting options remotely via Ajax
In case you want to use remote data instead of user-defined data for the "Choices" (`options`) settings, you can set this setting as an URL of your remote data source.
For example, you can set the "Choices" with the value: `https://yourdomain.com/wp-admin/admin-ajax.php?action=something`, which will send an ajax request to the `admin-ajax.php` file, and then you can handle it with your function as follows:
```php
add_action( 'wp_ajax_something', function() {
$s = $_REQUEST[ 'term' ];
// Do some stuff here to find matches.
$response = [
[ 'value' => '123', 'label' => 'Some Post' ],
[ 'value' => '77', 'label' => 'Another Post' ],
];
// Do some stuff to prepare JSON response ( headers, etc ).
echo wp_json_encode( $response );
die;
} );
```
Note that the data returned must be in JSON format as above. The ajax request also sends the search term via `$_REQUEST['term']` parameter as you see above.
# Background
import Screenshots from '@site/src/components/Screenshots';
The background field allows you to set background properties for a post. You can set the background color, select an image, and set other background settings.
## Screenshots
## Settings
This field doesn't have any specific settings. It only uses [common settings](/field-settings/).
This is a sample field settings array when creating this field with code:
```php
[
'id' => 'background',
'name' => 'Section background',
'type' => 'background',
],
```
## Data
This field stores background properties in a serialized array in the post meta.
## Template usage
**Getting the background properties:**
```php
$background = rwmb_meta( 'my_field_id' );
echo $background['color'];
echo $background['image'];
```
This helper function returns an array of background properties:
```php
[
'color' => '#111222',
'image' => 'https://domain.com/wp-uploads/2017/12/bg.png',
'position' => 'top left',
'attachment' => 'fixed',
'size' => 'cover',
'repeat' => 'no-repeat',
];
```
**Outputting the CSS for the background:**
```php
My section title
My section content
```
# Block Editor
import Screenshots from '@site/src/components/Screenshots';
The block editor field creates an isolated standalone Gutenberg block editor in meta boxes, settings pages, and other supported Meta Box objects. This is useful when you want to create a custom field for users to edit content with the same experience as the main WordPress block editor.
You can have multiple block editor fields on a same page, and they will not affect each other. Each editor can have a different set of allowed blocks, which is useful when you want to allow users to insert only certain blocks in a specific area of the page.
## Screenshots
## Settings
Besides the [common settings](/field-settings/), this field has a specific setting, the key is for use with code:
Name | Key | Description
--- | --- | ---
Allowed blocks | `allowed_blocks` | List of allowed block types. Leave empty to allow all blocks.
Height | `height` | Height of the editor. Can be any CSS value. Default is `300px`.
Toolbar position | `toolbar_position` | Position of the toolbar. Can be `top` (default, displayed fixed at the top) or `contextual` (displayed above the block).
This is a sample field settings array when creating this field with code:
```php
[
'name' => 'Content Blocks',
'id' => 'content_blocks',
'type' => 'block_editor',
'allowed_blocks' => [
'core/heading',
'core/columns',
'core/image',
],
]
```
## Data
This field saves data as Gutenberg block markup in the database, just like WordPress stores blocks in `post_content`.
## Displaying the value
Meta Box automatically applies `do_blocks()` when rendering the field value.
```php
rwmb_the_value( 'content_blocks' );
```
If you want to get the value as a string, and apply `do_blocks()` to it, you can use:
```php
$content = rwmb_get_value( 'content_blocks' );
echo do_blocks( $content );
```
# Button Group
import Screenshots from '@site/src/components/Screenshots';
import ChoiceSingle from '../_parts/_choice-single.md';
The button group allows you to select one or more options by enabling buttons from a button group. This field is helpful when you want to display choices in the style of a toolbar.
## Screenshots
## Settings
Besides the [common settings](/field-settings/), this field has the following specific settings, the keys are for use with code:
Name | Key | Description
--- | --- | ---
Buttons | `options` | List of buttons, each per line. If you need to set values and labels, use the format "value: Label" for each choice. When using with code, this setting is an array of `'value' => 'Label'`.
Multiple | `multiple` | Whether to allow select multiple values? `true` or `false` (default).
Display buttons horizontally | `inline` | Whether to display buttons horizontally (`true` - default) or vertically (`false`).
This is a sample field settings array when creating this field with code:
```php
[
'id' => 'styles',
'name' => 'Styles',
'type' => 'button_group',
'options' => [
'bold' => '',
'italic' => '',
'underline' => '',
],
'inline' => true,
'multiple' => true,
],
```
# Button
import Screenshots from '@site/src/components/Screenshots';
The button field creates a simple button. It doesn't have any value. Usually, this field is used to trigger custom JavaScript actions.
## Screenshots
## Settings
This field doesn't have any specific settings. It only uses [common settings](/field-settings/). But there are important settings that you should pay attention to, the keys are for use with code:
Name | Key | Description
--- | --- | ---
Default value | `std` | Button text.
Custom HTML5 attributes | `attributes` | A list of custom HTML5 attributes for the button. [More info](/custom-attributes/).
This is a sample field settings array when creating this field with code:
```php
[
'type' => 'button',
'name' => 'Advanced Settings',
'std' => 'Toggle',
'attributes' => [
'data-section' => 'advanced-section',
'class' => 'js-toggle',
],
],
```
## Data
This field does not save any value in the database.
## Custom JavaScript
As said above, this field is usually used for custom JavaScript actions. To enqueue a JavaScript file to the admin editing page, use the [rwmb_enqueue_scripts](/actions/rwmb-enqueue-scripts/) hook:
```php
add_action( 'rwmb_enqueue_scripts', 'prefix_enqueue_custom_script' );
function prefix_enqueue_custom_script() {
wp_enqueue_script( 'script-id', get_template_directory_uri() . '/js/admin.js', [ 'jquery' ], '', true );
}
```
And in the `admin.js` script, you can trigger a custom action when click the button:
```js
jQuery( function( $ ) {
$( '.js-toggle' ).on( 'click', function() {
// Do something.
} );
} );
```
# Checkbox list
import Screenshots from '@site/src/components/Screenshots';
import Choice from '../_parts/_choice.md';
The checkbox list field creates a list of tick-able checkboxes with options. You can select multiple choices from the predefined list.
## Screenshots
## Settings
Besides the [common settings](/field-settings/) such as Label, ID, Default value, Cloneable, etc., this field has the following specific settings:
Name | Key | Description
--- | --- | ---
Choices | `options` | List of choices, each per line. If you need to set values and labels, use the format "value: Label" for each choice. When using code, this setting is an array of `'value' => 'Label'`.
Display choices horizontally | `inline` | Display choices in a single line? `true` or `false`.
Display "Toggle All" button | `select_all_none` | Display "Toggle All" button to quickly toggle choices.
:::note
* The keys are for using with code.
* The interface of field settings just comes when you have the [MB Builder extension](https://metabox.io/plugins/meta-box-builder/) in your pocket. It provides the UI to create and configure fields visually. It’s already bundled in the **Meta Box AIO** and **Meta Box Lite**.
:::
When creating the field with **MB Builder**, just input options into the **Choices** box.
In some special cases, you may want the data stored (value) to be different from the data displayed (label), you can input data with the form `value`:`label`.
This is the field settings array when creating this field with code:
```php
[
'name' => 'Checkbox list',
'id' => 'field_id',
'type' => 'checkbox_list',
'inline' => true,
'select_all_none' => true,
'options' => [
'java' => 'Java',
'javascript' => 'JavaScript',
'php' => 'PHP',
'csharp' => 'C#',
'kotlin' => 'Kotlin',
'swift' => 'Swift',
],
],
```
In the post/page editor, the checkbox list will display with options.
## Data
This field saves multiple values in the database. Each value is stored in a single row in the database with the same key (similar to what `add_post_meta` does with the last parameter `false`).
If the field is cloneable, then the value is stored as a serialized array in a single row in the database. Each value of that array is an array of cloned values.
:::warning
Note that this field stores the **values**, not labels.
:::
## Template usage
### Using MB Views
[MB Views](https://docs.metabox.io/extensions/mb-views/) is an extension for Meta Box, which helps you to get Meta Box fields and build your templates on the front end fast and easily. The extension supports all custom fields built with Meta Box, and also post fields (such as post title and post content), site settings, user fields, and even query fields. MB Views is already bundled in the **Meta Box AIO**. So it's available in the Ultimate and Lifetime plans.
**Displaying selected values or labels:**
In the view, click on the **Insert Field** button.
Find the name of the created field on the list on the right sidebar.
There will be two options to output the data, they are the value and label of the choices that we input in the field.
Just choose one to output only the values, or only the labels. In the event that you want to display both of them, just insert the field twice.
Then the code will be like this:
Display only the labels:
Display both values and labels:
**Displaying cloneable values:**
No matter if the field is cloneable or not, the operation to display data from the field will be the same. The difference is just in the generated code.
### Using PHP
**Displaying selected values:**
```php
```
**Displaying selected labels:**
```php
Choices:
```
:::info
`rwmb_the_value()` automatically formats values as an unordered list.
:::
**Displaying both values and labels:**
```php
Value:
Label:
```
**Displaying cloneable values:**
```php
Value:
Label:
```
# Checkbox
import Screenshots from '@site/src/components/Screenshots';
The checkbox field creates a single checkbox.
## Screenshots
## Settings
Besides the [common settings](/field-settings/), this field has the following specific settings, the keys are for use with code:
Name | Key | Description
--- | --- | ---
Checked by default | `std` | Whether the checkbox is checked by default?
This is a sample field settings array when creating this field with code:
```php
[
'name' => 'Checkbox',
'id' => 'field_id',
'type' => 'checkbox',
'std' => 1, // 0 or 1
],
```
## Data
This field saves the "checked" and "unchecked" values in the database as "1" or "0".
## Template usage
**Conditional check:**
```php
$value = rwmb_meta( 'my_field_id' );
if ( $value ) {
echo 'Checked';
} else {
echo 'Unchecked';
}
```
**Displaying "Yes/No":**
```php
rwmb_the_value( 'my_field_id' );
```
# Color
import Screenshots from '@site/src/components/Screenshots';
The color field allows you to select a color. This field uses the built-in WordPress color picker with an extension to select the alpha channel for colors.
## Screenshots
## Settings
Besides the [common settings](/field-settings/), this field has the following specific settings, the keys are for use with code:
Name | Key | Description
--- | --- | ---
Allow to select opacity | `alpha_channel` | Whether to add opacity to the color picker. `true` or `false` (default). Optional.
Color picker options | `js_options` | Extra color picker options. [See here](https://automattic.github.io/Iris/).
This is a sample field settings array when creating this field with code:
```php
[
'name' => 'Color picker',
'id' => 'field_id',
'type' => 'color',
'alpha_channel' => true,
'js_options' => [
'palettes' => ['#125', '#459', '#78b', '#ab0', '#de3', '#f0f'],
],
],
```
## Data
This field saves the hex value of the picked color in the database.
If the field is cloneable, then the value is stored as a serialized array in a single row in the database.
## Template usage
**Getting the value:**
```php
My section title
My section content
```
**Displaying the selected color:**
```php
This is the color:
```
which displays the color as a single dot like this:
# Custom HTML
import Screenshots from '@site/src/components/Screenshots';
The custom HTML field allows you to output anything. You can even use a PHP callback function to output the HTML.
This field is usually used to display custom messages/instructions to users. Sometimes, it's used with PHP callback to display more advanced content (such as content from a query).
## Screenshots
## Settings
Besides the [common settings](/field-settings/), this field has the following specific settings, the keys are for use with code:
Name | Key | Description
--- | --- | ---
Content | `std` | The custom HTML content.
PHP Callback | `callback` | The PHP function that returns the custom HTML content. Optional.
This is a sample field settings array for registering this field with code:
```php
[
'type' => 'custom_html',
'std' => '
This is a custom HTML content
',
],
```
## Styling
Because this field is usually used to display custom content, it requires some CSS to make the content looks good. To enqueue a CSS file to the admin editing page, use the [rwmb_enqueue_scripts](/actions/rwmb-enqueue-scripts/) hook:
```php
add_action( 'rwmb_enqueue_scripts', function () {
wp_enqueue_style( 'style-id', get_template_directory_uri() . '/css/admin.css' );
} );
```
And in the `admin.css` you can put your custom styles.
# Date
import Screenshots from '@site/src/components/Screenshots';
The date field allows you to select a date via a friendly UI. This field uses the jQuery UI datepicker library to select a date.
## Screenshots
## Settings
Besides the [common settings](/field-settings/), this field has the following specific settings, the keys are for use with code:
Name | Key | Description
--- | --- | ---
Size of the input box | `size` | Size of the input box. Optional. Default 10. Without this setting, the input box is full-width.
Inline | `inline` | Whether to display the date picker inline with the input and don't require to click to show the date picker? `true` or `false` (default).
Save value as timestamp | `timestamp` | Whether to save the date in the Unix timestamp format (but still display in human-readable format)? `true` or `false` (default).
Date picker options | `js_options`|Date picker options. [See here](http://api.jqueryui.com/datepicker).
Save format | `save_format`|Custom PHP format for the datetime saved in the custom fields. [See here](https://www.php.net/manual/en/function.date.php).
:::warning Timezone and timestampt
This field gets the current time of your local computer and converts it to the timestamp value. So the Unix timestamp saved is the "timezone (UTC) + offset".
:::
This is a sample field settings array when creating this field with code:
```php
[
'name' => 'Date picker',
'id' => 'field_id',
'type' => 'date',
'js_options' => [
'dateFormat' => 'yy-mm-dd',
'showButtonPanel' => false,
],
'inline' => false,
'timestamp' => false,
],
```
## Data
If the `timestamp` is set to `true`, the field value is converted to Unix timestamp and saved to the database. Otherwise, the user input value is saved.
## Date format
It's important to understand that the date format showing in the date picker, which is set via `js_options['dateFormat']` is the jQueryUI format. It's **not** the same as PHP date format! By default, Meta Box sets the format to `yy-mm-dd`. You might want to change it to `dd-mm-yy` (for European countries) or `mm/dd/yy` (for US).
However, this is the format that users see in the date picker. You might want to save the value in another format, like `2022-10-20`, which allows you to [sort or query posts](https://metabox.io/get-posts-by-custom-fields-in-wordpress/) by date. To do that, set the value of "Save format" to `Y-m-d`. Unlike the above, the saved format **is the PHP date format**, which is similar to PHP's `date()` function.
Why is the difference? Because the plugin depends on jQueryUI to render the date picker, so we must use its format. On the back end, we can use what PHP provides us.
If you use code, then the field settings will look like this:
```php
[
'js_options' => [
'dateFormat' => 'dd-mm-yy',
],
'save_format' => 'Y-m-d',
],
```
So when displaying to users, the date will have the format of `30-01-2019`, and when saving to the database, it will have the format of `2019-01-30`.
## Template usage
**Displaying the value:**
```php
Entered:
```
**Getting the value:**
```php
Entered:
```
**Converting timestamp to another format:**
If you save the field value as a timestamp, then you can convert the value to different format, like this:
```php
Event date:
```
Or simpler:
```php
Event date: 'F j, Y'] ) ?>
```
:::info
The 2nd parameter of [rwmb_the_value()](/functions/rwmb-the-value/) accepts and extra parameter "**format**" which specify the datetime format to output in the frontend.
:::
**Querying posts by date:**
Saving values in timestamp allows you to query posts with a specific order by this field:
```php
$query = new WP_Query( [
'post_type' => 'event',
'orderby' => 'meta_value_num',
'meta_key' => 'my_field_id',
'order' => 'ASC',
] );
```
However, you still can sort posts by meta value if you set date format to something similar to `yy-mm-dd`. Anyway, querying posts by custom fields is [not recommended](https://metabox.io/custom-fields-vs-custom-taxonomies/).
# Datetime
import Screenshots from '@site/src/components/Screenshots';
The datetime field allows you to select a date and time via a friendly UI. This field uses jQuery UI date & time picker libraries.
## Screenshots
## Settings
Besides the [common settings](/field-settings/), this field has the following specific settings, the keys are for use with code:
Name | Key | Description
--- | --- | ---
Size of the input box | `size` | Size of the input box. Optional. Default 10. Without this setting, the input box is full-width.
Inline | `inline` | Whether to display the date picker inline with the input and don't require to click to show the date picker? `true` or `false` (default).
Save value as timestamp | `timestamp` | Whether to save the date in the Unix timestamp format (but still display in human-readable format)? `true` or `false` (default).
Date picker options | `js_options`|Date and picker options. See [date picker options](http://api.jqueryui.com/datepicker) and [time picker options](http://trentrichardson.com/examples/timepicker/).
Save format | `save_format`|Custom PHP format for the datetime saved in the custom fields. [See here](https://www.php.net/manual/en/function.date.php).
:::warning Timezone and timestampt
This field gets the current time of your local computer and converts it to the timestamp value. So the Unix timestamp saved is the "timezone (UTC) + offset".
:::
This is a sample field settings array when creating this field with code:
```php
[
'name' => 'Date picker',
'id' => 'field_id',
'type' => 'datetime',
'js_options' => [
'stepMinute' => 15,
'showTimepicker' => true,
'controlType' => 'select',
'showButtonPanel' => false,
'oneLine' => true,
],
'inline' => false,
'timestamp' => false,
],
```
## Data
If the `timestamp` is set to `true`, the field value is converted to Unix timestamp and saved to the database. Otherwise, the user input value is saved.
## Saving dates in another format
Meta Box already supports customizing the date format **displaying to users** via `js_options`. For example, you can set it to `dd-mm-yy`.
However, you might want to save the date in another format, like `Y-m-d`, which allows you to [sort or query posts](https://metabox.io/get-posts-by-custom-fields-in-wordpress/) by date. To do that, set the value of "Save format" to "Y-m-d".
If you use code, then the field settings will look like this:
```php
[
'js_options' => [
'dateFormat' => 'dd-mm-yy',
],
'save_format' => 'Y-m-d',
],
```
So when displaying to users, the date will have the format of `30-01-2019`, and when saving to the database, it will have the format of `2019-01-30`.
## Template usage
**Displaying the value:**
```php
Entered:
```
**Getting the value:**
```php
Entered:
```
**Converting timestamp to another format:**
If you save the field value as a timestamp, then you can convert the value to different format, like this:
```php
Event date:
```
Or simpler:
```php
Event date: 'F j, Y'] ) ?>
```
:::info
The 2nd parameter of [rwmb_the_value()](/functions/rwmb-the-value/) accepts and extra parameter "**format**" which specify the datetime format to output in the frontend.
:::
**Querying posts by date:**
Saving values in timestamp allows you to query posts with a specific order by this field:
```php
$query = new WP_Query( [
'post_type' => 'event',
'orderby' => 'meta_value_num',
'meta_key' => 'my_field_id',
'order' => 'ASC',
] );
```
However, you still can sort posts by meta value if you set date format to something similar to `yy-mm-dd`. Anyway, querying posts by custom fields is [not recommended](https://metabox.io/custom-fields-vs-custom-taxonomies/).
# Divider
import Screenshots from '@site/src/components/Screenshots';
The divider field creates a simple horizontal line. It doesn't have any value and is usually used to separate fields for a better reading experience.
## Screenshots
## Settings
This field doesn't have any specific settings.
This is a sample field settings array when creating this field with code:
```php
[
'type' => 'divider',
],
```
# Fieldset Text
import Screenshots from '@site/src/components/Screenshots';
The fieldset text creates a set of text inputs. It's useful if you want to save related information.
## Screenshots
## Settings
Besides the [common settings](/field-settings/), this field has the following specific settings, the keys are for use with code:
Name | Key | Description
--- | --- | ---
Inputs | `options` | Array of `'key' => 'Input Label'` pairs. `key` is used as keys of the array of values stored in the database.
This is a sample field settings array when creating this field with code:
```php
[
'id' => 'field_id',
'name' => 'Fieldset Text',
'type' => 'fieldset_text',
'options' => [
'name' => 'Name',
'address' => 'Address',
'email' => 'Email',
],
],
```
## Data
This field always stores the value as a serialized array in a single row in the database. Each element of that array will have the key as specified in the field's `options`.
## Template usage
**Displaying field inputs' values:**
```php
Name:
Address:
Email:
```
# File Advanced
import File from '../_parts/_file.md';
import Screenshots from '@site/src/components/Screenshots';
The file advanced field uses the WordPress media popup for selecting / uploading files. You can also reorder files if you want.
## Screenshots
## Settings
Besides the [common settings](/field-settings/), this field has the following specific settings, the keys are for use with code:
Name | Key | Description
--- | --- | ---
Max number of files | `max_file_uploads` | Max number of uploaded files. Optional.
Force delete | `force_delete` | Whether or not delete the files from Media Library when deleting them from post meta. `true` or `false` (default). Optional. Note: it might affect other posts if you use the same file for multiple posts.
MIME types | `mime_type` | The MIME type of files which you want to show in the Media Library. Note: this is a filter for items in the media popup, it doesn't restrict file types when uploading. See [common MIME types](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types).
Show status | `max_status` | Display how many files uploaded/remaining. Applied only when "Max number of files" is defined. `true` (default) or `false`. Optional.
This is a sample field settings array when creating this field with code:
```php
[
'id' => 'file',
'name' => 'File Advanced',
'type' => 'file_advanced',
'force_delete' => false,
'max_file_uploads' => 2,
'mime_type' => 'application/pdf',
'max_status' => false,
],
```
## Data
This field saves multiple attachment IDs in the database. Each value (attachment ID) is stored in a single row in the database with the same meta key (similar to what `add_post_meta` does with the last parameter `false`).
## Template usage
## Filters
This field has some filters to change the texts displayed on the screen..
Filter|Default|Description
---|---|---
`rwmb_media_add_string`|+ Add Media|Add new file string
`rwmb_media_single_files_string`|file|Singular "file" string
`rwmb_media_multiple_files_string`|files|Plural "files" string
`rwmb_media_remove_string`|Remove|File remove string
`rwmb_media_edit_string`|Edit|File edit string
`rwmb_media_view_string`|View|File view string
The code below changes the "+ Add Media" string:
```php
add_filter( 'rwmb_media_add_string', function () {
return '+ New File';
} );
```
# File Input
import Screenshots from '@site/src/components/Screenshots';
The file input field creates a simple text input for uploading a single file. You can select a file from the Media Library or enter a file URL directly (even a URL for a file hosted on another website). After selecting from the Media Library, the input file URL will be pasted into the input and is saved into the database.
## Screenshots
## Settings
This field doesn't have any specific settings. It only uses [common settings](/field-settings/).
## Data
This field saves the input file URL in the database.
## Template usage
**Displaying file:**
```php
```
# File Upload
import File from '../_parts/_file.md';
import Screenshots from '@site/src/components/Screenshots';
The file upload field displays an inline upload area that you can drag and drop or select files to upload. It doesn't open the Media Library popup for selecting existing files. You can upload new files only.
## Screenshots
## Settings
Besides the [common settings](/field-settings/), this field has the following specific settings, the keys are for use with code:
Name | Key | Description
--- | --- | ---
Max number of files | `max_file_uploads` | Max number of uploaded files. Optional.
Force delete | `force_delete` | Whether or not delete the files from Media Library when deleting them from post meta. `true` or `false` (default). Optional. Note: it might affect other posts if you use the same file for multiple posts.
MIME types | `mime_type` | MIME type of files which we want to show in the Media Library. Note: this is a filter for items in the media popup, it doesn't restrict file types when uploading.
Show status | `max_status` | Display how many files uploaded/remaining. Applied only when "Max number of files" is defined. `true` (default) or `false`. Optional.
Max file size | `max_file_size` | Maximum file size that the user can upload, in bytes. Optionally supports b, kb, mb, gb, tb suffixes. e.g. "10mb" or "1gb".
This is a sample field settings array when creating this field with code:
```php
[
'id' => 'file',
'name' => 'File upload',
'type' => 'file_upload',
'force_delete' => false,
'max_file_uploads' => 2,
'mime_type' => 'application,audio,video',
'max_status' => false,
],
```
## Data
This field saves multiple attachment IDs in the database. Each value (attachment ID) is stored in a single row in the database with the same meta key (similar to what `add_post_meta` does with the last parameter `false`).
## Template usage
## Filters
This field has some filters to change the texts displayed on the screen..
Filter|Default|Description
---|---|---
`rwmb_media_add_string`|+ Add Media|Add new file string
`rwmb_media_single_files_string`|file|Singular "file" string
`rwmb_media_multiple_files_string`|files|Plural "files" string
`rwmb_media_remove_string`|Remove|File remove string
`rwmb_media_edit_string`|Edit|File edit string
`rwmb_media_view_string`|View|File view string
`rwmb_media_select_string`|Select Files|Select files string
`rwmb_media_or_string`|or|The string "or" in "Drop files here to upload or Select Files"
`rwmb_media_upload_instructions_string`|Drop files here to upload|The upload instruction string
The code below changes the "+ Add Media" string:
```php
add_filter( 'rwmb_media_add_string', function () {
return '+ New File';
} )
```
## Binding events
You can bind various events during uploading via the `data-uploader` of the input like this:
```php
jQuery( function( $ ){
setTimeout( function() {
const myUploader = $( 'input.rwmb-file_upload.rwmb-media' ).data( 'uploader' );
myUploader.uploader.bind( 'FileUploaded', function( up, file, res ) {
console.log( 'File Uploaded' );
} );
}, 1000 );
} );
```
:::warning
You need to use `setTimeout` to make sure your code runs after the uploader is initialized.
:::
Here is the list of events of the uploader. You can see more details about them in the [official documentation of plupload](https://www.plupload.com/docs/v2/Uploader#events), the library WordPress and Meta Box use for uploading files.
Event|Description
---|---|---
`Init`|Fires when the current uploader has been initialized.
`PostInit`|Fires after the init event in case you need to perform actions there.
`Refresh`|Fires when the silverlight/flash or other shim needs to move.
`Browse`|Fires when browse_button is clicked and browse dialog shows.
`BeforeUpload`|Fires just before a file is uploaded. Can be used to cancel the upload for the specified file by returning false from the handler.
`UploadFile`|Fires when a file is to be uploaded by the runtime.
`UploadProgress`|Fires while a file is being uploaded. Use this event to update the current file upload progress.
`BeforeChunkUpload`|Fires just before a chunk is uploaded. This event enables you to override settings on the uploader instance before the chunk is uploaded.
`ChunkUploaded`|Fires when a file chunk is uploaded.
`FileUploaded`|Fires when a file is successfully uploaded.
`UploadComplete`|Fires when all files in a queue are uploaded.
`Error`|Fires when an error occurs.
`Destroy`|Fires when destroy method is called.
# File
import File from '../_parts/_file.md';
import CustomUploadFolder from '../_parts/_custom-upload-folder.md';
import Screenshots from '@site/src/components/Screenshots';
The file field creates a simple file upload with default UI like ``. Unlike other media fields, this field doesn't use Media Library UI to upload files.
## Screenshots
## Settings
Besides the [common settings](/field-settings/), this field has the following specific settings, the keys are for use with code:
Name | Key | Description
--- | --- | ---
Max number of files | `max_file_uploads` | Max number of uploaded files. Optional.
Force delete | `force_delete` | Whether or not delete the files from Media Library when deleting them from post meta. `true` or `false` (default). Optional. Note: it might affect other posts if you use the same file for multiple posts.
Custom upload folder | `upload_dir` | Full path to a custom upload folder.
Unique filename callback | `unique_filename_callback` | Custom callback to set the uploaded file name. Works only when uploading to a custom folder.
This is a sample field settings array when creating this field with code:
```php
[
'id' => 'file',
'name' => 'File',
'type' => 'file',
'force_delete' => false,
'max_file_uploads' => 2,
],
```
## Data
This field saves multiple attachment IDs in the database. Each value (attachment ID) is stored in a single row in the database with the same meta key (similar to what `add_post_meta` does with the last parameter `false`).
## Custom upload folder
## Template usage
## Filters
This field has some filters to change the texts displayed on the screen..
Filter|Default|Description
---|---|---
`rwmb_file_upload_string`|Upload Files|File upload string
`rwmb_file_add_string`|+ Add new file|Add new file string
`rwmb_file_delete_string`|Delete|File delete string
`rwmb_file_edit_string`|Edit|File edit string
All filters above accept 2 parameters:
- `$string`: the string needs to be changed
- `$field`: array of the field settings
The code below changes the "+ Add new file" string:
```php
add_filter( 'rwmb_file_add_string', function () {
return '+ New File';
} );
```
# Heading
import Screenshots from '@site/src/components/Screenshots';
The heading field creates a simple `
` heading, which has an optional description. It doesn't have any value and is usually used to separate fields into sections for better reading experience.
## Screenshots
## Settings
This field doesn't have any specific settings.
This is a sample field settings array when creating this field with code:
```php
[
'type' => 'heading',
'name' => 'Heading',
'desc' => 'Optional description',
],
```
# Hidden
The hidden field creates a simple hidden input. It's usually used to store custom data that cannot be changed.
## Screenshots
## Settings
This field doesn't have any specific settings. It only uses [common settings](/field-settings/).
To store the hidden value, put it in the `std` setting.
This is a sample field settings array when creating this field with code:
```php
[
'id' => 'field_id',
'type' => 'hidden',
// Hidden field must have predefined value
'std' => 'Hidden value',
],
```
## Data
Although the value is fixed in the code, this field still saves it in the database.
## Template usage
To get the field value, use this code
```php
The hidden value:
```
# Icon
import Screenshots from '@site/src/components/Screenshots';
The icon field allows you to select an icon from a predefined icon library and show it on the front end. With this field, you can quickly search and select an icon from any icon library:
- Font Awesome Free (default, built-in)
- Font Awesome Pro (requires your Pro account on the Font Awesome website)
- Any icon font that requires a CSS file like [Line Awesome](https://icons8.com/line-awesome), [Boxicons](https://boxicons.com/), or any icon font in your themes or plugins. This is helpful if you use use many icons from the icon font across your website.
- Your own custom icon library, where you can define your own icons with SVG. This is optimal if you use only some icons, and want to use SVG to improve the performance of the website because it doesn't require you to load a CSS file.
Depending on the icon library you use, you can output the icon on the front end as an icon font, or as an SVG.
## Screenshots
## Defining the icon library
### Font Awesome Free
Font Awesome Free is the most popular icon library available on the Internet with more than 2000 icons. It's supported and included by Meta Box and you don't have to download it.
To use Font Awesome Free for your icon field, add a field with type `icon` in the [MB Builder](/extensions/meta-box-builder/) (similar to the settings screenshot above). Leave all the icon settings as default.
If you use code, use the following [field settings](/field-settings/):
```php
[
'name' => 'Icon',
'id' => 'icon',
// highlight-next-line
'type' => 'icon', // Required.
]
```
After that, go to edit your post and you'll see the select box for search and pick an icon:
:::info
The `icon` field is inherited from the [`select_advanced`](/fields/select-advanced/) field, which makes it have the interface of the "select2" library.
:::
### Font Awesome Pro
To use Font Awesome Pro, you need to [download the "Pro For Web"](https://fontawesome.com/download) package, or [download your own kit](https://fontawesome.com/kits):
Extract it and find the file `icons.json` under the `metadata` folder:
This file contains all the data for icons, including CSS classes and SVG codes. We need to use it to select and output icons.
Now copy it to your theme or your plugin, and then add a field with type `icon` and set the following parameters in the MB Builder UI:
- Icon set: select "Font Awesome Pro"
- Icon file: absolute or relative path from the WordPress root directory to the `icons.json` file
If you use code, the field settings will look similar to this:
```php
[
'name' => 'Icon',
'id' => 'icon',
'type' => 'icon',
// highlight-start
'icon_set' => 'font-awesome-pro', // MUST.
'icon_file' => get_theme_file_path( 'assets/icons.json' ), // Path to icons.json file.
// highlight-end
]
```
After that, go to edit your post and you'll see the select box for search and pick an icon.
### Custom icon library
To use a custom icon library, you'll need to decide whether you want to use an icon font or use SVGs. Meta Box supports both of them. Below is the pros and cons of both:
Icon font | SVGs
--- | ---
Using CSS | Using SVG
Add CSS & font to the front end, which can reduce page speed | No CSS & font, best for page speed
One CSS file for all icons, no need to prepare SVG for each icon | Need to prepare SVG for each icon
### Using icon font
To use an icon font, you need to prepare the **icon CSS** file, which is a CSS file to enqueue the icon font. In the MB Builder UI, you can enter an absolute URL or a relative URL to that file from the WordPress root directory or a CDN URL if the icon font has support for it (like Line Awesome, Boxicons).
By default, the plugin will try to parse the content of the icon CSS file and extract all CSS classes for you to choose from. However, if your CSS file contains more CSS classes which are not used for icons, or you want to select only some icons, you'll need to prepare the **icon file**, which is a JSON or text file to define the icons you want to use. In the MB Builder UI, enter the absolute or relative path from the WordPress root directory.
This is the field settings for this:
If you use code, the field settings will look similar to this:
```php
[
'name' => 'Icon',
'id' => 'icon',
'type' => 'icon',
// highlight-start
'icon_file' => 'path/to/icons-file',
'icon_css' => 'https://url/to/icon/style.css',
// highlight-end
]
```
Some icon library uses JavaScript to load the icons. If you use such a library, you can set `icon_css` a callback function that enqueue the JavaScript file:
```php
[
'name' => 'Icon',
'id' => 'icon',
'type' => 'icon',
'icon_file' => 'path/to/icons-file',
// highlight-start
'icon_css' => function() {
wp_enqueue_script( 'my_icon_script', 'https://path/to/icon/script.js', [], '', true );
}
// highlight-end
]
```
The `icon_file` defines a list of icons you want to use in your project. It's best if you don't want to use all icons from the icon font.
Here is a sample icon field using Boxicons:
```php
[
'name' => 'Icon',
'id' => 'icon',
'type' => 'icon',
// highlight-start
'icon_file' => get_theme_file_path( 'assets/icons.txt' ), // Path to icons.txt in the theme.
'icon_css' => 'https://unpkg.com/boxicons@2.1.4/css/boxicons.min.css', // Boxicon CDN.
// highlight-end
]
```
In the theme, create an `icons.txt` file under the folder `assets` with the following content:
```txt title="assets/icons.txt"
bx bx-heart
bx bx-bookmark-heart
bx bx-check-circle
```
When editing a post, you'll see Boxicons as follows:
If you want the icons to have nice labels, you need to create a JSON file to specify values and labels like this:
```json title="assets/icons.json"
{
"bx bx-heart": "Heart",
"bx bx-bookmark-heart": "Bookmark",
"bx bx-check-circle": "Check"
}
```
Don't forget to update your field settings to point `icon_file` to the new `icons.json` file:
```php
[
'name' => 'Icon',
'id' => 'icon',
'type' => 'icon',
// highlight-next-line
'icon_file' => get_theme_file_path( 'assets/icons.json' ),
'icon_css' => 'https://unpkg.com/boxicons@2.1.4/css/boxicons.min.css',
]
```
When editing a post, you'll see Boxicons as follows:
### Using SVGs
To use SVGs, you'll need to get SVGs for your icons first. There are a lot of icon libraries that support downloading SVGs for icons, such as [Boxicons](https://boxicons.com/) or [Tabler icons](https://tablericons.com/). You can pick a specific icon library to use, or use an app like [Iconbuddy](https://iconbuddy.app/) or [Icones](https://icones.netlify.app) to search across multiple libraries.
Depending on how you manage icons within your project, you can *download SVGs and put them in a specific directory*, or *copy the SVG codes*.
If you **download SVGs and put them in a specific directory**, then you need to define the field as follows:
Where "Icon dir" is the absolute or relative path to the icon directory from the WordPress root path.
If you use code to register the field, your field settings will look like this:
```php
[
'name' => 'Icon',
'id' => 'icon',
'type' => 'icon',
// highlight-next-line
'icon_dir' => get_theme_file_path( 'assets/icons' ), // Path to the icon dir.
]
```
The plugin will get the **file names** and will show them as from the dropdown:
If you want to specify labels for icons, you'll need to create a JSON file as follows:
```json title="assets/icons.json"
{
"hippo": "Hippo",
"tractor": "Tractor",
"truck-monster": "Truck Monster"
}
```
Where keys are the file names and values are the icon labels.
Then in the MB Builder UI, set the "Icon file" parameter the absolute or relative path to that file from the WordPress root directory:
If you use code, the field settings look like this:
```php
[
'name' => 'Icon',
'id' => 'icon',
'type' => 'icon',
// highlight-next-line
'icon_file' => get_theme_file_path( 'assets/icons.json' ), // Path to the icon file.
'icon_dir' => get_theme_file_path( 'assets/icons' ),
]
```
Then you'll see the labels as follows:
If you **use the SVG codes**, then you only need to set the "Icon file" parameter. In this case, it **must be a JSON file that contains icon names, labels (optional), and SVG codes**.
This is a sample JSON file:
```json title="assets/icons.json"
{
"heart": "",
"bookmark": "",
"check": ""
}
```
If you want to set the icon labels, use the following format:
```json title="assets/icons.json"
{
"heart": {
"label": "Heart",
"svg": ""
},
"bookmark": {
"label": "Bookmark",
"svg": ""
},
"check": {
"label": "Check",
"svg": ""
}
}
```
When you edit a post, you'll see this field like this:
## Settings
Let's see a brief description of them before going into the steps of using a custom icon library:
Name | Key | Description
--- | --- | ---
Icon set | `icon_set` | The name of your icon set.
Icon file | `icon_file` | The full path to the icon file definition, which can be a text or JSON file.
Icon CSS | `icon_css` | URL to the icon CSS file. It's required only when you use icons as an icon font (e.g. no SVG).
Icon dir | `icon_dir` | Full path to the folder that contains all SVGs of icons.
## Data
This field saves the icon name (e.g. **CSS class** if you use an icon font) into the database.
If the field is cloneable, the value is stored as a serialized array in a single row in the database.
## Template usage
### Output format
If you use an **icon font**, Meta Box will automatically enqueue the CSS file of the icon font (which you define in the `icon_css` parameter). The plugin will output an icon font in the format of:
```html
```
In other cases where you use Font Awesome Free/Pro or your own icon library with SVG available, the plugin will output the SVG directly.
### Examples
**Getting the selected icon name (CSS class):**
```php
Selected:
```
**Displaying the selected icon (as an icon font or SVG):**
```php
```
# Image Advanced
import Image from '../_parts/_image.md';
import Screenshots from '@site/src/components/Screenshots';
The image advanced field uses the WordPress media popup for selecting / uploading images. You can also reorder images if you want.
## Screenshots
## Settings
Besides the [common settings](/field-settings/), this field has the following specific settings, the keys are for use with code:
Name | Key | Description
--- | --- | ---
Max number of files | `max_file_uploads` | Max number of uploaded files. Optional.
Force delete | `force_delete` | Whether or not delete the files from Media Library when deleting them from post meta. `true` or `false` (default). Optional. Note: it might affect other posts if you use the same file for multiple posts.
Show status | `max_status` | Display how many files uploaded/remaining. Applied only when "Max number of files" is defined. `true` (default) or `false`. Optional.
Image size | `image_size` | Image size displays in the edit page. Optional. Default "thumbnail". Image size is used to make sure images are not blurry. It’s not meant to display images with the exact width and height. Images are always displayed as a square.
New image placement | `add_to` | Whether to add new images to the beginning or the end of the list. `beginning` or `end`. Default `end`. Optional.
This is a sample field settings array when creating this field with code:
```php
[
'id' => 'image',
'name' => 'Image Advanced',
'type' => 'image_advanced',
'force_delete' => false,
'max_file_uploads' => 2,
'max_status' => false,
'image_size' => 'thumbnail',
],
```
## Data
This field saves multiple attachment IDs in the database. Each value (attachment ID) is stored in a single row in the database with the same meta key (similar to what `add_post_meta` does with the last parameter `false`).
## Template usage
## Filters
This field inherits from file advanced and thus, uses the [same filters](/fields/file-advanced/) to change the texts displayed on the screen.
Filter|Default|Description
---|---|---
`rwmb_media_add_string`|+ Add Media|Add new image string
`rwmb_media_single_images_string`|image|Singular "image" string
`rwmb_media_multiple_images_string`|images|Plural "images" string
`rwmb_media_remove_string`|Remove|Image remove string
`rwmb_media_edit_string`|Edit|Image edit string
`rwmb_media_view_string`|View|Image view string
The code below changes the "+ Add Media" string:
```php
add_filter( 'rwmb_media_add_string', 'prefix_change_add_string' );
function prefix_change_add_string() {
return '+ New Image';
}
```
## Tutorials
[How to display uploaded images as a WordPress image gallery?](https://metabox.io/display-uploaded-images-as-wordpress-image-gallery/)
# Image Select
import Screenshots from '@site/src/components/Screenshots';
The image select field allows you to select a choice visually with images. It works similar to the radio/checkbox field but uses images for a more user-friendly interface.
:::
## Screenshots
## Settings
Besides the [common settings](/field-settings/), this field has the following specific settings, the keys are for use with code:
Name | Key | Description
--- | --- | ---
Choices | `options` | List of choices, each per line. Use the format "value: Image URL" for each choice. When using with code, this setting is an array of `'value' => 'Image URL'`.
Multiple | `multiple` | Whether enable multiple selection? `true` or `false` (default).
This is a sample field settings array when creating this field with code:
```php
[
'id' => 'image_select',
'name' => 'Layout',
'type' => 'image_select',
'options' => [
'left' => 'http://placehold.it/90x90&text=Left',
'right' => 'http://placehold.it/90x90&text=Right',
'none' => 'http://placehold.it/90x90&text=None',
],
],
```
## Data
If "Multiple" is not set, this field saves the selected value in the database.
If "Multiple" is set, this field saves multiple values in the database. Each value is stored in a single row in the database with the same key (similar to what `add_post_meta` does with the last parameter `false`).
If the field is cloneable, the value is stored as a serialized array in a single row in the database.
:::warning
Note that this field stores the **values**, not image URLs.
:::
## Template usage
**Displaying the selected value:**
```php
Selected:
```
**Displaying the list of multiple choices:**
```php
```
**Displaying cloneable values:**
```php
```
# Image Upload
import Image from '../_parts/_image.md';
import Screenshots from '@site/src/components/Screenshots';
The image upload field displays an inline upload area that you can drag and drop or select images to upload.
## Screenshots
## Settings
Besides the [common settings](/field-settings/), this field has the following specific settings, the keys are for use with code:
Name | Key | Description
--- | --- | ---
Max number of files | `max_file_uploads` | Max number of uploaded files. Optional.
Force delete | `force_delete` | Whether or not delete the files from Media Library when deleting them from post meta. `true` or `false` (default). Optional. Note: it might affect other posts if you use the same file for multiple posts.
Show status | `max_status` | Display how many files uploaded/remaining. Applied only when "Max number of files" is defined. `true` (default) or `false`. Optional.
Image size | `image_size` | Image size displays in the edit page. Optional. Default "thumbnail". Image size is used to make sure images are not blurry. It’s not meant to display images with the exact width and height. Images are always displayed as a square.
New image placement | `add_to` | Whether to add new images to the beginning or the end of the list. `beginning` or `end`. Default `end`. Optional.
Max file size | `max_file_size` | Maximum file size that the user can upload, in bytes. Optionally supports b, kb, mb, gb, tb suffixes. e.g. "10mb" or "1gb".
This is a sample field settings array when creating this field with code:
```php
[
'id' => 'image',
'name' => 'Image upload',
'type' => 'image_upload',
'force_delete' => false,
'max_file_uploads' => 2,
'max_status' => false,
'image_size' => 'medium',
],
```
## Data
This field saves multiple attachment IDs in the database. Each value (attachment ID) is stored in a single row in the database with the same meta key (similar to what `add_post_meta` does with the last parameter `false`).
## Template usage
## Filters
This field inherits from file advanced and thus, uses the [same filters](/fields/file-advanced/) to change the texts displaying on the screen.
Filter|Default|Description
---|---|---
`rwmb_media_add_string`|+ Add Media|Add new image string
`rwmb_media_single_images_string`|image|Singular "image" string
`rwmb_media_multiple_images_string`|images|Plural "images" string
`rwmb_media_remove_string`|Remove|Image remove string
`rwmb_media_edit_string`|Edit|Image edit string
`rwmb_media_view_string`|View|Image view string
The code below changes the "+ Add Media" string:
```php
add_filter( 'rwmb_media_add_string', 'prefix_change_add_string' );
function prefix_change_add_string() {
return '+ New Image';
}
```
## Tutorials
[How to display uploaded images as a WordPress image gallery?](https://metabox.io/display-uploaded-images-as-wordpress-image-gallery/)
# Image
import Image from '../_parts/_image.md';
import Screenshots from '@site/src/components/Screenshots';
import CustomUploadFolder from '../_parts/_custom-upload-folder.md';
The image field creates a simple image upload with default UI like ``. Unlike other media fields, this field doesn't use Media Library UI to upload images.
This field is very similar to [file](/fields/file/). The only difference is that the file field allows uploading all file types while this field allows only images.
## Screenshots
## Settings
Besides the [common settings](/field-settings/), this field has the following specific settings, the keys are for use with code:
Name | Key | Description
--- | --- | ---
Max number of files | `max_file_uploads` | Max number of uploaded files. Optional.
Force delete | `force_delete` | Whether or not delete the files from Media Library when deleting them from post meta. `true` or `false` (default). Optional. Note: it might affect other posts if you use the same file for multiple posts.
Custom upload folder | `upload_dir` | Full path to a custom upload folder.
Unique filename callback | `unique_filename_callback` | Custom callback to set the uploaded file name. Works only when uploading to a custom folder.
This is a sample field settings array when creating this field with code:
```php
[
'name' => 'Image Upload',
'id' => 'field_id',
'type' => 'image',
'force_delete' => false,
],
```
## Data
This field saves multiple attachment IDs in the database. Each value (attachment ID) is stored in a single row in the database with the same meta key (similar to what `add_post_meta` does with the last parameter `false`).
## Custom upload folder
## Template usage
## Filters
This field has some filters to change the texts displayed on the screen.
Filter|Default|Description
---|---|---
`rwmb_file_upload_string`|Upload Files|File upload string
`rwmb_file_add_string`|+ Add new file|Add new file string
`rwmb_file_delete_string`|Delete|File delete string
`rwmb_file_edit_string`|Edit|File edit string
All filters above accept 2 parameters:
- `$string`: the string needs to be changed
- `$field`: array of the field settings
The code below changes the "+ Add new file" string:
```php
add_filter( 'rwmb_file_add_string', function () {
return '+ New File';
} );
```
## Tutorials
[How to display uploaded images as a WordPress image gallery?](https://metabox.io/display-uploaded-images-as-wordpress-image-gallery/)
# Key Value
import Screenshots from '@site/src/components/Screenshots';
The key-value field allows you to enter an unlimited group of "key-value" pairs. It's usually used for a list of items, such as a product specification.
## Screenshots
## Settings
Besides the [common settings](/field-settings/), this field has the following specific settings, the keys are for use with code:
Name | Key | Description
--- | --- | ---
Placeholder | `placeholder` | Array of placeholder texts for key and value inputs. Format `['key' => 'Key placeholder', 'value' => 'Value placeholder']`. Optional.
This is a sample field settings array when creating this field with code:
```php
[
'id' => 'key_value',
'name' => 'Key Value',
'type' => 'key_value',
'desc' => 'Add more additional info below:',
],
```
## Data
This field saves a serialized array of data of pairs in a single row in the database.
## Template usage
**Displaying list of key-value pairs:**
```php
Specification
```
or simpler:
```php
Specification
```
# Link
import Screenshots from '@site/src/components/Screenshots';
The link field allows you to insert or edit a link, which includes a URL, optional title text, an option to open the link in a new tab. You can also select an existing content (post, page, etc.).
## Screenshots
## Settings
This field has no additional settings besides the [common settings](https://docs.metabox.io/field-settings/).
This is a sample field settings array when creating this field with code:
```
[
'name' => 'Social Links',
'id' => 'social_links',
// highlight-next-line
'type' => 'link',
],
```
## Data
This field saves the value as a serialized array in the database with the following keys:
* `url`: The URL of the link.
* `title`: The link title text.
* `target`: The link target (empty or `_blank`).
* `post_id`: The selected post ID (optional). This is useful when you want to get more details of a selected post.
Example:
```
[
'url' => 'https://metabox.io',
'title' => 'Meta Box',
'target' => '_blank',
]
```
If the field is cloneable, then the value is stored as a serialized array in a single row in the database.
## Template usage
**Displaying the link in an `` tag:**
```php
```
**Displaying cloneable values:**
```php
```
# Google Maps
import Screenshots from '@site/src/components/Screenshots';
The **Google Maps field** lets you select and save a location directly on a map. It works together with an **address text field**, which supports **autocomplete** powered by the Google Maps Geocoding service.
You can set a location in two ways:
- Type an address into the text field (autocomplete helps you quickly find the place).
- Click on the map or drag the marker to a new spot. The field will then save the coordinates automatically.
## Screenshots
## Settings
In addition to the [common field settings](/field-settings/), this field has the following options:
Name | Key | Description
--- | --- | ---
Google Maps API key | `api_key` | Your Google Maps API key. [Get one here](https://developers.google.com/maps/documentation/javascript/get-api-key). **Required.**
Default location | `std` | The map's default location when it first loads. Format: `'53.346881,-6.258860'` (latitude, longitude). If not set, the map defaults to Dublin, Ireland.
Address field | `address_field` | The ID of the address field. For multiple fields, separate IDs with commas. **Required.**
Language | `language` | Set the map language. See the [full list of language codes](https://developers.google.com/maps/faq#languagesupport).
Region | `region` | A [country code top-level domain](https://en.wikipedia.org/wiki/Country_code_top-level_domain). This helps autocomplete suggest results based on a specific region. [Learn more](https://developers.google.com/maps/documentation/geocoding/intro#RegionCodes).
Marker draggable | `marker_draggable` | Determines whether the marker can be dragged. Boolean, default is `true`. When set to `false`, the marker cannot be moved on the map — the location can only be set by searching for an address (Google will place the marker automatically).
:::warning Address field required
You must create a [text field](/fields/text/) for the address input, and pass its ID to the map's **Address field** setting.
:::
The `address_field` can also be a list of multiple field IDs, separated by commas (e.g. `street,city,state`). In this case:
- You can use both text and select fields.
- Autocomplete will not work. Instead, the plugin combines the values from those fields to search for the location and updates the map whenever any field changes.
:::warning
Don't forget to enable the **Geocoding API** in your Google Cloud project - it's required for the autocomplete feature!
:::
Example field setup in code:
```php
// Address field
[
'id' => 'my_address',
'name' => 'Address',
'type' => 'text',
],
// Map field
[
'id' => 'map',
'name' => 'Location',
'type' => 'map',
'std' => '-6.233406,-35.049906,15',
'address_field' => 'my_address',
'api_key' => 'XXXXXXXXX',
],
```
## Data
The field saves the location as:
```
latitude,longitude,zoom
```
Example: `53.346881,-6.258860,14`
## Template usage
### Displaying a map
To show the map on the frontend, use [`rwmb_the_value()`](/functions/rwmb-the-value/) with extra parameters:
```php
.',
];
rwmb_the_value( 'my_field_id', $args );
?>
```
Available parameters:
Name | Description
---|---
`width` | Map width. Default: `640px`. Accepts `%` or `px`.
`height` | Map height. Default: `480px`. Accepts `%` or `px`.
`zoom` | Map zoom level. Default: value set in the admin, or `14` if not set.
`marker` | Show marker? `true` (default) or `false`.
`marker_icon` | URL to a custom marker icon. Optional.
`marker_title` | Marker tooltip (shows on hover).
`info_window` | Content shown when clicking the marker. HTML allowed. Avoid quotes inside to prevent JavaScript issues.
`js_options` | Pass custom JavaScript options. [Reference](https://developers.google.com/maps/documentation/javascript/reference#MapOptions).
The code below shows how to use `js_options` for advanced control how the map is displayed:
```php
$args = [
'width' => '640px',
'height' => '480px',
'js_options' => [
'mapTypeId' => 'HYBRID',
'zoomControl' => false,
],
];
rwmb_the_value( 'my_field_id', $args );
```
### Getting the raw field value
If you don't need to render the map but just want the coordinates:
```php
$location = rwmb_get_value( $field_id );
echo $location['latitude'];
echo $location['longitude'];
echo $location['zoom'];
```
See more about [`rwmb_get_value()`](/functions/rwmb-get-value/).
### Displaying a map inside a group
If the map is part of a group field, the helper functions above won't work. Instead, use the built-in `RWMB_Map_Field::render_map()` helper:
```php
$args = [
'width' => '640px',
'height' => '480px',
'js_options' => [
'mapTypeId' => 'HYBRID',
'zoomControl' => false,
],
];
$group_values = rwmb_meta( 'group_id' );
$args = [
'api_key' => 'your-API-key'
];
// If the group is cloneable
foreach ( $group_values as $group_value ) {
echo RWMB_Map_Field::render_map( $group_value['map_id'], $args );
}
```
The helper function accepts:
Name | Description
--- | ---
`$location` | Map location in the format `latitude,longitude[,zoom]` (zoom is optional). Same as the map field value.
`$args` | Additional display options. Same as in `rwmb_the_value()`.
## Filters
### `rwmb_google_maps_url`
This filter lets you modify the Google Maps script URL - for example, to add extra libraries.
It receives the script URL as a parameter and should return the modified URL.
For example, the code below adds "geometry" library to the Google Maps script:
```php
add_filter( 'rwmb_google_maps_url', function ( $url ) {
return add_query_arg( 'libraries', 'geometry', $url );
} );
```
# Number
import Screenshots from '@site/src/components/Screenshots';
The number field creates a simple HTML5 number input. You can enter a number or use the up/down arrow to change the number. It works with both integers and float numbers.
## Screenshots
## Settings
This meta number field inherits all settings from the [text field](/fields/text/). Besides, it has the following specific settings, the keys are for use with code:
Name | Key | Description
--- | --- | ---
Step | `step` | The increments for the value. Accepts an integer, a float number, or the string `any` (if you want to enter any value). Default is `1`. Optional.
Min value | `min` | Minimum value. Optional.
Max value | `max` | Maximum value. Optional.
This is a sample field settings array when creating this field with code:
```php
[
'name' => 'Number',
'id' => 'number',
'type' => 'number',
'min' => 0,
'step' => 0.5,
],
```
## Data
This meta number field saves the entered value into the database.
If the field is cloneable, then the value is stored as a serialized array in a single row in the database.
## Template usage
**Displaying the value:**
```php
Entered:
```
**Getting the value:**
```php
Entered:
```
**Formatting the value:**
```php
Entered:
```
**Displaying cloneable values:**
```php
```
# oEmbed
import Screenshots from '@site/src/components/Screenshots';
The oEmbed field creates a simple text input for entering a media URL. This field offers a live preview of the media content such as videos, audios, images, tweets, polls, podcasts, etc. from [many 3rd-party services](https://codex.wordpress.org/Embeds).
It helps to show the live preview below the field when input data, and also display the media’s preview on frontend much easier in most cases.
## Screenshots
This is an easy way to add videos from [Youtube](http://www.youtube.com/), [Vimeo](http://vimeo.com/), or [Tiktok](https://www.tiktok.com/en), musics from [Spotify](http://www.spotify.com/) or [SoundCloud](http://soundcloud.com/), presentation slideshows from [SlideShare](http://www.slideshare.net/), and so much other content from third-party services into your WordPress site.
## Settings
Besides the [common settings](/field-settings/), this field has the following specific settings, the keys are for use with code:
Name | Key | Description
--- | --- | ---
Size of the input box | `size` | Size of the input box. Without this setting, the input box is full-width
Not available text | `not_available_string` | The text message is displayed to users when the embed media is not available. Accepts HTML.
This is a sample field settings array when creating this field with code:
```php
[
'id' => 'oembed',
'name' => 'oEmbed(s)',
'type' => 'oembed',
],
```
## Data
This field **saves the URL** of the media (video, music, slideshow, podcast, etc.) to the database.
## Template usage
**Displaying the embedded media**:
```php
Youtube video
```
**Getting the URL:**
```php
$url = rwmb_get_value( 'my_field_id' );
echo $url;
```
## Filters
To change the message for all oEmbed field when no embed is available, use the filter `rwmb_oembed_not_available_string`, which accepts 2 parameters: message and URL.
```php
add_filter( 'rwmb_oembed_not_available_string', function( $message, $url ) {
$message = 'Sorry, what you are looking here is not available.';
return $message;
}, 10, 2 );
```
You also can hide the message with CSS on the front end by putting this code into your theme or in *Customize > Additional CSS*:
```css
.rwmb-oembed-not-available {
display: none;
}
```
# Open Street Map
import Screenshots from '@site/src/components/Screenshots';
The **Open Street Map (OSM) field** lets you select and save a location using [OpenStreetMap](https://openstreetmap.org).
It's very similar to the [Google Maps field](/fields/map/), but it provides a free alternative since [Google now requires billing details](https://metabox.io/meta-box-weekly-updates-july-2018/) (such as a credit card) to use their maps.
This field includes all the features of the Google Maps field. It comes with an address text field that supports **autocomplete**, powered by the [Nominatim](https://wiki.openstreetmap.org/wiki/Nominatim) geocoding service.
You can choose a location in two ways:
- Type in an address and select from the autocomplete suggestions.
- Click directly on the map or drag the marker - the field will automatically save the new coordinates.
The map itself is rendered using the [Leaflet](https://leafletjs.com) library.
## Screenshots
## Settings
In addition to the [common field settings](/field-settings/), this field has the following options:
Name | Key | Description
--- | --- | ---
Default location | `std` | The map's default location when it loads. Format: `'53.346881,-6.258860'` (latitude, longitude). If not set, the map will default to Dublin, Ireland.
Address field | `address_field` | The ID of the address field. For multiple fields, separate IDs with commas. **Required.**
Language | `language` | Set the language for more accurate autocomplete results. See the [list of language codes](https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html). Optional.
Region | `region` | Restrict search results to one or more countries. Accepts [ISO 3166-1 alpha-2 codes](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). Optional.
Marker draggable | `marker_draggable` | Determines whether the marker can be moved. Boolean, default is `true`. When set to `false`, the marker cannot be dragged - the location can only be set by searching for an address.
:::warning Address field required
You must create a [text field](/fields/text/) for the address input, and pass its ID to the map's **Address field** setting.
:::
The `address_field` can also be a list of multiple field IDs, separated by commas (e.g. `street,city,state`).
In this case:
- You can use both text and select fields.
- Autocomplete will not work. Instead, the plugin will combine the values of these fields, search for the full address, and update the map whenever any of those fields changes.
Example field setup in code:
```php
// Address field
[
'id' => 'my_address',
'name' => 'Address',
'type' => 'text',
],
// Map field
[
'id' => 'map',
'name' => 'Location',
'type' => 'osm',
'std' => '-6.233406,-35.049906,15',
'address_field' => 'my_address',
],
```
## Data
The field saves the location as:
```
latitude,longitude,zoom
```
Example: `53.346881,-6.258860,14`
## Template usage
### Displaying the map
To show the map on the frontend, use [`rwmb_the_value()`](/functions/rwmb-the-value/) with extra parameters:
```php
.',
];
rwmb_the_value( 'my_field_id', $args );
?>
```
Available parameters:
Name | Description
---|---
`width` | Map width. Default: `640px`. Accepts `%` or `px`.
`height` | Map height. Default: `480px`. Accepts `%` or `px`.
`zoom` | Map zoom level. Default: value set in the admin, or `14` if not set.
`marker` | Show marker? `true` (default) or `false`.
`marker_icon` | URL to a custom marker icon. Optional.
`marker_title` | Marker tooltip (shown on hover).
`info_window` | Content shown when clicking the marker. HTML allowed. Avoid using quotes inside to prevent JavaScript issues.
`js_options` | Pass additional map options directly to the Leaflet library. See the [Leaflet map options](https://leafletjs.com/reference-1.3.2.html#map-option).
The code below shows how to use `js_options` for advanced control how the map is displayed:
```php
$args = [
'width' => '640px',
'height' => '480px',
'js_options' => [
'doubleClickZoom' => false,
],
];
rwmb_the_value( 'my_field_id', $args );
```
### Getting the raw field value
If you don't need to render the map but just want the coordinates:
```php
$location = rwmb_get_value( $field_id );
echo $location['latitude'];
echo $location['longitude'];
echo $location['zoom'];
```
See more about [`rwmb_get_value()`](/functions/rwmb-get-value/).
### Displaying a map inside a group
If the map is part of a group field, the helper functions above won't work. Instead, use the built-in `RWMB_OSM_Field::render_map()` helper:
```php
$args = [
'width' => '640px',
'height' => '480px',
];
$group_values = rwmb_meta( 'group_id' );
// If the group is cloneable
foreach ( $group_values as $group_value ) {
echo RWMB_OSM_Field::render_map( $group_value['map_id'], $args );
}
```
The helper function accepts:
Name | Description
--- | ---
`$location` | Map location in the format `latitude,longitude[,zoom]` (zoom is optional). Same as the map field value.
`$args` | Additional display options. Same as in `rwmb_the_value()`.
# Password
import Screenshots from '@site/src/components/Screenshots';
The password field creates a simple password input. The password is encrypted by [wp_hash_password()](https://developer.wordpress.org/reference/functions/wp_hash_password/) before saving it into the database to make sure it's safe.
## Screenshots
## Settings
Besides the [common settings](/field-settings/), this field has the following specific settings, the keys are for use with code:
Name | Key | Description
--- | --- | ---
Size of the input box | `size` | Size of the input box. Without this setting, the input box is full-width.
This is a sample field settings array when creating this field with code:
```php
[
'name' => 'Password',
'id' => 'password',
'type' => 'password',
],
```
## Data
This field saves the encrypted password in the database for better security. The password is encrypted by [wp_hash_password()](https://developer.wordpress.org/reference/functions/wp_hash_password/) function.
## Template usage
As the password is encrypted in the database, you **cannot** get the original password via code. There's no reversing function that can turn a password hash into the original one. Otherwise, it will be insecure.
Instead of trying to get the original password, you should check the saved password is correct, like this:
```php
## Settings
Besides the [common settings](/field-settings/), this field has the following specific settings, the keys are for use with code:
Name | Key | Description
--- | --- | ---
Post types | `post_type` | Post types to query. Can be a string (for a single post type) or array (for multiple post types). Required.
Query args | `query_args` | Query arguments for getting post objects. Uses the same arguments as [WP_Query](https://developer.wordpress.org/reference/classes/wp_query/#parameters). Optional.
Set as parent | `parent` | Whether or not to set the selected post as the parent for the current being edited post? `true` or `false` (default).
Placeholder | `placeholder` | The placeholder for the select box. Default is "Select a `{post label}`". Applied only when the field type is a select field.
Field type | `field_type` | How the posts are displayed? See below.
This field inherits the look and field (and settings) from other fields, depending on the field type, which accepts the following value:
Field type | Description | Settings inherited from
--- | --- | ---
`select` | Simple select dropdown. | [Select](/fields/select/)
`select_advanced` | Beautiful select dropdown using the select2 library. This is the default value. | [Select advanced](/fields/select-advanced/)
`select_tree` | Hierarchical list of select boxes that allows to select multiple items (select/deselect parent item will show/hide child items). Applied only when the post type is hierarchical (like pages). | [Select](/fields/select/)
`checkbox_list` | Flatten list of checkboxes that allows to select multiple items. | [Checkbox list](/fields/checkbox-list/)
`checkbox_tree` | Hierarchical list of checkboxes that allows to select multiple items (select/deselect parent item will show/hide child items). Applied only when the post type is hierarchical (like pages). | [Checkbox list](/fields/checkbox-list/)
`radio_list` | Flatten list of radio boxes that allows to select only 1 item. | [Radio](/fields/radio/)
This is a sample field settings array when creating this field with code:
```php
[
'name' => 'Select a page',
'id' => 'page',
'type' => 'post',
'post_type' => 'page',
'field_type' => 'select_advanced',
'placeholder' => 'Select a page',
'query_args' => [
'post_status' => 'publish',
'posts_per_page' => - 1,
],
],
```
:::info
The default value of `query_args` is `['post_status' => 'publish']`. If you want to query posts with another status (`draft`, `pending`, etc.) or query attachments (which have the status `inherit`), then change the `post_status` to the corresponding value, or to `any`.
:::
## Ajax load
Meta Box uses Ajax to increase the performance of the field query. Instead of fetching all posts at once, the plugin now fetches only some posts when the page is loaded, and then it fetches more posts when users scroll down to the list.
See this video for a demonstration (the UI of the MB Builder was from the old version, the new version of MB Builder has a better UI):
:::info
This feature is available only for fields that set the field type to **select advanced**. There are some extra parameters for you to disable or customize.
:::
### Enable/Disable ajax requests
This feature is enabled by default when you set the field type to "select advanced".
If you're using code to create this field, the settings to enable/disable it is `ajax`, which accepts a boolean value (and it's `true` by default):
```php
[
'id' => 'project',
'title' => 'Project',
'type' => 'post',
'post_type' => 'project',
// highlight-next-line
'ajax' => true,
],
```
Setting this parameter to `false` will disable ajax requests.
### Limit the number of posts for pagination
The number of posts for pagination is set via the `posts_per_page` parameter in the "Query args" setting:
```php
[
'id' => 'project',
'title' => 'Project',
'type' => 'post',
'post_type' => 'project',
'ajax' => true,
'query_args' => [
// highlight-next-line
'posts_per_page' => 10,
],
],
```
When fetching new posts, the new posts will be appended to the list of options in the dropdown, to make the infinite scroll effect.
:::info Initial load
The number of posts **doesn't affect the initial load** of the field. When the field is loaded, Meta Box **only queries for saved posts** (which is usually not many). So the initial query is very minimal and doesn't cause any performance problems.
:::
### Searching parameters
You probably don't want to perform an ajax request when opening the dropdown at first. You might want to _make ajax requests only when users type something_ and search for that. To do that, you need to set the `minimumInputLength` for the input, as below:
```php
[
'id' => 'project',
'title' => 'Project',
'type' => 'post',
'post_type' => 'project',
'ajax' => true,
'query_args' => [
'posts_per_page' => 10,
],
'js_options' => [
// highlight-next-line
'minimumInputLength' => 1,
],
],
```
This parameter sets the minimum number of characters required to start a search. It may be good if you don't want users to make too many ajax requests that could harm your server.
## Data
This field saves post ID(s) in the database.
If "Multiple" is not set, a single post ID is saved in the database. Otherwise, the field saves multiple post IDs in the database, where each post ID is stored in a single row in the database with the same meta key (similar to what `add_post_meta` does with the last parameter `false`).
If the field is cloneable, then the value is stored as a serialized array in a single row in the database.
If "Parent" is set, this field doesn't save any data. Instead, it sets the selected post as the parent for the current being edited post.
## Template usage
**Getting selected post ID:**
```php
Selected post ID:
```
**Getting selected post object:**
```php
```
**Displaying selected post title:**
```php
```
or simpler:
```php
false] ) ?>
```
**Displaying the selected post with link:**
```php
```
or simpler:
```php
```
**Additional options for `rwmb_the_value()`:**
Using `rwmb_the_value` also has some extra options as follows:
```php
false] ) ?>
'view'] ) ?>
'edit'] ) ?>
```
**Displaying multiple selected posts:**
If "Multiple" is set or the field is cloneable, you can loop through the returned values like this:
```php
Related posts
```
of simpler:
```php
Related posts
```
`rwmb_the_value()` automatically outputs multiple selected posts as an unordered list with links to each post.
## Filters
`rwmb_post_choice_label` and `rwmb_{$field_id}_choice_label`
These filters allow developers to change the label of `post` fields. The first label applies to all `post` fields and the second one is for a specific field.
Example: If you are using a field called `my_field` and you want to change the label, use the code below:
```php
function my_field_filter( $label, $field, $post ) {
return $post->post_title . ' - ' . $post->post_status;
}
add_filter( 'rwmb_my_field_choice_label', 'my_field_filter', 10, 3 );
```
# Radio
import Screenshots from '@site/src/components/Screenshots';
The radio field creates a simple list of radio inputs where you can select a single choice from the predefined list.
## Screenshots
## Settings
Besides the [common settings](/field-settings/), this field has the following specific settings, the keys are for use with code:
Name | Key | Description
--- | --- | ---
Choices | `options` | List of choices, each per line. If you need to set values and labels, use the format "value: Label" for each choice. When using with code, this setting is an array of `'value' => 'Label'`.
Inline | `inline` | Display choices on a single line? `true` or `false`.
This is a sample field settings array when creating this field with code:
```php
[
'name' => 'Radio',
'id' => 'radio',
'type' => 'radio',
'inline' => false,
'options' => [
'value1' => 'Label1',
'value2' => 'Label2',
],
],
```
## Data
This field saves a single selected value in the database.
If the field is cloneable, then the value is stored as a serialized array in a single row in the database.
:::warning
Note that this field stores the **values**, not labels.
:::
## Template usage
**Displaying the selected value:**
```php
Selected:
```
**Displaying the selected label:**
```php
My choice:
```
**Displaying both value and label:**
```php
Value:
Label:
```
# Range
import Screenshots from '@site/src/components/Screenshots';
The range field creates an HTML5 range field where you can select a number by dragging a control.
This field is very similar to the [number](/fields/number/) field. It just uses a different control to select a number instead of entering it.
## Screenshots
## Settings
Besides the [common settings](/field-settings/), this field has the following specific settings, the keys are for use with code:
Name | Key | Description
--- | --- | ---
Step | `step` | The increments for the value. Accepts an integer, a float number, or the string `any` (if you want to enter any value). Default is `1`. Optional.
Min value | `min` | Minimum value. Optional.
Max value | `max` | Maximum value. Optional.
This is a sample field settings array when creating this field with code:
```php
[
'name' => 'Range',
'id' => 'range',
'type' => 'range',
'min' => 0,
'max' => 60,
'step' => 5,
],
```
## Data
This field saves the entered value into the database.
If the field is cloneable, then the value is stored as a serialized array in a single row in the database.
## Template usage
**Displaying the value:**
```php
Entered:
```
**Getting the value:**
```php
Entered:
```
**Formatting the value:**
```php
Entered:
```
**Displaying cloneable values:**
```php
```
# Select Advanced
import Screenshots from '@site/src/components/Screenshots';
import ChoiceSingle from '../_parts/_choice-single.md';
The select advanced field creates a beautiful select dropdown using the [select2](https://select2.org/) library.
## Screenshots
## Settings
Besides the [common settings](/field-settings/), this field has the following specific settings, the keys are for use with code:
Name | Key | Description
--- | --- | ---
Choices | `options` | List of choices, each per line. If you need to set values and labels, use the format "value: Label" for each choice. When using with code, this setting is an array of `'value' => 'Label'`.
Multiple | `multiple` | Whether to allow select multiple values? `true` or `false` (default).
Placeholder | `placeholder` | The placeholder text.
Display "Toggle All" button | `select_all_none` | Display "Toggle All" button to quickly toggle choices. Applied only when "Multiple" is set.
Select2 options | `js_options` | Options for `select2` library. [See here](https://select2.org/configuration).
By default, Meta Box applies these default options for select2:
Name | Value | Description
--- | ---
`allowClear` | `true` | Allow users to clear selection.
`width` | `resolve` | Set width by element's width.
`placeholder` | `$field['placeholder']` | Make `placeholder` works just like `select` field.
This is a sample field settings array when creating this field with code:
```php
[
'name' => 'Select Advanced',
'id' => 'select_advanced',
'type' => 'select_advanced',
'options' => [
'java' => 'Java',
'javascript' => 'JavaScript',
'php' => 'PHP',
'kotlin' => 'Kotlin',
'swift' => 'Swift',
],
'placeholder' => 'Select an Item',
'js_options' => [
'containerCssClass' => 'my-custom-class',
],
],
```
# Select
import Screenshots from '@site/src/components/Screenshots';
import ChoiceSingle from '../_parts/_choice-single.md';
The select field creates a simple select dropdown. You can select one or multiple values from the predefined list.
## Screenshots
## Settings
Besides the [common settings](/field-settings/), this field has the following specific settings, the keys are for use with code:
Name | Key | Description
--- | --- | ---
Choices | `options` | List of choices, each per line. If you need to set values and labels, use the format "value: Label" for each choice. When using with code, this setting is an array of `'value' => 'Label'`.
Multiple | `multiple` | Whether to allow select multiple values? `true` or `false` (default).
Placeholder | `placeholder` | The placeholder text.
Display "Toggle All" button | `select_all_none` | Display "Toggle All" button to quickly toggle choices. Applied only when "Multiple" is set.
Flatten | `flatten` | Display sub items without indentation. `true` or `false` (default). See below to know how to define sub items.
Callback | `_callback` | A callable function that returns an array of choices. The function should return an array of `'value' => 'Label'`.
This is a sample field settings array when creating this field with code:
```php
[
'name' => 'Select',
'id' => 'select',
'type' => 'select',
'multiple' => true,
'placeholder' => 'Select an item',
'select_all_none' => true,
'options' => [
'java' => 'Java',
'javascript' => 'JavaScript',
'php' => 'PHP',
'kotlin' => 'Kotlin',
'swift' => 'Swift',
],
],
```
Besides the normal list of choices, you can define sub choices as follows:
```php
[
'name' => 'Select',
'id' => 'select',
'type' => 'select',
'placeholder' => 'Select an Item',
// highlight-next-line
'flatten' => false,
'options' => [
[
'value' => 'monkeys',
'label' => 'Monkeys',
],
[
'value' => 'king_kong',
'label' => 'King Kong',
// highlight-next-line
'parent' => 'monkeys',
],
[
'value' => 'curious_george',
'label' => 'Curious George',
// highlight-next-line
'parent' => 'monkeys',
],
[
'value' => 'donkeys',
'label' => 'Donkeys',
],
[
'value' => 'eeyore',
'label' => 'Eeyore',
// highlight-next-line
'parent' => 'donkeys',
],
[
'value' => 'guss',
'label' => 'Gus',
// highlight-next-line
'parent' => 'donkeys',
],
],
],
```
Here is how it looks:
# Sidebar
import Screenshots from '@site/src/components/Screenshots';
The sidebar field allows you to select one or multiple sidebars. This field has several settings that can be displayed as a: simple select dropdown, checkbox list, or beautiful select dropdown with select2 library.
## Screenshots
## Settings
Besides the [common settings](/field-settings/), this field has the following specific settings, the keys are for use with code:
Name | Key | Description
--- | --- | ---
Placeholder | `placeholder` | The placeholder for the select box. The default is "Select a sidebar". Applied only when the field type is a select field.
Field type | `field_type` | How the sidebars are displayed? See below.
This field inherits the look and field (and settings) from other fields, depending on the field type, which accepts the following value:
Field type | Description | Settings inherited from
--- | --- | ---
`select` | Simple select dropdown. | [Select](/fields/select/)
`select_advanced` | Beautiful select dropdown using the select2 library. This is the default value. | [Select advanced](/fields/select-advanced/)
`checkbox_list` | Flatten list of checkboxes which allows to select multiple items. | [Checkbox list](/fields/checkbox-list/)
`radio_list` | Flatten list of radio boxes which allows to select only 1 item. | [Radio](/fields/radio/)
This is a sample field settings array when creating this field with code:
```php
[
'name' => 'Sidebar',
'id' => 'sidebar',
'type' => 'sidebar',
'field_type' => 'select_advanced',
'placeholder' => 'Select a sidebar',
],
```
## Data
This field saves sidebar ID(s) in the database.
If "Multiple" is not set, a single sidebar ID is saved in the database. Otherwise, the field saves multiple sidebar IDs in the database, where each sidebar ID is stored in a single row in the database with the same meta key (similar to what `add_post_meta` does with the last parameter `false`).
If the field is cloneable, then the value is stored as a serialized array in a single row in the database.
## Template usage
**Display widgets for the selected sidebar:**
```php
```
**Checking if the selected sidebar has widgets and displaying it:**
```php
## Settings
Besides the [common settings](/field-settings/), this field has the following specific settings, the keys are for use with code:
Name | Key | Description
--- | --- | ---
Force delete | `force_delete` | Whether or not delete the files from Media Library when deleting them from post meta. `true` or `false` (default). Optional. Note: it might affect other posts if you use the same file for multiple posts.
Image size | `image_size` | Image size displays in the edit page. Optional. Default "thumbnail". Image size is used to make sure images are not blurry. It’s not meant to display images with the exact width and height. Images are always displayed as a square.
This is a sample field settings array when creating this field with code:
```php
[
'type' => 'single_image',
'name' => 'Single Image',
'id' => 'my_image',
],
```
## Data
This field saves the attachment ID in the database.
## Template usage
**Displaying uploaded image:**
```php
'thumbnail'] ); ?>
Logo
```
or simpler:
```php
Logo
'thumbnail'] ) ?>
```
`rwmb_the_value()` outputs the image, and `rwmb_meta()` returns an array of image details:
```php
[
'ID' => 123,
'name' => 'logo-150x80.png',
'path' => '/var/www/wp-content/uploads/logo-150x80.png',
'url' => 'https://example.com/wp-content/uploads/logo-150x80.png',
'width' => 150,
'height' => 80,
'full_url' => 'https://example.com/wp-content/uploads/logo.png',
'title' => 'Logo',
'caption' => 'Logo caption',
'description' => 'Used in the header',
'alt' => 'Logo ALT text',
'srcset' => 'large.jpg 1920w, medium.jpg 960w, small.jpg 480w', // List of responsive image src
'sizes' => [], // List of image sizes. See https://developer.wordpress.org/reference/functions/wp_get_attachment_metadata/
'image_meta' => [], // List of image meta. See https://developer.wordpress.org/reference/functions/wp_get_attachment_metadata/
];
```
**Display the image with link to the full-size version (for lightbox effect):**
```php
'thumbnail'] ); ?>
Logo
```
or simpler:
```php
Logo
'thumbnail', 'link' => true] ) ?>
```
The 2nd argument for `rwmb_meta()` and `rwmb_the_value()` is an array of extra parameters and accepts the following parameters:
Name|Description
---|---
`size`|Image size returned. Optional. Default `thumbnail`.
`link`|Set to `true` to show a link to the full-size version. Default `false`.
## Filters
This field inherits from image advanced and thus, uses the [same filters](/fields/image-advanced/) to change the texts displayed on the screen.
Filter|Default|Description
---|---|---
`rwmb_media_add_string`|+ Add Media|Add new image string
`rwmb_media_single_images_string`|image|Singular "image" string
`rwmb_media_multiple_images_string`|images|Plural "images" string
`rwmb_media_remove_string`|Remove|Image remove string
`rwmb_media_edit_string`|Edit|Image edit string
`rwmb_media_view_string`|View|Image view string
The code below changes the "+ Add Media" string:
```php
add_filter( 'rwmb_media_add_string', 'prefix_change_add_string' );
function prefix_change_add_string() {
return '+ New Image';
}
```
# Slider
import Screenshots from '@site/src/components/Screenshots';
The slider field creates a slider where you can select a number by dragging a control. This field uses jQuery UI library to create the UI.
## Screenshots
## Settings
Besides the [common settings](/field-settings/), this field has the following specific settings, the keys are for use with code:
Name | Key | Description
--- | --- | ---
Prefix | `prefix` | Text displayed before the field value. Optional.
Suffix | `suffix` | Text displayed after the field value. Optional.
Slider options | `js_options` | jQuery UI slider options. [See here](https://api.jqueryui.com/slider/).
By default, Meta Box applies these default slider options:
Name | Value | Description
--- | ---
`range` | `min` | Create a range from the minimum value to one handle.
`value` | `$field['std']` | Set the default field value.
If you set `range` to `true`, the plugin will save 2 values in the database, separated by pipe (`|`) character, e.g. `15|90`.
This is a sample field settings array when creating this field with code:
```php
[
'name' => 'Slider',
'id' => 'slider',
'type' => 'slider',
'prefix' => '$',
'suffix' => ' USD',
'js_options' => [
'min' => 10,
'max' => 255,
'step' => 5,
],
'std' => 150,
],
```
## Data
This field saves a single selected value (without the prefix and suffix) in the database.
If the field is cloneable, the value is stored as a serialized array in a single row in the database.
## Template usage
**Displaying the field value:**
```php
Selected value:
```
or simpler:
```php
Selected value:
```
# Switch
import Screenshots from '@site/src/components/Screenshots';
The switch field shows an on/off switch for you to enable/disable something. You can choose a style (rounded or square) and set custom text/icon labels.
## Screenshots
## Settings
Besides the [common settings](/field-settings/), this field has the following specific settings, the keys are for use with code:
Name | Key | Description
--- | --- | ---
Style | `style` | The switch style. `rounded` (default) or `square`.
Custom ON status label | `on_label`|The label for "On" status. Can be any HTML. You can set the text "Enable" or a check icon like ``. When this setting is set to empty string, it displays a style like iOS switch.
Custom OFF status label | `off_label`|Similar to the above but for the "Off" status.
This is a sample field settings array when creating this field with code:
```php
[
'id' => 'enable_slider',
'name' => 'Enable Slider?',
'type' => 'switch',
'style' => 'rounded',
'on_label' => 'Yes',
'off_label' => 'No',
],
```
## Data
This field saves the "on" and "off" status in the database as "1" or "0".
## Template usage
**Conditional check:**
```php
$value = rwmb_meta( 'my_field_id' );
if ( $value ) {
echo 'Checked';
} else {
echo 'Unchecked';
}
```
**Displaying "On/Off":**
```php
rwmb_the_value( 'my_field_id' );
```
# Taxonomy Advanced
import LiteYouTubeEmbed from 'react-lite-youtube-embed';
import 'react-lite-youtube-embed/dist/LiteYouTubeEmbed.css';
import Screenshots from '@site/src/components/Screenshots';
The taxonomy advanced field allows you to select one or multiple taxonomy terms. This field has several settings that can be displayed as a: simple select dropdown, checkbox list, or beautiful select dropdown with select2 library.
If the taxonomy is hierarchical, you can display the field as a select or checkbox tree, e.g. showing children terms when a parent term is selected.
:::warning Taxonomy vs. taxonomy advanced
- Taxonomy field **doesn't store data**. It just sets post terms. Think about it like a replacement of the *Category* or *Tag* meta box of WordPress.
- Taxonomy advanced **stores terms' IDs** and doesn't set post terms.
:::
## Screenshots
## Settings
Besides the [common settings](/field-settings/), this field has the following specific settings, the keys are for use with code:
Name | Key | Description
--- | --- | ---
Taxonomies | `taxonomy` | Taxonomy slug(s). Can be a string (for single taxonomy) or an array (for multiple taxonomies). Required.
Query args | `query_args` | Query arguments for getting taxonomy terms. Uses same arguments as [get_terms()](https://developer.wordpress.org/reference/functions/get_terms/). Optional.
Placeholder | `placeholder` | The placeholder for the select box. The default is "Select a `{taxonomy label}`". Applied only when the field type is a select field.
Add new | `add_new` | Allow users to create a new term when submitting the post (`true` or `false`).
Remove default meta box | `remove_default` | Remove the default WordPress taxonomy meta box. Only works with the classic editor.
Field type | `field_type` | How the terms are displayed? See below.
This field inherits the look and field (and settings) from other fields, depending on the field type, which accepts the following value:
Field type | Description | Settings inherited from
--- | --- | ---
`select` | Simple select dropdown. | [Select](/fields/select/)
`select_advanced` | Beautiful select dropdown using the select2 library. This is the default value. | [Select advanced](/fields/select-advanced/)
`select_tree` | Hierarchical list of select boxes which allows to select multiple items (select/deselect parent item will show/hide child items). Applied only when the taxonomy is hierarchical (like category). | [Select](/fields/select/)
`checkbox_list` | Flatten list of checkboxes which allows to select multiple items. | [Checkbox list](/fields/checkbox-list/)
`checkbox_tree` | Hierarchical list of checkboxes which allows to select multiple items (select/deselect parent item will show/hide child items). Applied only when the taxonomy is hierarchical (like category). | [Checkbox list](/fields/checkbox-list/)
`radio_list` | Flatten list of radio boxes which allows to select only 1 item. | [Radio](/fields/radio/)
This is a sample field settings array when creating this field with code:
```php
[
'name' => 'Taxonomy',
'id' => 'taxonomy',
'type' => 'taxonomy_advanced',
'taxonomy' => 'category',
'field_type' => 'select_advanced',
],
```
## Ajax load
Meta Box uses ajax to increase the performance of the field query. Instead of fetching all terms at once, the plugin now fetches only some terms when the page is loaded, and then it fetches more terms when users scroll down to the list.
See this video for demonstration (made for posts, but works similar for taxonomies, the UI of the MB Builder was from the old version, the new version of MB Builder has a better UI):
:::info
This feature is available only for fields that set the field type to **select advanced**. There are some extra parameters for you to disable or customize.
:::
### Enable/Disable ajax requests
This feature is enabled by default when you set the field type to "select advanced".
If you're using code to create this field, the settings to enable/disable it is `ajax`, which accepts a boolean value (and it's `true` by default):
```php
[
'id' => 'project_cat',
'title' => 'Project Categories',
'type' => 'taxonomy_advanced',
'taxonomy' => 'project_cat',
// highlight-next-line
'ajax' => true,
],
```
Setting this parameter to `false` will disable ajax requests.
### Limit the number of terms for pagination
The number of terms for pagination is set via the `number` parameter in the "Query_args" setting:
```php
[
'id' => 'project_cat',
'title' => 'Project Categories',
'type' => 'taxonomy_advanced',
'taxonomy' => 'project_cat',
'ajax' => true,
'query_args' => [
// highlight-next-line
'number' => 10,
],
],
```
When fetching new terms, the new terms will be appended to the list of options in the dropdown, to make the infinite scroll effect.
:::info Initial load
The number of terms **doesn't affect the initial load** of the field. When the field is loaded, Meta Box **only queries for saved terms** (which is usually not many). So the initial query is very minimal and doesn't cause any performance problems.
:::
### Searching parameters
You probably don't want to perform an ajax request when opening the dropdown at first. You might want to _make ajax requests only when users type something_ and search for that. To do that, you need to set the `minimumInputLength` for the input, as below:
```php
[
'id' => 'project_cat',
'title' => 'Project Categories',
'type' => 'taxonomy_advanced',
'taxonomy' => 'project_cat',
'ajax' => true,
'query_args' => [
'number' => 10,
],
'js_options' => [
// highlight-next-line
'minimumInputLength' => 1,
],
],
```
This parameter sets the minimum number of characters required to start a search. It may be good if you don't want users to make too many ajax requests that could harm your server.
## Data
Unlike the [taxonomy](/fields/taxonomy/) field, this field saves terms' IDs in the database.
If "Multiple" is not set, a single term ID is saved in the database. Otherwise, the field saves multiple term IDs in a single row in the database in the comma-separated strings (e.g. format `1,2,3`).
If the field is cloneable, then the value is stored as a serialized array in a single row in the database.
## Template usage
**Getting selected term object:**
```php
```
**Displaying selected term name:**
```php
name; ?>
```
or simpler:
```php
false] ) ?>
```
**Displaying the selected term with link:**
```php
```
or simpler:
```php
```
**Additional options for `rwmb_the_value()`:**
Using `rwmb_the_value` also has some extra options as following:
```php
false] ) ?>
'view'] ) ?>
'edit'] ) ?>
```
**Displaying multiple selected terms:**
If "Multiple" is set or the field is cloneable, you can loop through the returned values like this:
```php
```
`rwmb_the_value()` automatically output multiple selected terms as an unordered list with links to each term.
## Filters
`rwmb_taxonomy_advanced_choice_label` and `rwmb_{$field_id}_choice_label`
These filters allow developers to change the label of `taxonomy_advanced` fields. The first label applies to all `taxonomy_advanced` fields, and the second one is for a specific field.
Example: If you are using a field called `my_field` and you want to change the label in the select box, use this code:
```php
function my_field_filter( $label, $field, $term ) {
return $label . ' - Custom text';
}
add_filter( 'rwmb_my_field_choice_label', 'my_field_filter', 10, 3 );
```
# Taxonomy
import LiteYouTubeEmbed from 'react-lite-youtube-embed';
import 'react-lite-youtube-embed/dist/LiteYouTubeEmbed.css';
import Screenshots from '@site/src/components/Screenshots';
The taxonomy field allows you to select one or multiple taxonomy terms. This field has several settings that can be displayed as a: simple select dropdown, checkbox list, or beautiful select dropdown with select2 library.
If the taxonomy is hierarchical, you can display the field as a select or checkbox tree, e.g. showing children terms when a parent term is selected.
:::warning Taxonomy vs. taxonomy advanced
- Taxonomy field **doesn't store data**. It just sets post terms. Think about it like a replacement of the *Category* or *Tag* meta box of WordPress.
- Taxonomy advanced **stores terms' IDs** and doesn't set post terms.
:::
## Screenshots
## Settings
Besides the [common settings](/field-settings/), this field has the following specific settings, the keys are for use with code:
Name | Key | Description
--- | --- | ---
Taxonomies | `taxonomy` | Taxonomy slug(s). Can be a string (for single taxonomy) or an array (for multiple taxonomies). Required.
Query args | `query_args` | Query arguments for getting taxonomy terms. Uses same arguments as [get_terms()](https://developer.wordpress.org/reference/functions/get_terms/). Optional.
Placeholder | `placeholder` | The placeholder for the select box. The default is "Select a `{taxonomy label}`". Applied only when the field type is a select field.
Add new | `add_new` | Allow users to create a new term when submitting the post (`true` or `false`).
Remove default meta box | `remove_default` | Remove the default WordPress taxonomy meta box. Only works with the classic editor.
Field type | `field_type` | How the terms are displayed? See below.
This field inherits the look and field (and settings) from other fields, depending on the field type, which accepts the following value:
Field type | Description | Settings inherited from
--- | --- | ---
`select` | Simple select dropdown. | [Select](/fields/select/)
`select_advanced` | Beautiful select dropdown using the select2 library. This is the default value. | [Select advanced](/fields/select-advanced/)
`select_tree` | Hierarchical list of select boxes which allows to select multiple items (select/deselect parent item will show/hide child items). Applied only when the taxonomy is hierarchical (like category). | [Select](/fields/select/)
`checkbox_list` | Flatten list of checkboxes which allows to select multiple items. | [Checkbox list](/fields/checkbox-list/)
`checkbox_tree` | Hierarchical list of checkboxes which allows to select multiple items (select/deselect parent item will show/hide child items). Applied only when the taxonomy is hierarchical (like category). | [Checkbox list](/fields/checkbox-list/)
`radio_list` | Flatten list of radio boxes which allows to select only 1 item. | [Radio](/fields/radio/)
This is a sample field settings array when creating this field with code:
```php
[
'name' => 'Taxonomy',
'id' => 'taxonomy',
'type' => 'taxonomy',
'taxonomy' => 'category',
'field_type' => 'select_advanced',
],
```
## Ajax load
Meta Box uses ajax to increase the performance of the field query. Instead of fetching all terms at once, the plugin now fetches only some terms when the page is loaded, and then it fetches more terms when users scroll down to the list.
See this video for demonstration (made for posts, but works similar for taxonomies, the UI of the MB Builder was from the old version, the new version of MB Builder has a better UI):
:::info
This feature is available only for fields that set the field type to **select advanced**. There are some extra parameters for you to disable or customize.
:::
### Enable/Disable ajax requests
This feature is enabled by default when you set the field type to "select advanced".
If you're using code to create this field, the settings to enable/disable it is `ajax`, which accepts a boolean value (and it's `true` by default):
```php
[
'id' => 'project_cat',
'title' => 'Project Categories',
'type' => 'taxonomy',
'taxonomy' => 'project_cat',
// highlight-next-line
'ajax' => true,
],
```
Setting this parameter to `false` will disable ajax requests.
### Limit the number of terms for pagination
The number of terms for pagination is set via the `number` parameter in the "Query_args" setting:
```php
[
'id' => 'project_cat',
'title' => 'Project Categories',
'type' => 'taxonomy',
'taxonomy' => 'project_cat',
'ajax' => true,
'query_args' => [
// highlight-next-line
'number' => 10,
],
],
```
When fetching new terms, the new terms will be appended to the list of options in the dropdown, to make the infinite scroll effect.
:::info Initial load
The number of terms **doesn't affect the initial load** of the field. When the field is loaded, Meta Box **only queries for saved terms** (which is usually not many). So the initial query is very minimal and doesn't cause any performance problems.
:::
### Searching parameters
You probably don't want to perform an ajax request when opening the dropdown at first. You might want to _make ajax requests only when users type something_ and search for that. To do that, you need to set the `minimumInputLength` for the input, as below:
```php
[
'id' => 'project_cat',
'title' => 'Project Categories',
'type' => 'taxonomy',
'taxonomy' => 'project_cat',
'ajax' => true,
'query_args' => [
'number' => 10,
],
'js_options' => [
// highlight-next-line
'minimumInputLength' => 1,
],
],
```
This parameter sets the minimum number of characters required to start a search. It may be good if you don't want users to make too many ajax requests that could harm your server.
## Data
:::warning No value saved!
This field **does not save any value** in the database. Instead of that, it **sets the taxonomy terms for the current being edited post**. In short, it behaves exactly like the "Category" and "Tags" meta boxes.
:::
The purpose of this field is to replace the default WordPress meta box for taxonomy and offer more options to control how it displays.
For this reason, if you have two taxonomy fields, and select different values for them, after saving, they still show the same value.
:::tip How to save data
If you prefer saving data, check out the [taxonomy advanced](/fields/taxonomy-advanced/) field.
:::
## Template usage
**Getting selected term object:**
```php
```
**Displaying selected term name:**
```php
name; ?>
```
or simpler:
```php
false] ) ?>
```
**Displaying the selected term with link:**
```php
```
or simpler:
```php
```
**Additional options for `rwmb_the_value()`:**
Using `rwmb_the_value` also has some extra options as following:
```php
false] ) ?>
'view'] ) ?>
'edit'] ) ?>
```
**Displaying multiple selected terms:**
If "Multiple" is set, you can loop through the returned values like this:
```php
```
`rwmb_the_value()` automatically output multiple selected terms as an unordered list with links to each user.
## Filters
`rwmb_taxonomy_choice_label` and `rwmb_{$field_id}_choice_label`
These filters allow developers to change the label of `taxonomy` fields. The first label applies to all `taxonomy` fields, and the second one is for a specific field.
Example: If you are using a field called `my_field` and you want to change the label in the select box, use this code:
```php
function my_field_filter( $label, $field, $term ) {
return $label . ' - Custom text';
}
add_filter( 'rwmb_my_field_choice_label', 'my_field_filter', 10, 3 );
```
# Text List
import Screenshots from '@site/src/components/Screenshots';
The text list field creates a list of text inputs.
## Screenshots
## Settings
Besides the [common settings](/field-settings/), this field has the following specific settings, the keys are for use with code:
Name | Key | Description
--- | --- | ---
Inputs | `options`|Array of `'placeholder' => 'label'` for the inputs.
This is a sample field settings array when creating this field with code:
```php
[
'id' => 'text_list',
'name' => 'Text List',
'type' => 'text_list',
'clone' => true,
'options' => [
'John Smith' => 'Name',
'name@domain.com' => 'Email',
],
],
```
## Data
If the field is not cloneable, the data is stored in multiple rows in the database. Each row has the same meta key as the field ID, and the value is the value in the corresponding text input.
If the field is cloneable, then the value is stored as a serialized array of values in a single row in the database.
## Template usage
**Displaying field inputs' values:**
```php
Name:
Email:
```
**Displaying cloneable values:**
```php
Name: Email:
```
**Displaying field values in a table:**
```php
Values
```
which outputs:
HTML:
```html
Name
Email
Name 1
email1@domain.com
Name2
email2@domain.com
```
# Text
import Screenshots from '@site/src/components/Screenshots';
The text field creates a simple text input. You can enter any value or select a value from a predefined list.
:::info Input types
This docs is also used for **URL** and **email** field types as they share the same settings. If you want to have full text editing abilities, checkout the [WYSIWYG](/fields/wysiwyg/) field.
:::
## Screenshots
## Settings
Besides the [common settings](/field-settings/), this field has the following specific settings, the keys are for use with code:
Name | Key | Description
--- | --- | ---
Type | `type` | Allowed values: `text`, `url` or `email`. If the value is `url` or `email`, the field value will be validated accordingly.
Placeholder | `placeholder` | Placeholder for the input. Optional.
Size of the input box | `size` | Size of the input box. Without this setting, the input box is full-width.
Prepend text | `prepend`|Prepend text for the input. The prepended text should be considered as an informative label. It's not saved in the database with the input value.
Append text | `append`|Append text for the input. The appended text should be considered as an informative label. It's not saved in the database with the input value.
Predefined values | `datalist` | Predefined values that users can select from (users still can enter text if they want). If you use code, this parameter has the following sub-parameters - `id`: ID of the div that stores the options. Usually not used and auto-generated as `{$field['id']_list`. Useful if you have several inputs with same datalist. - `options`: Array of predefined values to select from.
This is a sample field settings array when creating this field with code:
```php
[
'name' => 'Text',
'id' => 'text',
'desc' => 'Please enter some text above',
'type' => 'text',
'std' => 'Default text value',
'placeholder' => 'Enter something here',
'datalist' => [
'id' => 'text_datalist',
'options' => [
'What',
'When',
'Where',
'Why',
'Who',
],
],
],
```
:::tip "type" is optional
You can omit the "type" setting. The plugin automatically sets it to "text" if missing.
```php
add_filter( 'rwmb_meta_boxes', function ( $meta_boxes ) {
$meta_boxes[] = [
'title' => 'Event details',
'post_types' => 'event',
'fields' => [
[
'name' => 'Date and time',
'id' => 'datetime',
'type' => 'datetime',
],
// highlight-start
[
'name' => 'Location',
'id' => 'location',
],
// highlight-end
[
'name' => 'Map',
'id' => 'map',
'type' => 'osm',
'address_field' => 'location',
],
],
];
return $meta_boxes;
} );
```
:::
:::tip Quick define a text field
If your text field only need a label, then you can define it with code simply by the label text. In this case, the field id is auto generated from the label:
```php
add_filter( 'rwmb_meta_boxes', function ( $meta_boxes ) {
$meta_boxes[] = [
'title' => 'Event details',
'post_types' => 'event',
'fields' => [
[
'name' => 'Date and time',
'id' => 'datetime',
'type' => 'datetime',
],
// highlight-next-line
'Location', // id is auto-generated to "location"
[
'name' => 'Map',
'id' => 'map',
'type' => 'osm',
'address_field' => 'location',
],
],
];
return $meta_boxes;
} );
```
:::
## Data
This field saves the entered value into the database.
If the field is cloneable, then the value is stored as a serialized array in a single row in the database.
## Template usage
**Displaying the value:**
```php
Entered:
```
**Getting the value:**
```php
Entered:
```
**Displaying cloneable values:**
```php
```
# Textarea
import Screenshots from '@site/src/components/Screenshots';
The textarea field creates a simple textarea (multiline) input. You can use this field for entering a paragraph of text.
## Screenshots
## Settings
Besides the [common settings](/field-settings/), this field has the following specific settings, the keys are for use with code:
Name | Key | Description
--- | --- | ---
Placeholder | `placeholder` | The placeholder text. Optional.
Columns | `cols` | Number of columns. Optional. Default 60.
Rows | `rows` | Number of rows. Optional. Default 4.
## Data
This field saves the entered value into the database.
If the field is cloneable, then the value is stored as a serialized array in a single row in the database.
:::warning
Meta Box **removes all scripts and iframes** from the value. If you want to enter scripts (like Google Analytics) or embed videos, then you need to [disable sanitization](/sanitization/#bypass-the-sanitization).
:::
## Template usage
**Displaying the value:**
```php
About Us
```
**Getting the value:**
```php
About Us
```
**Auto adding paragraphs to the text:**
```php
```
**Parse shortcodes:**
```php
```
**Parse blocks:**
```php
```
**Displaying cloneable values:**
```php
```
# Time
import Screenshots from '@site/src/components/Screenshots';
The time field allows you to select a time via a friendly UI. This field uses jQuery UI time picker libraries.
## Screenshots
## Settings
Besides the [common settings](/field-settings/), this field has the following specific settings, the keys are for use with code:
Name | Key | Description
--- | --- | ---
Size of the input box | `size` | Size of the input box. Optional. Default 10. Without this setting, the input box is full-width.
Inline | `inline` | Whether to display the time picker inline with the input and don't require to click to show the time picker? `true` or `false` (default).
Time picker options | `js_options`| Time picker options. [See here](http://trentrichardson.com/examples/timepicker/).
This is a sample field settings array when creating this field with code:
```php
[
'name' => 'Time picker',
'id' => 'field_id',
'type' => 'time',
'js_options' => [
'stepMinute' => 15,
'controlType' => 'select',
'showButtonPanel' => false,
'oneLine' => true,
],
],
```
## Data
This field saves ther entered time in the database.
If the field is cloneable, then the value is stored as a serialized array in a single row in the database.
## Template usage
**Displaying entered time:**
```php
Entered:
```
or simpler:
```php
Entered:
```
# User
import LiteYouTubeEmbed from 'react-lite-youtube-embed';
import 'react-lite-youtube-embed/dist/LiteYouTubeEmbed.css';
import Screenshots from '@site/src/components/Screenshots';
The user field allows you to select one or multiple users. This field has several settings that can be displayed as a: simple select dropdown, checkbox list, or beautiful select dropdown with select2 library.
## Screenshots
## Settings
Besides the [common settings](/field-settings/), this field has the following specific settings, the keys are for use with code:
Name | Key | Description
--- | --- | ---
Query args | `query_args` | Query arguments for getting users. Uses same arguments as [get_users()](https://developer.wordpress.org/reference/functions/get_users/). Optional.
Placeholder | `placeholder` | The placeholder for the select box. The default is "Select a user". Applied only when the field type is a select field.
Field type | `field_type` | How the users are displayed? See below.
This field inherits the look and field (and settings) from other fields, depending on the field type, which accepts the following value:
Field type | Description | Settings inherited from
--- | --- | ---
`select` | Simple select dropdown. | [Select](/fields/select/)
`select_advanced` | Beautiful select dropdown using the select2 library. This is the default value. | [Select advanced](/fields/select-advanced/)
`select_tree` | Hierarchical list of select boxes which allows to select multiple items (select/deselect parent item will show/hide child items). Applied only when the post type is hierarchical (like pages). | [Select](/fields/select/)
`checkbox_list` | Flatten list of checkboxes which allows to select multiple items. | [Checkbox list](/fields/checkbox-list/)
`checkbox_tree` | Hierarchical list of checkboxes which allows to select multiple items (select/deselect parent item will show/hide child items). Applied only when the post type is hierarchical (like pages). | [Checkbox list](/fields/checkbox-list/)
`radio_list` | Flatten list of radio boxes which allows to select only 1 item. | [Radio](/fields/radio/)
This is a sample field settings array when creating this field with code:
```php
[
'name' => 'User',
'id' => 'user',
'type' => 'user',
'field_type' => 'select_advanced',
'placeholder' => 'Select an author',
],
```
## Ajax load
Meta Box uses ajax to increase the performance of the field query. Instead of fetching all users at once, the plugin now fetches only some users when the page is loaded, and then it fetches more users when users scroll down to the list.
See this video for demonstration (made for posts, but works similar for users, the UI of the MB Builder was from the old version, the new version of MB Builder has a better UI):
:::info
This feature is available only for fields that set the field type to **select advanced**. There are some extra parameters for you to disable or customize.
:::
### Enable/Disable ajax requests
This feature is enabled by default when you set the field type to "select advanced".
If you're using code to create this field, the settings to enable/disable it is `ajax`, which accepts a boolean value (and it's `true` by default):
```php
[
'id' => 'project_author',
'title' => 'Project Author',
'type' => 'user',
// highlight-next-line
'ajax' => true,
],
```
Setting this parameter to `false` will disable ajax requests.
### Limit the number of users for pagination
The number of users for pagination is set via the `number` parameter in the "Query_args" setting:
```php
[
'id' => 'project_author',
'title' => 'Project Author',
'type' => 'user',
'ajax' => true,
'query_args' => [
// highlight-next-line
'number' => 10,
],
],
```
When fetching new users, the new users will be appended to the list of options in the dropdown, to make the infinite scroll effect.
:::info Initial load
The number of users **doesn't affect the initial load** of the field. When the field is loaded, Meta Box **only queries for saved users** (which is usually not many). So the initial query is very minimal and doesn't cause any performance problems.
:::
### Searching parameters
You probably don't want to perform an ajax request when opening the dropdown at first. You might want to _make ajax requests only when users type something_ and search for that. To do that, you need to set the `minimumInputLengthfor` the input, as below:
```php
[
'id' => 'project_author',
'title' => 'Project Author',
'type' => 'user',
'ajax' => true,
'query_args' => [
'number' => 10,
],
'js_options' => [
// highlight-next-line
'minimumInputLength' => 1,
],
],
```
This parameter sets the minimum number of characters required to start a search. It may be good if you don't want users to make too many ajax requests that could harm your server.
## Data
This field saves user ID(s) in the database.
If "Multiple" is not set, a single user ID is saved in the database. Otherwise, the field saves multiple user IDs in the database, where each user ID is stored in a single row in the database with the same meta key (similar to what `add_post_meta` does with the last parameter `false`).
If the field is cloneable, then the value is stored as a serialized array in a single row in the database.
## Template usage
**Getting selected user ID:**
```php
Selected user ID:
```
**Getting selected user object:**
```php
```
**Displaying selected user info:**
```php
Display name: display_name ?>
Email: user_email ?>
```
or simpler:
```php
Display name: false] ) ?>
Email: 'user_email', 'link' => false] ) ?>
```
**Additional options for `rwmb_the_value()`:**
Using `rwmb_the_value` also has some extra options as following:
```php
false] ) ?>
'view'] ) ?>
'edit'] ) ?>
'user_email'] ) ?>
```
Parameter | Description
--- | ---
`link` | Which type of link to display: `false` - no link, `view` - user posts page, `edit` - edit user page.
`display_field` | The user field to display. Default is `display_name`.
**Displaying multiple selected users:**
If the "Multiple" is set or the field is cloneable, you can loop through the returned values like this:
```php
Speakers
display_name ?>
```
of simpler:
```php
Speakers
false] ); ?>
```
`rwmb_the_value()` automatically output multiple selected users as an unordered list with links to each user.
## Filters
`rwmb_user_choice_label` and `rwmb_{$field_id}_choice_label`
These filters allow developers to change the label of `user` fields. The first label applies to all `user` fields and the second one is for a specific field.
Example: If you are using a field called `some_user` and you want to change the label in the select box to user `first_name` instead of the default `display_name`:
```php
function some_user_filter( $label, $field, $user ) {
return $user->first_name ;
}
add_filter( 'rwmb_some_user_choice_label', 'some_user_filter', 10, 3 );
```
# Video
import Screenshots from '@site/src/components/Screenshots';
The video field uses the WordPress media popup for selecting / uploading videos.
## Screenshots
## Settings
Besides the [common settings](/field-settings/), this field has the following specific settings, the keys are for use with code:
Name | Key | Description
--- | --- | ---
Max number of files | `max_file_uploads` | Max number of uploaded files. Optional.
Force delete | `force_delete` | Whether or not delete the files from Media Library when deleting them from post meta. `true` or `false` (default). Optional. Note: it might affect other posts if you use the same file for multiple posts.
Show status | `max_status` | Display how many files uploaded/remaining. Applied only when "Max number of files" is defined. `true` (default) or `false`. Optional.
This is a sample field settings array when creating this field with code:
```php
[
'name' => 'Video',
'id' => 'field_id',
'type' => 'video',
'max_file_uploads' => 3,
'force_delete' => false,
'max_status' => true,
],
```
## Data
This field saves multiple attachment IDs in the database. Each value (attachment ID) is stored in a single row in the database with the same meta key (similar to what `add_post_meta` does with the last parameter `false`).
## Template usage
**Displaying videos with HTML5 player:**
```php
Uploaded videos
```
`rwmb_meta()` returns an array of videos, each video has the following information:
```php
[
'ID' => 123,
'src' => 'https://example.com/wp-content/uploads/intro.mp4',
'title' => 'Introduction',
'type' => 'video',
'caption' => 'Video caption',
'description' => 'Video description',
// Array of video ID3 meta. See https://developer.wordpress.org/reference/functions/wp_get_attachment_id3_keys/
'meta' => [],
// Video dimension.
'dimensions' => [
'width' => 640,
'height' => 360,
],
// Featured image: full size
'image' => [
'src' => 'https://example.com/wp-content/uploads/full.jpg',
'width' => 1024,
'height' => 500,
],
// Featured image: thumbnail
'thumb' => [
'src' => 'https://example.com/wp-content/uploads/full-150x150.jpg',
'width' => 150,
'height' => 150',
],
];
```
**Displaying only one video:**
```php
1] ) ?>
