Template replacer

From Sense/Net Wiki
Jump to: navigation, search
  •  
  •  
  •  
  •  
  • 100%
  • 6.0.8
  • Enterprise
  • Community
  • Planned

Overview

This page contains information for developers about the Application Programming Interface (API) for creating custom template replacer classes. These classes can participate in any use case where a string replace functionality is needed and the 'tokens' to be replaced are well-known.

Details

The Template replacer module was created to handle any scenario that involves string replacing, when the replaceable tokens are well-known. Developers can create and execute custom code that provides replacements for any custom token in a string. The code that executes this replacer may provide additional parameters that the replacer can use during the execution.

The replacer mechanism is built on regular expressions. The expression used for finding the parameters can be customized in the replacer implementations.

Use cases

Developing with Sense/Net ECM sometimes involves dealing with parametrized strings. For example handling declarative parameters for controls like ActionMenu. In these cases it is useful to have a simple module for replacing parameters with actual values corresponding to the current environment. We created template replacers to handle the most common tasks of replacing parameters in a string and providing helper methods related to the Content Repository.

Action menu

A parameterized string for an ActionMenu control may look like the following:

...Pid={{PortletID}}...

In this case we know the token ('PortletID') and know how to replace it (we need to insert the ID of the current portlet).

Query template replacer

Another powerful example is the Query template replacer that is responsible for substituting values into predefined content queries. For example this is a dynamic query that will list content only under the current workspace:

InTree:'@@CurrentWorkspace.Path@@'

If you want the portal to replace your custom parameters in content queries, you just need to inherit from the class PortalContentQueryTemplateReplacer and provide your custom parameter names and replace rules.

Watermark template replacer

If you want to extend the behavior of watermark templates in the document viewer, please inherit from the following class:

  • WatermarkTemplateReplacer

Context bound portlet template replacer

If you want to extend the behavior of queries defined specifically in context bound portlets (e.g. the Content collection Portlet or Content query presenter Portlet) or content list views, please inherit from the following class:

  • ContextBoundPortletTemplateReplacer

Creating a replacer

Creating a custom replacer means writing a class that derives either from the base class TemplateReplacerBase or one of the built-in replacers. The portal automatically collects and processes the replacers, and provides a simple API to execute them.

Template replacers are collected into replacer families. The main class of the family is the one that is directly inherited from the base class above. All child types are family members that may override template behavior defined by parent classes. For example if you want your queries to behave differently in case of the @@CurrentDate@@ parameter, you can override that in a child type.

There are a couple of methods and properties that must or may be implemented in your derived class to make the replace mechanism work.

Template names

The TemplateNames property is mandatory in any derived class. It must provide a list of parameter names that the class targets.

Note that if you inherit your class from another template replacer (instead of inheriting directly from the base class) you can override the evaluation of one or more parameters by providing its name here.

Evaluate parameters

The EvaluateTemplate method is mandatory also. This method is the heart of your code: it provides the actual replacement code for every parameter name that is published by the TemplateNames property above.

This method is given the template name (in the above example 'PortletID'), an optional property name (e.g. if the template looks like this: 'TemplateName.PropertyName') and an optional context object provided by the executor code.

In the example above the EvaluateTemplate method receives the parameter PortletID, a null as a property name and a user control as the custom parameter that will be used to find the current portlet.

Evaluate expressions

The EvaluateExpression method is optional. In a derived class you can change or extend the behavior of interpreting chained properties and other expressions. See more examples in the Query template replacer article.

Evaluate modifiers

The EvaluateModifier method is optional. In a derived class you can change or extend the behavior of interpreting template modifiers like '+3days' in case of date values. See more examples in the Query template replacer article.

Pattern format

TemplatePatternFormat is an optional property that can be used to provide a custom regular expression for finding the parameter (the template name) in the original string. The default format is the following:

  • @@{0}(?<PropertyName>[\.\+\-][^@]+)?@@

As you can see it matches templates that are given in the following format:

  • @@TemplateName@@: a simple template
  • @@TemplateName.Property1@@: template with chained fields
  • @@TemplateName.Property1.Property2@@: template with chained fields

In the example above we provided a custom format that is more convenient for url parameters: \{{{0}\}}.

Executing a replacer

The replacer is executed by the feature it was created for. For example the Query template replacer is called by our Lucene search engine when we execute content queries. The feature should always call the TemplateManager.Replace method with the main (base) class of the replacer family, the system will take all inherited types into account during evaluation. The caller must provide the custom replacer type, the string that contains the replaceable data and optionally a parameter, used by the replacer.

This means if you are inheriting from one of the built-in replacers, you do not have to call the replacer method in your custom code, we do this for you in the right place.

In case you create a completely new replacer that inherits from the TemplateReplacerBase class, this is how you initiate the replace mechanism:

var result = TemplateManager.Replace(typeof(PortletTemplateReplacer), sourceText, this);

The example above is taken from the ActionMenu class where the optional custom parameter is the control itself.

If you want the portal to replace your custom parameters in the action menu scenario parameter, you just need to inherit from the class PortletTemplateReplacer and provide your custom parameter names and replace rules.

Examples

The following example demonstrates a simple use case for a template replacer. The client code has a string that contains parameters related to a portlet on the page. The replacer class can handle two parameters:

  • PortletID
  • DefaultView

These parameters will be used by the 'view changing' custom scenario and action that needs to know about the particular portlet and view to use.

public class PortletTemplateReplacer : TemplateReplacerBase
{
    public override string TemplatePatternFormat
    {
        get { return @"\{{{0}\}}"; }
    }
 
    public override IEnumerable<string> TemplateNames
    {
        get { return new[] { "PortletID", "DefaultView" }; }
    }
 
    public override string EvaluateTemplate(string templateName, string propertyName, object parameters)
    {
        var control = parameters as Control;
        var cbp = ContextBoundPortlet.GetContainingContextBoundPortlet(control);
 
        switch (templateName)
        {
            case "PortletID":
                return cbp != null ? cbp.ID : string.Empty;
            case "DefaultView":
                if (cbp != null)
                {
                    ...
                }
                break;
        }
 
        return string.Empty;
    }
}


Note that this sample module works only if the client code provides a user control as a parameter during the execution of the replacer. This user control (in this case the action menu) is used to find the portlet in question.

Related links

References