You may use Velocity code on your pages to access information about Rules which have been fired (triggered) prior to the page being displayed. This enables you to use Rules to customize the content and format displayed on a page. This feature may be combined with Velocity access to the Visitor object to create highly personalized content and formatting on your site.
Determining What Rules Were Fired (dotRulesFired)
Whenever a Rule is triggered, dotCMS automatically adds the Rule to the dotRulesFired attribute, which you can access from Velocity code. This attribute is set in both the HTTP Request object and the Session object.
Rule Properties
You may access the following properties for each Rule returned by dotRulesFired:
| Property | Description |
|---|---|
| ruleID | The Identifier of the Rule. |
| ruleName | The Name of the Rule. Note: Rule names are not unique, so the name alone may not uniquely identify which Rule was fired. |
| fireOn | A string indicating the conditions under which the Rule is set to fire. Valid values: Per Page, Per Request, Per Visit, or Per Visitor. |
| fireTime | The time the Rule was fired. |
For details on how to access each property, please see the example code, below.
Request and Session Object Differences
The Rules listed in the dotRulesFired attribute will change depending on whether it is accessed from the Request object or Session object:
| Object | Included Rules |
|---|---|
| Request object | All Rules which were fired for a single Request. |
| Session object | All Rules which have fired for the entire session. |
Once a new Request is sent, the Request object is cleared and a new list of Rules fired is created for the new Request. However the Session object retains a list of all Rules fired for all previous Requests in the session, and for Rules which are only evaluated once per session (Rules which are evaluated Per Visitor).
The following table shows which Rules are available from the Request object and the Session object:
| Fire On Property | Available from Request object | Available from Session object |
|---|---|---|
| Per Page | Most recent Request only | All Requests in Session |
| Per Request | Most recent Request only | All Requests in Session |
| Per Visit | Most recent Request only | All Requests in Session |
| Per Visitor | Only in the first Request | Yes |
Example Code
The following code can be added to a widget in a page to test what Rules were fired at any time in the Session before the page was displayed:
<h3>Rules Fired (from Session):</h3>
<ul>
#foreach($rule in $session.getAttribute("dotRulesFired").values())
<li>$rule.ruleName</li>
<ul>
<li>ID: $rule.ruleID</li>
<li>Fire On: $rule.fireOn</li>
<li>Time: $rule.fireTime</li>
</ul>
#end
</ul>
The following code (which is identical to the previous example, except that it accesses the $request object instead of the $session object) displays what Rules were fired in the current Request before the page was displayed:
<h3>Rules Fired (from Request):</h3>
<ul>
#foreach($rule in $request.getAttribute("dotRulesFired").values())
<li>$rule.ruleName</li>
<ul>
<li>ID: $rule.ruleID</li>
<li>Fire On: $rule.fireOn</li>
<li>Time: $rule.fireTime</li>
</ul>
#end
</ul>
