Conditions allow you selectively display any Oxygen element based on a condition or set of conditions, such as if a user is logged in, or if a user has a certain role or capability.
When an element's conditions evaluate to true, the element is shown. If the conditions evaluate to false, the element is hidden. By default, all of an element's conditions must evaluate to true in order for it to be shown, because the condition type defaults to AND. If you change the condition type to OR, only one of the conditions must evaluate to true for the element to be shown.
To set a condition for any element, select the element and click the condition icon at the top of the Properties Pane. If you wish to add a condition to a Shortcode element, you must wrap it in a Div and add the condition to the Div.
You'll then be presented with the condition menu.
Set Conditions
This button launches the Conditions Modal, where you can set the conditions for this element.
Condition Type
Choose whether the condition stack is evaluated as AND (all conditions must be true) or OR (one condition must be true).
In-Editor Behavior
Choose the visibility of the element in the builder preview. Choose Always Show to make the element always visible in the builder. Choose Always Hide to see what the design looks like when the element's conditions evaluate to false. To preview the element's visibility based on the actual evaluation of its conditions, choose Show/Hide Based on Conditions.
Conditions Modal
Clicking Set Conditions launches the Conditions Modal, where you can designate the conditions used for the element. To get started, click the Add your first condition button in the center of the Modal. Now, you'll be presented with three fields: Condition, Operator, and Value.
Use the left-most dropdown to choose your condition first. Oxygen includes a number of built-in conditions, but conditions registered via the Conditions API will also be listed here.
Once you've chosen a Condition, choose an Operator in the middle drop down field. Operators are used to evaluate some value (for example, the current post's ID) against the value you choose. There are a number of operators available depending on the chosen condition. Some operators, such as contains or does not contain are abstractions of string comparison functions, and work as their name implies. Some conditions may not need an operator, in which case the only available operator will be two dashes (--).
Finally, choose a value in the right hand field. This field may be a dropdown, an input field, or both, depending on the chosen condition. When inputting a custom value, be mindful of the type of data you're comparing. For example, you should not use a string, or text, as the value for a Post ID condition, since it's comparing your value to a number.
Once a condition has been set up on an element, you can see the condition indicator icon next to that element's name in the Structure Pane.
This icon will assist in locating elements that may be hidden by a condition in the builder preview.
Conditions API
The Conditions API allows you to register your own conditions for use within Oxygen. This can be done from a custom plugin or via the Code Snippets plugin.
To begin, it's important to first check if the oxygen_vsb_register_condition function exists before we use it.
This prevents errors that would result from Oxygen not being active and our code still trying to call the oxygen_vsb_register_condition_function.
Next, we need to use the oxygen_vsb_register_condition() function to register our condition. The oxygen_vsb_register_condition function accepts the following required arguments:
Condition Name
(string) The name of the condition as it will appear in the Conditions list in Oxygen.
Values
(array) The array of pre-set values the user can choose from. Use the options key to list default values. Set the custom key's value to true to allow users to input custom values. Example: array('options'=>array('option 1', 'option 2', 'true', 'false'), 'custom'=>true).
Operators
(array) Array of operators that can be used in the Condition. Example: array('==', '!=').
Callback Function
(string) Name of function that will be used to handle the condition.
Condition Category
(string) Name of the category under which the Condition will appear in the Conditions dropdown.
In this example, we'll register a condition that checks the current post's ID.
if( function_exists('oxygen_vsb_register_condition') ) {
oxygen_vsb_register_condition('Current Post ID', array('options'=>array(), 'custom'=>true), array('==', '!=', '>=', '<=', '>', '<'), 'condition_post_id_callback', 'Post');
}
Since we want the user to input their own custom value, we've left the Options array empty and set Custom to true.
Next, we simply have to create the callback function to evaluate the condition and return true or false based on the evaluation.
if( function_exists('oxygen_vsb_register_condition') ) {
oxygen_vsb_register_condition('Current Post ID', array('options'=>array(), 'custom'=>true), array('==', '!=', '>=', '<=', '>', '<'), 'ex_condition_post_id_callback', 'Post');
function ex_condition_post_id_callback($value, $operator) {
$current_post_id = get_the_ID();
$value = intval($value);
if ($operator == "==") {
if ($current_post_id == $value) {
return true;
} else {
return false;
}
} else if ($operator == "!=") {
if ($current_post_id != $value) {
return true;
} else {
return false;
}
} else if ($operator == ">=") {
if ($current_post_id >= $value) {
return true;
} else {
return false;
}
} else if ($operator == "<=") {
if ($current_post_id <= $value) {
return true;
} else {
return false;
}
} else if ($operator == ">") {
if ($current_post_id > $value) {
return true;
} else {
return false;
}
} else if ($operator == "<") {
if ($current_post_id < $value) {
return true;
} else {
return false;
}
}
}
}
Note that the function accepts two arguments: $value and $operator. The possible values for these are determined by the values set in oxygen_vsb_register_condition, and are chosen by the user. Then, the arguments are passed to the function and used to evaluate the condition.
First, we set a variable to the value which we want to compare against. In this case, we need to know the post ID of the current post, so we set $current_post_id to get_the_ID(). Next, we make sure the value passed in by the user is an integer by setting $value to intval($value).
Finally, we set up an if statement that checks for the operator the user has chosen, and evaluates $current_post_id against $value to determine the outcome. Note that the if statement needs to accommodate every possible operator that has been declared in the oxygen_vsb_register_condition_call. We need to return true if the condition evaluates as true (.e.g. $current_post_id == $value, if $operator is ==), and return false if the condition is not true. When true is returned by the callback function, the element using this condition will be visible. If false is returned by the callback function, the element will be hidden.
Now that your condition has been registered, it will appear in the conditions dropdown for any element on your site.
Helper Functions
To make creation of Oxygen conditions easier, we've also included a few helper functions & variables.
In the above example, we can replace the entire if statement by returning the helper function eval_int() from the global object $OxygenConditions.
if( function_exists('oxygen_vsb_register_condition') ) {
oxygen_vsb_register_condition('Current Post ID', array('options'=>array(), 'custom'=>true), array('==', '!=', '>=', '<=', '>', '<'), 'ex_condition_post_id_callback', 'Post');
function ex_condition_post_id_callback($value, $operator) {
$current_post_id = get_the_ID();
$value = intval($value);
global $OxygenConditions;
return $OxygenConditions->eval_int($current_post_id, $value, $operator);
}
}
If we were evaluating a string, we could use the $OxygenConditions->eval_string() function. To use either function, simply return the function after declaring the condition variables, and pass in the value we're comparing to ($current_post_id), the value the user has chosen ($value), and $operator.
Additionally, when registering Conditions, we can use the $oxy_condition_operators global variable to quickly insert common sets of operators for use in our condition.
if( function_exists('oxygen_vsb_register_condition') ) {
global $oxy_condition_operators;
oxygen_vsb_register_condition('Current Post ID', array('options'=>array(), 'custom'=>true), $oxy_condition_operators['int'], 'ex_condition_post_id_callback', 'Post');
function ex_condition_post_id_callback($value, $operator) {
$current_post_id = get_the_ID();
$value = intval($value);
return oxy_condition_eval_int($current_post_id, $value, $operator);
}
}
First, we must make the $oxy_condition_operators variable available with the line global $oxy_condition_operators. Next, we replace our operators argument in oxygen_vsb_register_condition() with this variable, and target which set of operators from the array we want to use. There are three sets: int, string, and simple.
$oxy_condition_operators['int'] = array('==', '!=', '>=', '<=', '>', '<')
$oxy_condition_operators['string'] = array('==','!=','contains','does not contain')
$oxy_condition_operators['simple'] = array('==','!=')
