Posted by: Stefan Cullmann
Sun, 09 Sep 2007 20:59:24 GMT 

4.6.0: Token Replace

DotNetNuke 4.6.0 is going to include a new Token Replace engine. It searches text for tokens, analyses them and replaces the tokens with their related framework values. The syntax is quite simple: [Object:Property]. For example the token [User:Lastname] will be replaced with the last name of the current user. You might already know this kind of notation; it is the same that has been already used for system messages inside the language pack.

History

At the end of last year Sebastian and I were working on a request for User Defined Table 3.4.0. We were asked to replace the caption of a link with context information. Sebastian as editor of the German Language pack was familiar with the token syntax, so we took the code out of localization and used it in our module. Quickly we realized that this code was too slow to be called for each row of a User Defined Table. We rewrote that code from scratch using Regular Expressions, and it was impressive enough to get part of DotNetNuke 4.4.1. inside the Localization namespace.

We now had got a fast token replacement service, and some developers already started on reusing the code inside their own projects. Reusing meant that they copied the code and wrote their own, specialized token engines. As copying code is not really an Object Orientated technique, I started again a major refactoring which resulted in a new set of classes located in the new DotNetNuke.Services.Tokens namespace. These new services provide new enhancements and are open for own extensions. The previous TokenReplace class inside the Localization namespace still exists, but it is now deprecated and is actually just an adapter to the new classes.

Usage

TokenReplace allows the following notations:

[Object :Property]
[Object :Property|Format]
[Object :Property|Format|IfEmpyReplacement]

TokenReplace recognizes the following Object names as valid source for values:

* “custom” can be replaced with custom text, passed as separate parameter
** The content depends also on the scope and profile visibility setup. 

The output can be formatted using a format string. You can use the usual Date and Time Format Strings for date values or Numeric Format Strings for any numeric value. String values are handled using String.Format.

Example:
[User:Lastname|Dear Mr./Mrs . {0}] Dear Mr./Mrs. Walker
[Date:Now|dddd] Monday

The “Format” string can be followed by an additional “IfEmptyReplacement”, which will be returned when is requested property is not found or not set.

Example:
[User:Firstname|Hi {0}|Hello Guest]

Reusing

TokenReplace was built with extensible in mind and was therefore created using inheritance. The top level class is BaseTokenReplace. This class handles the tokenization using Regular Expressions. If you only want to handle one single or only few custom token, this class is your friend:

Public Class DateTimeTokenReplace
    Inherits Services.Tokens.BaseTokenReplace

    Public Function ReplaceDateTimeTokens(ByVal strSource As String) As String
        Return MyBase.ReplaceTokens(strSource)
    End Function

    Protected Overrides Function replacedTokenValue(ByVal strObjectName As String, _
                        ByVal strPropertyName As String, ByVal strFormat As String) As String
        Dim result As String = String.Empty
        If strFormat = String.Empty Then strFormat = "g"
        If strObjectName.ToLower = "datetime" Then
            If strPropertyName.ToLower = "today" Then
                result = System.DateTime.Today.ToString(strFormat)
            Else
                result = System.DateTime.Now.ToString(strFormat)
            End If
        End If
        Return result
    End Function
End Class

'sets "Today is Monday" on Mondays
Dim r as String = new DateTimeTokenReplace().ReplaceDateTimeTokens("Today is [Datetime:today|dddd]")

If you need to handle multiple kinds of Object tokens, you might want to handle every data source in its own custom class. This class needs to implement IPropertyAccess which consists out of the function GetProperty and the property Cacheability. 
  

Public Interface IPropertyAccess
    Function GetProperty(ByVal strPropertyName As String, ByVal strFormat As String, _
                          ByVal formatProvider As Globalization.CultureInfo, _
                          ByVal AccessingUser As UserInfo, ByVal AccessLevel As Scope, _
                          ByRef PropertyNotFound As Boolean) As String
    ReadOnly Property Cacheability() As CacheLevel
End Interface

BaseCustomTokenReplace is able to handle multiple data sources. The previous example can now be rewritten. First we need the property access class:

Class DateTimeAccess
    Implements Services.Tokens.IPropertyAccess

    Public Function GetProperty(ByVal strPropertyName As String, ByVal strFormat As String, _
            ByVal formatProvider As System.Globalization.CultureInfo, ByVal AccessingUser As Entities.Users.UserInfo, _
            ByVal AccessLevel As Scope, ByRef PropertyNotFound As Boolean) As String Implements IPropertyAccess.GetProperty
    Dim result As String = String.Empty
    If strFormat = String.Empty Then strFormat = "g"
    If strPropertyName.ToLower = "today" Then
      result = System.DateTime.Today.ToString(strFormat, formatprovider)
    Else
      result = System.DateTime.Now.ToString(strFormat. formatprovider)
    End If
    Return result
  End Function
  
  Public ReadOnly Property Cacheability() As CacheLevel Implements Services.Tokens.IPropertyAccess.Cacheability
    Get
      Return CacheLevel.secureforCaching
    End Get
  End Property

End Class

The main token replace is now more compact:

Public Class DateTimeTokenReplace2
    Inherits Services.Tokens.BaseCustomTokenReplace
    Sub New()
        PropertySource("datetime") = New DateTimeAccess
    End Sub
    Public Function ReplaceDateTimeTokens(ByVal strSource As String) As String
        Return MyBase.ReplaceTokens(strSource)
    End Function
End Class

…

Dim dttr2 As New DateTimeTokenReplace2()
dttr2.DebugMessages = True
dttr2.Language = "de-de"
'sets "Montag" on Mondays
Dim s As String = dttr2.ReplaceDateTimeTokens("[datetime:today|dddd]")

There are three different CacheLevel:
CacheLevel
Meaning
notCacheable
Caching of the text is not suitable and might expose security risks
secureforCaching
Caching of the text might result in inaccurate display (e.g. time), but does not expose a security risk
fullyCacheable
Caching of the text can be done without limitations or any risk

You can ask TokenReplace whether your current [Token] string whether is cachable or not.

Dim cl as CacheLevel = dttr2.Cacheability("Is [Date:Now] cacheable")
'cl = CacheLevel.SecureForCaching

Class TokenReplace is the main class inside the tokens namespace. It uses to handle 13 different data sources. A new class does not need to handle each data source. If there is already an info class, the interface can also be put inside. Examples for these are UserInfo or ModuleInfo.

The method ReplaceEnviromentTokens has a number of overloads, which allow also to use DataRows, Dictionaries (HashTables) or ArrayLists as source for the tokenization.

Public Function ReplaceEnvironmentTokens(ByVal strSourceText As String) As String
Public Function ReplaceEnvironmentTokens(ByVal strSourceText As String, _
                ByVal row As DataRow) As String
Public Function ReplaceEnvironmentTokens(ByVal strSourceText As String, _
                ByVal Custom As ArrayList, ByVal CustomCaption As String) As String
Public Function ReplaceEnvironmentTokens(ByVal strSourceText As String, _
	       ByVal Custom As IDictionary, ByVal CustomCaption As String) As String
Public Function ReplaceEnvironmentTokens(ByVal strSourceText As String, _
	       ByVal Custom As ArrayList, ByVal CustomCaption As String, _
                ByVal Row As System.Data.DataRow) As String

TokenReplace is not sealed, so you can extend it with your own data sources.

TokenReplace can also handle object less [PROPERTY] tokens, which might help to renew some already existing Token Engines inside DotNetNuke.

Example:

Public Class DateTimeTokenReplace3
    Inherits DotNetNuke.Services.Tokens.TokenReplace

    Public Sub New()
        MyBase.new(Services.Tokens.Scope.Configuration)
        UseObjectLessExpression = True
        PropertySource(ObjectLessToken) = New DateTimeAccess
    End Sub
End Class

…

dim s as String = new DateTimeTokenReplace3().ReplaceEnvironmentTokens( _
                      "hello [User:Displayname|{0}|Guest], today is [TODAY]")

Trackback Print

Tags:

Categories:

Location: Blogs Stefan Cullmann