Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Conditional Logic allows you to hide and show fields based on the values of other fields in the same context. For example, you may want to only show the "Background Image" field when the "Use background" checkbox has been checked.
When working with conditional logic, you will work with:
- Rules: A rule represents a single logical connection.
- Groups: A group represents multiple rules.
The relationship between the rules in a group is "AND", while the relationship between separate groups is "OR". This means that in order for a field to be displayed, at least one group must have all of its rules matched.
All of these rules and groups and rules are added to individual fields.
Although you can use logic with a single checkbox, in order to understand how it works, we need to have an elaborate example.
Imagine that you are creating a vehicle catalog, with vehicles being a custom post type. Each vehicle would include those fields:
- Type is a radio, which has "New" and "Used" as options.
- Mileage is a number field, which is only shown when a vehicle has been marked as "used".
- Production year is another number field, which is only shown when a vehicle has been marked as "used".
- Insurance price would let editors enter an optional monthly insurance price. This field should only be visible for new cars and used cars, which have less than 10.000 miles and are 5 years old or newer.
In this case we have:
- two simple rules for "Mileage" and "Production Year". Both of these fields are only shown for used vehicles.
- two groups of rules for the "Insurance Price" field, which work independently:
- The first group requires a car to be new.
- The second group requires a car to be both newer than 5 years and to have less than 10k miles.
This example will be used to demonstrate both the usage in the interface, as well as in PHP.
Usage in the interface
All settings for conditional logic are located in the "Validation & Logic" tab when editing a field.
In order to enable conditional logic for the field, start by enabling the "Use conditional logic" checkbox. When you do so, you will see a new field, called "Conditional Logic". This is the place where you can define all needed rules.
Click the "+ Add Group" and you will be presented with a new group, which contains a single rule by default. You can add more rules and edit them. All options will change based on the type of the source field.
Usage in PHP
Conditional logic in PHP can be accessed by using the
add_dependency( $field, $value = null, $compare = null, $group = 0 ) add_dependency_group( $group = null )
add_dependency does is to add a new rule to a group of rules. If there is no group specified when calling the method, it will add the rule to the last existing group. If there are no existing groups, the method will add a rule to the last one.
add_dependency_group adds a new group to the field. If you do not specify a group (an instance of
Ultimate_Fields\Dependency\Group), an empty group will be added to the field. In both cases, calling
add_dependency afterwards will add the new rules to this group.
If you call
add_dependency_group without a specific group and do not add any rules to the field afterwards, the group will be ignored.
fieldmust either be an
Ultimate_Fields\Fieldinstance or simply the name of a field.
valueis a value to compare against. The type of this parameter varies based on the comparator.
compareis a string, which defines which operator to use.
||Equals||Same as the field|
||Equal||Same as the field|
||Does not equal||Same as the field|
||Greater than or equal to||Numeric|
||Lesser than or equal to||Numeric|
||Is not null when converted to a boolean||-|
||Is null when converted to a boolean||-|
||In this list||array|
||Not in this list||array|
||The value is an array and contains the operand||mixed|
||Does not contain||mixed|
||Contains (for repeater groups)||string, the type of the group.|
||Does not contain (for repeater groups)||string, the type of the group.|
An important note here is that if you are using a mathematical comparator, arrays will be converted to their count. This means that
[ 'intro', 'gallery' ] will be seen by the conditional logic simply as
<?php $fields = array( // Show a field based on a checkbox Field::create( 'checkbox', 'show_background_image' ), Field::create( 'image', 'background_image' ) ->add_dependency( 'show_background_image' ), // Show a field based on a specific value Field::create( 'select', 'shipping_method' ) ->add_options(array( 'store_pickup' => 'Store Pickup', 'post' => 'Post shipping', )), Field::create( 'select', 'pickup_store' ) ->add_dependency( 'shipping_method', 'post' ) ->add_options(array( 'store_a' => 'Store A', 'store_b' => 'Store B' )), // Show a field only when there are more than 3 images Field::create( 'gallery', 'images' ), Field::create( 'checkbox', 'enable_overlay' ) ->add_dependency( 'images', 3, '>' ), // Use a relational comparator Field::create( 'multiselect', 'modules' ) ->add_options(array( 'intro', 'gallery' )), Field::create( 'textarea', 'intro_text' ) ->add_dependency( 'modules', 'intro', 'CONTAINS' ), // Check if a specific group has been added to a repeater Field::create( 'repeater', 'content_blocks' ) ->add_group( 'text', array( 'fields' => array( Field::create( 'text', 'title' ), Field::create( 'textarea', 'text' ) ) )) ->add_group( 'gallery', array( 'fields' => array( Field::create( 'gallery', 'images' ) ) )), Field::create( 'select', 'gallery_type' ) ->add_dependency( 'content_blocks', 'gallery', 'CONTAINS_GROUP' ) ->add_options(array( 'grid' => 'Grid', 'slider' => 'Slider' )) );
This method allows you to add multiple groups of rules to a field. Once you call it, the field will switch to a new group for all following
Here is how the example with vehicles would look like:
$fields = array( Field::create( 'select', 'car_type' ) ->add_options(array( 'new' => 'New Vehicle', 'used' => 'User Vehicle', )), Field::crate( 'number', 'mileage' ) ->add_dependency( 'car_type', 'used' ), Field::create( 'number', 'production_year' ) ->add_dependency( 'car_type', 'used' ), Field::create( 'number', 'insurance_price' ) ->add_dependency( 'car_type', 'new' ) ->add_dependency_group() ->add_dependency( 'car_type', 'used' ) ->add_dependency( 'mileage', 10000, '<' ) ->add_dependency( 'production_year', date( 'Y' ) - 5, '>=' ) );
As you can see, initially we work with the default group of rules for the fields, but we create a new one by calling
add_dependency_group. This way, the first rule is contained in a single group, while next three are separated.
Because groups have a boolean
OR relationship and fields inside them have a boolean
AND, the insurance field will be only shown based on the matches in the first rule
OR all rules in the second group.
If this logic was written as a PHP condition with every field having its own variable, it would look like this:
$insurance = ( ( 'new' == $type ) || ( 'used' == $type && $mileage < 10000 && $production_year >= ( date( 'Y' ) - 5 ) ) );
Accessing parent levels
If you need to access a value, which is not in the direct context of the current field, you can prepend
'../' to the first parameter of
add_dependency to get one level up.
<?php $fields = array( Field::create( 'select', 'header_type' ) ->add_options(array( 'simple' => 'Simple', 'slider' => 'Image Slider', )), Field::create( 'repeater', 'content_blocks' ) ->add_group( 'image', array( Field::create( 'image', 'image' ), Field::create( 'checkbox', 'include_in_slider' ) ->add_dependency( '../header_type', 'slider' ) )) );
This feature is only accessible in fields, which contain other fields:
- In repeater field groups
- In layout field groups
- In complex fields
You can also use
../ multiple times in order to get up multiple levels of nesting.