Accessing Rules from Velocity Code - Documentation topics on: request,rules,velocity,.

Accessing Rules from Velocity Code

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:

PropertyDescription
ruleIDThe Identifier of the Rule.
ruleNameThe Name of the Rule.
Note: Rule names are not unique, so the name alone may not uniquely identify which Rule was fired.
fireOnA string indicating the conditions under which the Rule is set to fire.
Valid values: Per Page, Per Request, Per Visit, or Per Visitor.
fireTimeThe 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:

ObjectIncluded Rules
Request objectAll Rules which were fired for a single Request.
Session objectAll 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 PropertyAvailable from
Request object
Available from
Session object
Per PageMost recent Request onlyAll Requests in Session
Per RequestMost recent Request onlyAll Requests in Session
Per VisitMost recent Request onlyAll Requests in Session
Per VisitorOnly in the first RequestYes

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>