Layout

Purpose

The Layout field builds on top of the Repeater field and adds the concept of columns. By doing so the field allows you to create groups of sub-fields, which can be used to define a flexible-column layout.

All of the groups in the field are added to rows, which have columns. You can either use the default amount of 12 columns or customize it. Afterwards, you can set the minimum and maximum number of columns for each block.

Settings

The following settings apply to the whole field. Please scroll down to Group Settings to learn how to setup individual groups.

Columns

To change the amount of available columns you can use the "Columns" setting in the interface or the set_columns method.

Field::create( 'layout', 'content_blocks' )
	->set_columns( 6 );

This amount will also work as a limit for the groups in the field. Even when a group has a maximum amount of 20 columns, if the field uses 6 columns, the group will be limited to 6 columns.

Placeholder Text

You can adjust the "Drag an item here to create a new entry." text, which is displayed in empty rows.

In the interface, please use the "Placeholder Text" field. If you leave it empty, the default string displayed above will be used.

In PHP you can use the set_placeholder_text( $text ) method:

Field::create( 'layout', 'content_blocks' )->set_placeholder_text( 'Drag a block here to create a new entry' );

Background Color

You can change the background color of the layout field.

This setting works well when you need to visually separate different levels of nested fields. Use the set_background_color method.

$field->set_background_color( '#008B8B' )

Group Settings

Groups are added to a layout field through the add_group method. It accepts either:

• id and args parameters. In this case the method will create a new group based on the parameters.
• A Ultimate_Fields\Container\Layout_Group object - this would be a group, which has already been initialised.

As the class name suggests, layout groups are containers. Just like with normal containers, you can use both arguments and setters. To read more about this, please read the Arguments vs. Setters section of the Container Settings article.

Groups support the same arguments and setters as standard containers, except for set_layout and add_location. Additionally, you can use the following options:

Method name	Argument
set_min_width	min_width
set_max_width	max_width
set_title_background	title_background
set_title_color	title_color
set_border_color	border_color
set_icon	icon
set_title_template	title_template

All examples for the methods below will use methods, but keep in mind that you can use them as arguments by just removing the set_ prefix from the method name.

The following two examples are equivalent:

use Ultimate_Fields\Container;
use Ultimate_Fields\Container\Layout_Group;
use Ultimate_Fields\Field;

// Preparation
$layout_field = Field::create( 'layout', 'example_layout_field' );
Container::create( 'layout_example' )
	->add_location( 'options' )
	->add_fields(array(
		$layout_field
	));

// Use arguments
$layout_field->add_group( 'image', array(
	'title'     => __( 'Image' ),
    'min_width' => 6,
    'max_width' => 12,
	'icon'      => 'dashicons dashicons-format-image',
    'fields'    => array(
        Field::create( 'image', 'image' )
    )
));

// Create manually
$group = Layout_Group::create( 'image' )
    ->set_title( __( 'Image' ) )
    ->set_icon( 'dashicons dashicons-format-image' )
    ->set_min_width( 6 )
    ->set_max_width( 12 )
	->add_fields(array(
		Field::create( 'image', 'image' )
	));

$layout_field->add_group( $group );

Colors

You can adjust the folowing colors of each group:

• Title Background
• Title Color
• Border Color

In PHP all methods for colors expect a single parameter - a hexadecimal color string.

Examples:

$layout_group->set_title_background( '#ff0000' );
$layout_group->set_title_color( '#fff' );
$layout_group->set_border_color( '#000' );

Icon

You can change the icon, which appears next to the group title when the group is being used. This icon will not appear in the chooser.

Because of the fact that Ultimate Fields loads styles danymically only when a field is displayed, there is no possibility to control whether an icon font set should be loaded or not. Therefore, the layout field only supports Dashicons icons.

In PHP you can use the set_icon method or the icon argument:

$layout_group->set_icon( 'dashicons-format-image' );

Title Template

You can set a custom template for the title of a group. This can be done by using a template, compatible with Underscore.js.

$group = Layout_Group::create( 'peron' )
    ->add_fields(array(
        Field::create( 'text', 'first_name' ),
        Field::create( 'text', 'last_name' )
    ))
    ->set_title_template( '<%= first_name %> <%= first_name %>' );

Within the template, you can use all avialble field names as local variables. In this example, we are using the first and last name in order to generate a full name, which will be displayed in the title-bar of the group even when its popup is closed.

Usage

The article Using field values explains how to use the values of standard fields. Even though the Layout is also a field, its value consists of the values of its sub-fields, which require a slightly different approach. Before we examine each of those functions individually, let's take a look at an example:

<?php while( have_layout_rows( 'content_blocks' ) ): the_layout_row() ?>
<div class="row">

	<?php while( have_groups( 'content_blocks' ) ): the_group() ?>
	<div class="block block-<?php the_group_type() ?> width-<?php the_group_width() ?>">
	    
	    <?php if( 'image' == get_group_type() ): ?>
	        <?php the_sub_value( 'image' ) ?>
	    <?php else if( 'text' == get_group_type() ): ?>
	        <?php if( get_sub_value( 'title' ) ): ?>
	        <h3><?php the_sub_value( 'title' ) ?></h3>
	        <?php endif; ?>

	        <?php the_sub_value( 'text' ) ?>
	    <?php endif ?>

	</div>
	<?php endwhile ?>

<?php endwhile ?>
</div>

As you can see, the way to use Layout values looks very similar to using the values of a Repeater field. It is also similar to the WordPress loop: There is a while loop with a have_groups() function and a call to the_group during every iteration.

When you are iterating groups, it is important that you use the same parameters for have_layout_rows and have_groups. This will ensure that both loops are working with the same field. Both of those functions require the same parameters that are used for get_value, the_value and etc: $name and $type.

Once you are inside the loop you can use two additional groups of functions:

• Group functions: get_group_type will return the ID of the current group, while the_group_type will display it. The same applies to get_group_width and the_group_width(), but they are used to retrieve the amount columns for the current group.
• Value functions: Those functions display and return the sub-values from the current group. They must always be wrapped by the have_groups and have_layout_rows loop. All of those functions expect a single parameter, which is the name of the sub-field.
  • get_sub_value returns the raw sub-value, like get_value.
  • get_the_sub_value return a processed sub-value, like get_the_value.
  • the_sub_value displays a processed sub-value, like the_value.