Access this dialog by selecting Add Rule from the Visitor Context Rules dialog. Use this dialog to set conditions for assigning visitors to predefined groups based on their browsing behavior.
When a visitor: Pick from the dropdown, as shown above. Additional options display, based on your selection:
Before you can define a module here, you must first create a CFML file in a location that can be referenced as a cfmodule template path. This is typically in the /customcf directory for the site. See Creating a Custom Detection Module, below, for more information.
Once you've created a module, select Is recognized by this custom module from the When a visitor dropdown, then enter the path to your module in the Module Path field.
Note that this cfmodule path is relative to the root or to a defined mapping, not a disk path. Since there's already a mapping to the site root, in the customcf case the path would be:
/{mysitename}/customcf/my-module-name.cfm
If CommonSpot can't find the file using the path you provide, an alert displays on save.
The Module Parameter field enables you to reuse a module in multiple rules, with different behavior. Enter any value that suits your purposes, or leave it blank if your module doesn’t need it. The value you enter is passed unaltered to your module, as attributes.moduleParameter. Your code can then use that value in any way you require.
Note that this value is a simple text string, with no inherent meaning; it is not evaluated or processed in any way. It's up to your module to use it as you see fit.
Add them to this group: Displays predefined groups. Pick from the dropdown.
Keep them in it: Specify how long to keep visitors in their assigned group.
Check this rule (for certain rule types only): Pick from the dropdown:
Description: Optionally enter a description for the rule.
Creating a Custom Detection Module,
Custom detection modules let you write custom ColdFusion code to detect any conditions you require.
Your module must test for whether the conditions you've defined are met, and return a true or false boolean value indicating whether to trigger the rule. Do this by setting a variable in the caller scope whose name is passed into the module as attributes.returnVariable.
Code typically looks like this:
isTriggered = {the result of your custom logic};
caller[attributes.returnVariable] = isTriggered;
Note the last line carefully. Do not set attributes.returnVariable directly - it won't have the desired effect.
Important Note: Do not set other variables in the caller scope. Doing so can have unpredictable results that may affect your entire site.
If the module doesn't set the required variable, or sets it to a non-boolean value, the rule will not trigger.
CommonSpot also passes the value entered in the rule’s Module Parameter field into your module, as attributes.moduleParameter, This value has no inherent meaning, it’s solely for use by the rule’s logic. It lets you use the same module in multiple rules, while invoking different behavior in each one, based on this value.
The sample module provided demonstrates this capability. You’ll find it here:
/commonspot/samples/visitorcontextruledetectionmodule/
Important Note: Test modules carefully before deploying them to a production site. Module errors are logged, rather than displayed on the page, so review logs first if you're not getting the expected results. Defective rules that are checked on every request will produce errors on every CommonSpot page, potentially creating many log entries on a busy site.
Related Links
You can download PDF versions of the Content Contributor's, Administrator's, and Elements Reference documents from the support section of paperthin.com (requires login).
For technical support:
