Sep 9

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:

Object	Class / Data source	Default Content**
“Host”	System.Collection.Hashtable	Secure Hostsettings
“Portal”	DotNetNuke.Entities.Portals.PortalSettings	current PortalSettings
“Tab”	DotNetNuke.Entities.Tabs.TabInfo	current TabInfo
“Module”	DotNetNuke.Entities.Modules.ModuleInfo	Nothing
“Culture”	System.Globalization.CultureInfo	currrent Culture
“User”	DotNetNuke.Entities.Users.UserInfo	current User
“Profile”	DotNetNuke.Entities.Profile	current User.Profile
“Membership”	DotNetNuke.Entities.Users.Membership	current User.Membership
“Date”, “DateTime”, “Time”	System.DateTime	current DateTime
“Ticks”	System.Int64 (Long)	current DateTime in ticks
“Row”, “Field”	System.Data.DataRow	Nothing
“Custom”*	System.Collections.ArrayList	Nothing
userdefined Token	Any Object by Reflection	Nothing
userdefined Token	Any System.Collection.IDictionary	Nothing

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

Scope	Description
NoSettings	Only access to Date and Time
Configuration	Tokens for Host, Portal, Tab (, Module)
DefaultSettings	Configuration and Current User
SystemMessages	System notifications to users and adminstrators
Debug	internal debugging, error messages, logs

The first four scopes will only return public relevant information. For example the only public avaiable property is HostName. All others are only accessible to the "Debug" scope. Critical information (host password...) is not available through TokenReplace.

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.