Advanced Topics
There are four basic components that can be customised in ASR: Scanners, Filters, Commands and Viewers. First let's explain what each of those are.
When one runs a report in ASR, the scanners are created. They will return some objects which are optionally sent through the filters, if they all return true for the item it gets added to the list. Viewers will then process those items and convert them to a series of columns for display. A command is a Sitecore Command which can be applied to the selected items.
There is one further concept in the ASR: Paremeters. These allow the user to select the information to be sent to Scanners, Viewers and Filters through the UI.
Scanners
A scanner is just a class that inherits from the ASR.Interface.BaseScanner abstract class, and must implement the following method signature:
public abstract ICollection Scan();
Scan will therefore return a collection of objects; those might be items or any other type of objects.
We need to create a Scanner definition item under /sitecore/system/Modules/ASR/Configuration/Scanners folder and indicate the Assembly, fully qualified name of the class (obviously we need to put the dll in the bin folder!). Optionally we can specify some attributes in the format name=value|name2=value|&...&nameN=valueN which can then be retrieved with the inherited method getParameter(string).
Filters
A filter is simply a class that inherits from ASR.Interfaces.BaseFilter and must implement the following method:
public abstract bool Filter(object element);
Filter will therefore return return true if the object is to be included in the report.
We need to create a Filter definition item under /sitecore/system/Modules/ASR/Configuration/Filters folder and indicate the Assembly, fully qualified name of the class (obviously we need to put the dll in the bin folder!). Optionally we can specify some attributes in the format name=value|name2=value|&...&nameN=valueN which can then be retrieved with the inherited method getParameter(string).
Don't assume the type of the parameter element, sometimes scanners can return heterogeneous collections.
Commands
Commands are just standard Sitecore Commands. They are defined under /sitecore/system/Modules/ASR/Configuration/Commands and besides the name of the command and the icon, they just have the command name, the standard way of mapping commands to classes in Sitecore (check the commands.config file under the App_Config folder).
Of course the recommended way of creating new commands in Sitecore is to create a class inheriting from Sitecore.Shell.Framework.Commands.Command and adding the mapping through an include configuration file. This is standard best practice in Sitecore and outside the scope of this document.
The checkbox Put single item on command context simply decides whether to create an array with all the selected items, adding the array to the CommandContext and invoke the command once, or just have one item at a time in the CommandContext and invoke the command once per selected item.
Viewers
A viewer is just a class that inherits from the ASR.Interface.BaseViewer abstract class, and must implement the following method signature:
public abstract void Display(DisplayElement dElement);
Display will therefore receive a DisplayElement object. One of the properties of this object (Element) will be the object it is trying to display, and then it can use the AddColumn method.
We need to create a Viewer definition item under /sitecore/system/Modules/ASR/Configuration/Viewers folder and indicate the Assembly, fully qualified name of the class (obviously we need to put the dll in the bin folder!). Optionally we can specify some attributes in the format name=value|name2=value|&...&nameN=valueN which can then be retrieved with the inherited method getParameter(string).
Example of a simple viewer:
public override void Display(DisplayElement dElement)
{
Sitecore.Security.Accounts.User user = dElement.Element as Sitecore.Security.Accounts.User;
if (user == null) return;
dElement.AddColumn("Name", user.Name);
dElement.AddColumn("Display Name", user.DisplayName);
dElement.AddColumn("Domain", user.Domain.Name);
dElement.AddColumn("Is Admin", user.IsAdministrator ? "yes" : "no");
}
Columns don't need to be hard-coded as they can be passed through attributes. Another alternative is to use the special field Columns defined in the Viewer definition item. Then those values can be retrieved from code using the Columns property. That's how for instance the ItemViewer class receives the list of columns that should add to the report.
Parameters
As explained earlier, the attributes to be sent to the basic components (Scanners, Filters and Viewers) can be hard-coded or obtained through user input in the UI. Parameters are indicated using curly braces, and they must be declared in /sitecore/system/Modules/ASR/Configuration/Parameters. The Parameter definition item includes information about the title, the type of control the default value and some extra parameters. There are currently five parameter types.
Text
This will simply display as a text box. It does not react to any parameters.
Date Picker
It will show a dropdown calendar selector. The selected date is retrieved as a string in the recommended ISO 8601 format.
User Selector
It will show a control that allows to select a user by showing the standard Account selection dialog in Sitecore. The filter attribute could be used to restrict which accounts are displayed the possible values are roles and users. So entering the following attribute in the parameter definition item filter=users will not allow to select roles. Right now the user selector only shows accounts from the Sitecore domain.
Item selector
It will show a control that allows to select an item. This control admits several parameters:
root: the item at the top of the selection tree
folder: the selected item
displayresult: how the selected item is shown in the textbox to the user. Possible
values:ID,Name, FullPath!
valueresult: how the selected item is stored and made available as a parameter. Possible values: ID,
Name, FullPath
filter: which items to show and allow to select. It folllows the same syntax as the TreeList field type in
Sitecore.
Dropdown
It offers the selection of different values in a dropdown. The possible values are created by adding child items to the parameter definition item. The name of the child items will shown in the dropdown, and the content of the value field used as the value of the parameter.
There is also another available feature when creating parameters. Certain special token replacements can be used as values in the dropdowns and as default values:
$sc_lastyear
$sc_lastweek
$sc_lastmonth
$sc_yesterday
$sc_today
$sc_now
$sc_currentuser
All the date tokens are replaced by a ISO formatted string.