Fields are the building block of every container.
New field are created using the
Field::make($type, $name, $label=null), where:
The type of the field. This parameter should be valid class name of a field. For example
text will create field of class
Name of the field. Used as a key when stored in the database and for you to retrieve its value. Please note, that all fields in a Custom Field Container have their names automatically prefixed with an underscore (e.g.
_bgcolor). For more information why, see here.
The label of the field is displayed in the back-end only, where the container is visible. When the parameter is omitted it is automatically derived from the
If this parameter is omitted, and the
$name starts with
Crb part will not be displayed in the generated label.
The factory greatly simplifies the field creation process, since it returns the field object itself and you don’t need to assign it to a variable. The fields API supports method chaining (as seen in the example below).
// Create image field with name "customer_photo" and label "Photo" Field::make('image', 'crb_customer_photo', 'Photo') // Here the title is automatically set to "Custom Sidebar" Field::make('choose_sidebar', 'crb_custom_sidebar') // Method chaining Field::make('select', 'crb_color') ->add_options(array('red', 'blue', 'green')) ->help_text('Pick a color')
All field types originate from a single class named
Field and inherit the following basic features:
You can assign a default value for each field in every container. The default value is used when there is currently no value for the particular field in the database. This is the case for example, when you add a new post, or you add a new theme options field to existing container.
To assign a default value, you use:
You can mark any field as required, in which case the user will need to fill it out before submitting. To set a field as required, you use:
Help text is used as a hint to the user, who will use the field. It is usually rendered under the field and contains more information about what it should contain – requirements, examples, links, etc. HTML tags are allowed.
You add help text using:
You can set the width to fields that are next to each other and they will align on one row. To set the field width %, use:
NB: This feature does nothing in term meta container due to the table layout used by WordPress term editing screen.
Custom field classes can be added using the
add_class() method, for example:
You can apply conditional logic to a field, using
set_conditional_logic($rules), to show or hide it based on other field(s) in the same container. The syntax is similar to
The conditional rules are passed in a two-dimensional array and each rule can have the following arguments as
||The field name to which the rule is applied. The name should be the same as defined in the container.||
||The value of the field. It can be an array only when compare is IN or NOT IN.||
||Operator to test. Possible values are: =, <, >, <=, >=, IN, NOT IN.||
You can optionally pass the
relation key and set it to either
AND (default) or
OR. It defines the relation, when there is more than one rule.
Field::make('select', 'crb_show_socials', 'Show Socials') ->add_options(array( 'yes' => 'Yes', 'no' => 'No', )), Field::make('text', 'crb_facebook', 'Facebook URL') ->set_conditional_logic(array( 'relation' => 'AND', // Optional, defaults to "AND" array( 'field' => 'crb_show_socials', 'value' => 'yes', // Optional, defaults to "". Should be an array if "IN" or "NOT IN" operators are used. 'compare' => '=', // Optional, defaults to "=". Available operators: =, <, >, <=, >=, IN, NOT IN ) )),