Conditions API

In this article, we're going to explain how to create custom Conditions and Assignments

  1. How to Create a Custom Rule
  2. How to Create a Custom Condition UI
  3. How to Create a Custom Assignment UI

Conditions offer a great way to either hide content based on a set of rules or assign layouts based on those same rules. Let's get into it.

How to Create a Custom Rule

The conditions are saved through JSON as group:condition_rule. The filter will be preceded by cs_condition_rule and then where the : is use a _. It will looked something like this. These can be used by Assignments or Show Conditions.

<?php // Save in JSON as `test:empty_arg` add_filter("cs_condition_rule_test_empty_arg", function($result = false, $args = []) { // Return boolean for passed or not return empty($args[0]); }, 0, 2);

How to Create a Custom Condition UI


In this example we are going to create the UI that will show up for show conditions UI. Our group is going to be example which will be store as example:condition.

<?php // Add to list of contexts add_filter( 'cs_condition_contexts', function($contexts) { // Add group label $contexts['labels']['example'] = __( 'Example', 'cornerstone' ); // Add controls $contexts['controls']['example'] = [ [ 'key' => 'example:condition', 'label' => __('My Example Condition (is)', 'cornerstone'), // Will check the 'toggle' => ['type' => 'boolean'], 'criteria' => [ 'type' => 'select', 'choices' => [ [ 'value' => 'enabled', 'label' => __('Enabled', 'cornerstone') ], [ 'value' => 'disabled', 'label' => __('Disabled', 'cornerstone') ], ] ] ] ]; return $contexts; });

It will look similar to this.

Example Show Condition

Configuration Reference

keystringHow to reference and store as in DB.
labelstringLocalized title to display in the library and when inspecting the element
togglearrayHow to control arguments. Types include boolean,
criteriaarrayThe field to use dynamically to control. Follows Cornerstone Controls API.

How to Create a Custom Assignment UI

Similar to Show Conditions. The difference in Assignments is that you can specifically have a Condition just for post type. Using global as your type will allow you to set a Condition to be used on all Post Types.

This uses the same configuration as Show Conditions.

<?php // Assignments filter add_filter('cs_assignment_contexts', function($contexts = []) { // 'global' adds to all assignment contexts $contexts['controls']['global'][] = [ 'key' => 'example:condition', 'label' => __('My Example Condition (is)', 'cornerstone'), 'toggle' => [ 'type' => 'boolean', ], 'criteria' => [ 'type' => 'select', 'choices' => [ [ 'value' => 'enabled', 'label' => __('Enabled', 'cornerstone') ], [ 'value' => 'disabled', 'label' => __('Disabled', 'cornerstone') ], ] ] ]; // If you only want a control for Single Layouts // $contexts['controls']['single'][] = [ ... ]; // If you have created a special layout type // This creates the group control label // $contexts['labels']['single-wc' ] = __( 'WooCommerce Single', 'cornerstone' ); return $contexts; });

@since 6.3.0

An additional step is needed if you are looking to add an assignment to the global context that be used on all layout types. Without it being apart of the global group.

<?php // Add our group the valid global assignments add_filter('cs_assignment_global_contexts', function($contexts = []) { $contexts[] = "example"; return $contexts; });

On a Single Layout it will look similar to this.

Example Assignment Condition on a Single Layout

See something inaccurate? Let us know