Container Settings

Overview

Containers in Ultimate Fields are used for grouping fields together and showing them in various locations through the WordPress back- & front-end. An important thing to keep in mind is that containers can be both top-level elements, as well as nested items. Here are some examples of containers:

1. Field groups: All containers, which you see in the "Ultimate Fields" section in the back-end are top-level field groups.
2. Repeater and Layout groups are also field containers. This means that many of the settings on this page (ex. description, layout, description positions and etc.) are not only applicable to top-level containers, but also to these groups.
3. Even something as simple as the Complex field uses a container to manage the fields inside itself.

In this article you will learn how to set containers up and we will review available settings.

Container settings in the UI

If you are using the administration interface, you can start by navigating to the "Ultimate Fields" section and clicking "Add new" or some existing container. You will see the container settings in the last box on the screen, called "Container".

Container settings in PHP

If you prefer coding your fields and using the PHP API of Ultimate Fields, please make sure to read the Using the PHP API article first.

In that article you can see that containers are always created through the static create method of Ultimate_Fields\Container. The definition of that method looks like this:

Parameters

public static function create( $id, $args = array() )

As you can see, the method expects two parameters:

1. $id: This is a required parameter and should contain a unique ID, in order to avoid conflicts with other containers.
2. $args (Optional): The second parameter for the method can be an array and may contain any setting, as long as the container has a setter, whose name looks like set_{$setting_name}.

Arguments vs. Setters

If you want to modify a setting of a container, you can both use the proper method for it (called setter) or include the setting in the $args array.

Container::create( 'post-data', array(
    'title' => __( 'Post Data' )
));

// or

Container::create( 'post-data )
    ->set_title( __( 'Post Data' ) );

The examples below will only use the setter (like set_title above), but keep in mind that you can always use an argument in the $args array. The key for the argument will not be explicitly documented for every setting, but the general principle is that in order to get it, you need to remove the verb (ex. set_) from a method name.

Method name	Argument	Note
set_id	id	-
set_title	title	-
set_description	description	-
set_description_position	description_position	-
add_location	locations	This argument expects multiple locations (an array).
add_fields	fields	-
set_layout	layout	-
set_style	style	-
require_role	roles	-

Method chaining

For the following examples, let's assume that we will be working with a variable named $container, defined like this:

$container = Container::create( 'demo-container' );

Please keep in mind that every set_* method will return the instance of the container, ready to chain with any another method, like this:

$container = Container::create( 'post-data' )
    ->set_title( __( 'Post Data' ) )
    ->set_layout( 'grid' )
    ->add_fields(array(
        /* ... */
    ));

That's why in the following examples, we will simply use the variable $container.

Identifiers

When using the administration interface, you should not worry about container ids - they will be handled automatically for you.

If you are using the PHP API, you can use the set_id and get_id methods:

$container->set_id( 'container_hPqeBg1' );
echo $container->get_id(); // Will return "container_hPqeBg1"

Important: Container identifiers are passed to the container during initialization and there are very few cases where it would make sense for you to manually alter them later. If you decide to do so, make sure to change the ID immediately after the container is created. If you do it later, it might cause unpredictable instabilities.

Title

The title of the container will be displayed in various places. For containers, which are displayed as normal meta boxes, the title will be used for the title of the metabox. For the shortcode location, the title of the container will be displayed as the shortcode name in the media popup navigation and etc.

If you are using the administration interface, the title of the container is entered in the beginning of the container editing screen.

When you are generating containers with PHP, the title is generated based on the ID of the container, converting special symbols (underscores, dashes and etc.) to spaces and upper-casing the rest of words in the ID. This behavior is useful for small projects where English is the main language. It is not suitable for distributable plugins and themes, because for them you need to use localisation with a proper textdomain.

The methods that let you manipulate the title are called set_title and get_title. set_title receives a single parameter, which is the new title:

$container->set_title( __( 'Additional post settings', 'my-textdomain' ) );
$container->get_title(); // Returns "Additional post settings"

Description

Container descriptions are instructions for your users, displayed in the beginning of a container.

Those descriptions can be set through the set_description method and retrieved through get_description:

$description = __( 'Descriptions appear in the beginning of a container, even before its tabs, just like this.' );
$container->set_description( $description );

Layout

Ultimate Fields supports two layouts, which you can choose for a container.

Rows lets each field occupy an entire row. In this layout, the label of the field is displayed on its left side, resulting in a table-like layout where there is a column with labels and one with fields. In this layout mode, field widths are ignored.

Grid makes fields more compact by moving their labels on top of the field. Because of the amount of horizontal space saved this way, fields can have different widths, resulting in a grid-like layout.

Keep in mind that some locations, like widgets, don't have enough physical space, which means the Grid layout will be enforced.

The manipulation of layouts through the PHP API is done through the following methods:

• set_layout( $layout ): The supported values of the parameter are "grid" and "rows".
• get_layout() returns the current layout of the container.
• grid_layout() is a shortcut for switching to grid.

Example:

$container->set_layout( 'grid' );

Style

Containers have two supported styles:

1. Boxed: Displays the fields of the container within a meta box. This is the default style.
2. Seamless: Displays the fields directly, without the usage of a box around them.

Those styles are only applicable when a container is displayed directly in the body of the WordPress back-end. The style will be ignored for the following locations, which have their own, specific styles:

• Widget
• Shortcode
• Menu Item
• Attachment
• Customizer

The PHP API exposes the methods set_style( $style ) and get_layout() at your disposal. The only possible parameters for the $style parameter are "seamless" and "boxed".

$container->set_style( 'seamless' );

Description positioning

Field descriptions are used to explain the purpose of a field to the user and are explained in the Fields chapter.

By default the description is displayed right after the input of the field, but you can change that through the set_description_position( $position ) method:

$container->set_description_position( 'label' );
echo $container->get_description(); // returns "label"

The vailable options are:

• After the label ("label"): The description will be displayed beneath the label of the field.
• After the input ("input"): The description will be dispalyed beneath the input of the field.

When combined with the two layout modes, description positions can let you perfectly curate the appearance of your fields.

Roles & capabilities

By default Ultimate Fields does not introduce any additional restrictions to roles and capabilities. Instead, it's defaulting to the normal WordPress access control for every location. This means that:

• If a user can edit a post, they can also see all containers, associated with that post through the Post Type location.
• If a user can edit widgets, they can also see all containers, associated with widgets.
• If a user can use the customizer, they can see all containers, which are displayed in the customizer.

And so on. The only Ultimate Fields location, which creates an actual new location in the back-end is the options page. By default, it requires the manage_options capability.

If you need to add additional requirements, you can use the require_role( $role ) and require_capability( $capability ) methods of the container. This will make sure that users with different roles (when using require_role) and users that don't have a certain capability (when using require_capability) don't have access to the container.

Sample usage:

$container->require_role( 'editor' );
$container->require_capability( 'publish_posts' );

Both methods accept both a single string parameter or an array of strings, when multiple options are necessary.