Display conditions

New conditions can easily be added to SproutCMS for use in the context engine.

Creating condition classes

Conditions are a helper class which extends the DisplayCondition class

The class provides four methods:

• getOperators - the operators available, such as Equals and Doesn't contain.
• getParamType - the field type to show in the admin when editing the condition, either 'text' or 'dropdown'.
• getParamValues - for dropdowns, the values available to be selected from.
• match - the main condition matching method, which determines if the specified operator and value matches the condition.

In many cases it's a lot easier to extend one of the base classes which exist for common types of conditions:

• DisplayConditionEnum - the value is selected from a list
• DisplayConditionInteger - the value is an integer
• DisplayConditionString - the value is a string

When using one of these bases classes, the method getCurrentValue should be implemented but no other methods need to be implemented (except for enums which also requires the getParamValues method).

Registering conditions

Conditions are registered using the Register::displayCondition method, which takes three arguments:

1. The class name including namespace.
2. The section the condition is in, shown as optgroups in the admin.
3. The friendly name of the condition.

Registration should be done in the sprout_load.php file of the module.

Example - day of the week

An example would be a condtion which matches on the day of the week. As the selection is a fixed list, DisplayConditionEnum is the perfect base class.

The condition is a helper class, and can be futher organised into a sub-namespace if desired.

The use of a specialised base class for enums, the code for the condition is very simple:

namespace SproutModules\AcmeInc\MyModule\Helpers\DisplayConditions;
use Sprout\Helpers\DisplayConditions\DisplayConditionEnum;
 
class DayOfWeek extends DisplayConditionEnum
{
 
	/**
	 * Options for the dropdown in the admin
	 */
	public function getParamValues()
	{
		// These are the ISO-8601 day of the week numbers
		return [
			'1' => 'Monday', '2' => 'Tuesday', '3' => 'Wednesday',
			'4' => 'Thursday', '5' => 'Friday', '6' => 'Saturday',
			'7' => 'Sunday'
		];
	}
 
	/**
	 * Return the current value of the variable.
	 * This is compared against the selected parameter value using the selected operator
	 */
	protected function getCurrentValue(array $env)
	{
		return date('N');
	}
 
}
 

This condition would be registered by adding the following line into the sprout_load.php file for the module:

Register::displayCondition('SproutModules\\AcmeInc\\MyModule\\Helpers\\DisplayConditions\\DayOfWeek', 'Date/Time', 'Day of week');

Example - hour of the day

In a similar way, the base class DisplayConditionInteger can be used for matching integer numbers. In this case the class is even simpler:

namespace SproutModules\AcmeInc\MyModule\Helpers\DisplayConditions;
use Sprout\Helpers\DisplayConditions\DisplayConditionInteger;
 
class HourOfDay extends DisplayConditionInteger
{
 
	/**
	 * Return the current value of the variable.
	 * This is compared against the selected value using the selected operator
	 */
	protected function getCurrentValue(array $env)
	{
		return date('G');
	}
 
}

And it's registered in the same way:

Register::displayCondition('SproutModules\\AcmeInc\\MyModule\\Helpers\\DisplayConditions\\DayOfWeek', 'Date/Time', 'Day of week');
Register::displayCondition('SproutModules\\AcmeInc\\MyModule\\Helpers\\DisplayConditions\\HourOfDay', 'Date/Time', 'Hour of day');