6. Provide your own UI for building rules
It's perfectly possible for contributed modules to provide their own UI for building rules.
This might make sense, when the UI should be more integrated in your module's UI. Possible uses I can think of are:
- Provide your own, simplified UI for basic configuration, which configures the rules for the user. Advanced users can go and customize those rules.
- Just list rules assigned to your modules' events, and allow seamless editing theme through the rules UI.
- Just allow the user to define custom conditions for your module to do its work. For this you could provide a default rule-set, which sets a boolean variable. Integrate the UI for customizing conditions into your module's UI.
How does it work?
First off, you have to decide whether users should be able to customize the provided rules at all. If not, just set the '#status' property (or 'status' for rule sets) to 'fixed', and users won't be able to change the rules. Furthermore fixed rules are hidden from the UI by default. You can, but need provide your fixed rules as default rules.
If users should be able to customize your rules, then just leave out the 'fixed' property. There is the possibility to provide them as default rules, however it's *not* suggested to use this mechanism when the rules are likely to change (when the user changes the settings in your module's UI). Instead just provide your rule in code and save it to the database yourself. Have a look at the example below.
The name of rules are prefixed with the providing module's name, so all names of rules created with the rules admin UI are prefixed with "rules". So once the user wants to edit a custom rule which is provided by another module, the UI shows the user this warning:
This rule has been provided by another module. Be aware that any changes made through this interface might be overwritten once the providing module updates the rule.
(This warning isn't shown when a user edits a default rule).
Using the API to create a rule
This is an example taken from the rules admin UI, which sets up an example and an example rule set. So to save your rule, just use rules_item_save(), which needs the item type ('rules', 'rule sets'), the name and the actual item (rule) to save. Be sure to prefix the name with your modules name, so it's unique!
<?php
function _rules_admin_install_example_rules() {
$rule = array(
'#type' => 'rule',
'#set' => 'event_node_view',
'#label' => t('Example rule: When viewing an unpublished page, publish it.'),
'#status' => 'custom',
'#categories' => array('example'),
'#active' => 0,
);
$condition1 = rules_use_condition('rules_condition_content_is_published', array(
'#settings' => array('#argument map' => array('node' => 'node')),
'#negate' => 1,
), t('Viewed content is published'));
$condition2 = rules_use_condition('rules_condition_content_is_type', array(
'#settings' => array(
'#argument map' => array('node' => 'node'),
'type' => array('page'),
),
), t('Viewed content is Page'));
$action1 = rules_use_action('rules_core_node_publish_action', array(
'#settings' => array(
'#argument map' => array('node' => 'node'),
'auto_save' => TRUE,
),
), t('Publish viewed content'));
$rule += array(
'#conditions' => array($condition1, $condition2),
'#actions' => array($action1),
);
rules_item_save('rules', 'rules_example_1', $rule);
}
function _rules_admin_install_example_rule_sets() {
$set = array(
'label' => t('Example: Empty rule set working with content'),
'arguments' => array('node' => array('type' => 'node', 'label' => 'Content')),
'categories' => array('example'),
'status' => 'custom',
);
rules_item_save('rule_sets', 'rules_set_1', $set);
}
?>After saving an item, you need to clear the rules cache so the changes are picked up:
<?php
rules_clear_cache();
?>