Fields

Intro

It is in the name - fields are the core of Ultimate Fields. The plugin comes with up to 30 field types out of the box and they allow you to do everything that you need.

When you create fields, you need to add them to a container, which is the hub that will display them in the right place. Please make sure to read the Container Settings article in order to understand how to create and set containers up.

Fields can be created through:

• The Administration Interface allows you to create fields visually in the back-end dashboard.
• The PHP API lets you directly access the PHP classes and objects of the plugin to quickly create and setup fields.

All settings, described below will be applicable for both methods.

General settings

Every field that you create must have some or all of the following settings:

Setting	Description	PHP Method
Name	The name of the field, similarly to the name attribute of an HTML field is the identifier of the field, which will be used to save, load and display the value of the field. Additionally, this name will be used for conditional logic, postMessage fields (in the customizer), administration columns and more.	None
Type	The type of a field not only indicates what type of input to expect, but actually points to a class, which Ultimate Fields will use for that field. This way the setting fields (in the UI) and the available methods (in PHP) differ from one field type to another.	None
Label	This is the label of the field, which is a general indicator of its purpose.	set_label()
Default value	The default value of a field will be presented to editors when they edit an item (or settings) for the first time. Also, when you retrieve the values of fields through functions like get_value and the_value, you will get the default values of fields even if they have never been saved.	set_default_value()
Description	Descriptions extend the function of the label by allowing you to provide longer texts, which describe the purpose of a field. Based on container settings, descriptions might appear both below the label and below the fields' inputs.	set_description()
Hide label	The label of a field may be hidden altogether through this setting. It is useful to hide the label of a field when it is the only field in a container or when the input of a field fully indicates its purpose, like a checkbox.	hide_label()
Width	In Grid layout you can adjust the width of a fields in order to show multiple fields on the same row, next to each-other.	set_width()
HTML Attributes	You can add all types of HTML attributes to the root element of a field. Please keep in mind that those settings will be applied to the whole field element, rather than its input.	set_attr()

Creating fields through the interface

Please start by reading the Administration Interface article and specifically its Fields section.

Once you click the +Add field button to create a new field or you click an existing field, which you want to edit, you will be presented with a popup, looking like this:

Entering a label in the first field will automatically generate the value of the field name. This is just a suggestion, so feel free to change the name of the field.

Next you have to select a field type. Based on the field type, many of the other fields in the popup will change in order to allow you to fine-tune the field.

The rest of the settings are either described:

• in General Settings above
• in Conditional Logic below
• in Validation below
• in Output Settings below
• or in the article for the particular field type

Once you are done, click the blue "Add Field" or "Save Field" button and set the rest of the container up.

Creating fields through PHP

Before you proceed with this article, it is important for you to understand:

• How to use PHP namespaces
• The uf.init action
• How to create a container

If are not familiar with one or more of those points, please read Using the PHP API.

Fields are created through the static create method of the Ultimate_Fields\Field class:

Field::create( $type, $name, $label = null )

The method expects three parameters:

1. $type must be a string, which represents the field type. This string will be uppercased and appended to Ultimate_Fields\Field\ in order to generate the full class name. For example, "text" will be transformed to Ultimate_Fields\Field\Text.
2. $name is the name of the field, which you will be using when retrieving the value of the field.
3. $label is the label, which will be displayed next to the field. It is an optional parameter, as by default Ultimate Fields will auto-generate it based on the field name.

It also returns the new instance of the field, ready for method chaining. All other methods, described here may be directly executed on this instance.

Here is an example, which includes creating a field and adding the field and a location to a container.

<?php
use Ultimate_Fields\Container;
use Ultimate_Fields\Field;

Container::create( 'post_data' )
	->add_location( 'post_type', 'post' )
	->add_fields(array(
		Field::create( 'text', 'subtitle', __( 'Subtitle' ) )
			->set_default_value( '(no subtitle)' )
	));

In this example we are creating a text field, named subtitle with "Subtitle" as a label. Once the field is created, we immediately use the new instance and set a default value by calling the set_default_value method.

PHP Methods

Here are some generic methods of all fields. Please keep in mind that all of those methods will return an instance of the field, meaning that you can daisy-chain them, for example:

Field::create( 'text', 'subtitle' )
	->set_default_value( '(no title)' )
	->set_description( 'The subtitle will only be displayed on the post page.' )
	->set_width( 50 )

Default value

set_default_value( mixed $value )

The value should be in a format, compatible with the field. Giving an array as a default value for a text field will not work.

Description

set_description( string $description )

The description will have paragraphs automatically added to it, but also supports custom HTML.

Hiding a field's label

hide_label()

Hides the label of the field for when the field itself is descriptive enough.

Width

set_width( float $width )

Changes the width of the field in a grid layout. $width should be a numeric percentage.

HTML Attributes

set_attr( $name, $value = null )

Adds an attribute to the field wrapper. You can either give a $name and a $value to the attribute or provide an array for $name:

$field->set_attr( 'style', 'background: purple;' );

// or

$field->set_attr(array(
	'style'         => 'background: red',
	'data-selected' => 5
));

Validation

Validation in Ultimate Fields is very flexible. You define both whether a field is required, as well as a validation rule for it. Then validation works both in the browser and server-side.

It is important to keep in mind that there is a difference between a required field and a field with a validation rule:

• You can make a field required without specifying a validation rule. In this case the value of the field will have to be comparable to a boolean true. Use this if you need a value, but a specific format is not required.
• You can set the validation rule of a field without making it required. In this case the value of the field will only be validated when it is not a boolean false. For example, you can use a regular expression to validate an email, but only do it once something has been entered.
• Of course, you can make a field both required and use a specific validation rule.

Internally, validation values are always handled as regular expressions. Both in the UI and in PHP you should enter full regular expressions, which include terminators and modifiers. This means that you should use something like /^(?P<first_name>[^\s]+) (?P<last_name>[^\s]+)$/i instead of just (?P<first_name>[^\s]+) (?P<last_name>[^\s]+). Because of this mechanism, fields which work with non-scalar values (like a repeater) do not support custom validation rules, but you can still make them required.

In the UI, if you select "An explicitly defined value" as "Validation Rule", the value will be automatically transformed to a regular expression.

PHP Methods

required( $regex = true, $validation_message = '' )

You can use the required method without arguments to just make the field required, but it allows you to immediately set a validation rule and a message.

You can also use set_validation_rule to change the used validation rule and set_validation_message to change what users see when there are issues with a field.

set_validation_message( $message )
set_validation_rule( $regex )

Examples:

<?php
use Ultimate_Fields\Container;
use Ultimate_Fields\Field;

Container::create( 'required-fields' )
	->add_fields(array(
		Field::create( 'text', 'basic_field' ),
		Field::create( 'text', 'required_field' )
			->required()
			->set_validation_message( 'Please enter a value!' ),
		Field::create( 'text', 'optional_email_field' )
			->set_validation_rule( Field\Text::VALIDATION_RULE_EMAIL )
			->set_description( 'Enter an email here if you have one (Optional)' ),
		Field::create( 'text', 'price' )
			->required( '/^\d+\.\d{2}$/', 'Please enter a floating point number.' )
	));

Ultimate Fields comes with a single validation rule, which is for email addresses. You can access it as Ultimate_Fields\Field\Text::VALIDATION_RULE_EMAIL.

Sanitization

When Ultimate Fields saves values into the database, most of them are sanitized in order to ensure a proper format and to avoid unvalidated input. This does not apply to the values of the following fields:

• Text
• Textarea
• WYSIWYG
• Map - Latitude, longitude, zoom and most sub-fields are sanitized, but not the address, entered in the search bar.

The reason is that those fields accept generic input, which makes it hard to know what to and not to expect.

Manual sanitization

In order to sanitize values manually, you can set a validation rule and/or set a sanitization callback. Validation rules are the better option, as they will ensure that the value is formatted correctly from the beginning.

When you are not expecting a particular format, you can also use the set_sanitization_callback method of a field.

set_sanitization_callback( $callback )

For example:

Field::create( 'text', 'name' )
	->set_sanitization_callback( 'strip_tags' )

Escaping

Even though (and if) sanitization is done when saving a field, values must always be escaped before being displayed. There are various functions in Ultimate Fields, which give you access to fields' data.

• All functions, which include "the" in their name will escape values before displaying/returning them. Those include the_value, get_the_value, the_sub_value and get_the_sub_value.
• All functions, which do not include "the" in their name will not escape values. Those include get_value and get_sub_value.

If you are using a "the" function, you can rely on Ultimate Fields for escaping the values of most fields. For example:

• If you are displaying the context of a text field, Ultimate FIelds will use the esc_html function.
• If you are using a multi-line text field (Textarea and WYSIWYG), Ultimate Fields will use wp_kses_post.
• If you are displaying a map through the Map field, all attributes will be escaped before being included in the output.

Conditional logic

Conditional Logic allows you to hide and show fields based on the values of other fields in the same context.

Because of the complexity of the topic, it has been isolated in the Conditional Logic article.

Output settings

Output settings only matter when you are using a function like the_value. If you are using a get_value function, you will get the pure (raw) value of a field.

Some fields may have various output settings. Those vary from field type to field type and will be explained separately for each field type in its article.