|
The Inventua TokenExchanger for DotNetNuke gives you the ability to use "variables" in your DotNetNuke pages by automatically swapping "tokens" from your page skin and container HTML and module data for DNN user, portal and custom values.
Try Before You Buy
All of Inventua's DNN modules and components are available on a try before you buy basis. You can download them freely from Inventua, and try them out for as long as you like. If you are happy with the product, you can buy it at SnowCovered.
Compatibility
TokenExchanger is compatible with DotNetNuke 3 and 4.
Installation and Configuration
1. Install the TokenExchanger Assembly:
The installation zip file contains a file named Inventua.TokenExchanger.dll. You must extract this file to your DotNetNuke BIN directory to install it.
2. Add web.config settings
You can enable TokenExchanger and configure options by adding these lines to your web.config file, inside the <configuration> tag:
<configSections>
<section name="tokenExchanger" type="Inventua.TokenExchanger.ConfigurationHandler, Inventua.TokenExchanger" />
</configSections>
<system.web>
<httpModules>
<add name="TokenHttpModule" type= "Inventua.TokenExchanger.HrefHttpModule,Inventua.TokenExchanger"/>
</httpModules>
</system.web>
<tokenExchanger enabled = "True" />
Ensure that the line containing section name="tokenExchanger" is a direct "child" node of the "configSections" section - do NOT place it inside the sectionGroup name="dotnetnuke" section.
You can add custom settings for each portal in a multi-portal DNN setup by adding child entries to the tokenExchanger element. If you are using a multi-portal DNN setup, you must still fill in the top-level settings as a default. For example:
<tokenExchanger enabled="True" command= "readTokenData">
<portal portalid="1" command="readTokenValues" />
<portal portalid= "2" command="readTokenValues"
connectionstring="server=someserver;database=a_database;userid=xx;password= xx" />
</tokenExchanger>
Note: In a standard DotNetNuke web.config file, most of the sections will already exist. You should add the lines relevant to TokenExchanger to the existing sections.
| portalid |
For <portal> nodes, the portalid specifies the index of the portal the settings are for. |
| command |
TokenExchanger can read values from a stored procedure. The command attribute specifies the name of the stored procedure. Refer to the section below "reading from the database" for more information. |
| connectionstring |
The connectionstring attribute contains the database connection string for the database command referenced in the "command" attribute. This setting is optional - if it is blank or omitted, the command will be run from the DotNetNuke database. |
| enabled |
If set to "false", disables TokenExchanger for a given portal. |
| <token nodes> |
You can add pre-defined token values in your web.config. These values are available in your HTML, just like the values you read from the database. You can use token nodes to set a "default" value for tokens that are read from the database, or you can use them without reading from the database. Token nodes can contain fixed values, or a reference to a text file, or a reference to an xml file and an xpath to read a value from. |
The options above are valid on the <tokenExchanger> line (and will be effective for all portals), or as part of a <portal> node, which sets the option for a single portal only.
3. Reading from the database
If the "command" attribute is set, TokenExchanger will call the nominated stored procedure and add the return values to it's token values table. The stored procedure must accept three values - @PortalId int, @UserId int, @LocaleId nvarchar(10).
Sample:
To configure TokenExchanger to run a stored procedure called "GetTokenValues", use the following web.config setting:
<tokenExchanger command="GetTokenValues" />
To read values from the database, create a stored procedure. The PortalId, UserId and LocaleId values must be present, but your stored procedure does not have to make use of them.
CREATE procedure GetTokenValues
@PortalId int,
@UserId int,
@LocaleId nvarchar(10)
AS
SELECT LogoFile AS PortalLogoFile
FROM Portals
WHERE PortalID = @PortalID
TokenExchanger assumes only one row of data is returned from the stored procedure. All of the values returned are dynamically inserted into the TokenExchanger token values table, which it uses to perform replacements at run time. The example above makes a "PortalLogoFile" values available, which would be referenced in HTML as [$PortalLogoFile].
The stored procedure method of getting database values is intended to be used for getting data from third-party modules, external applications or other data sources.
4. Pre-defined values
TokenExchanger automatically populates its token values table with DNN portal and user values. The fixed values are:
| DATETIME |
The current date and time. |
| TIME |
The current time. |
| DDD |
The current day as an abbreviation (for example, "Tue"). |
| DD |
The current day of the month in two digit format (with a leading zero for single digit values). |
| D |
The current day without a leading zero. |
| YYYY |
The current year. |
| M |
The current month without a leading zero. |
| MM |
The current month in two digit format (with a leading zero for single digit values). |
| MMMM |
The current month name (for example, "January"). |
| USERID |
The currently logged on user's user id. If no user is logged in, the value will be -1. |
| USERNAME |
The currently logged on user's login name. |
| FIRSTNAME |
The currently logged on user's first name. |
| LASTNAME |
The currently logged on user's last name. |
| FULLNAME |
The currently logged on user's full name, being a concatenation of their first and last names. |
| CREATEDDATE |
The currently logged on user's account creation date. |
| EMAIL |
The currently logged on user's email address. |
| LASTLOGINDATE |
The currently logged on user's last login date. |
| CELL |
The currently logged on user's cell phone number. |
| CITY |
The currently logged on user's city. |
| COUNTRY |
The currently logged on user's country |
| FAX |
The currently logged on user's fax number. |
| IM |
The currently logged on user's instant messenger ID. |
| POSTALCODE |
The currently logged on user's postal code. |
| PREFERREDLOCALE |
The currently logged on user's preferred locale code. |
| REGION |
The currently logged on user's region (state). |
| STREET |
The currently logged on user's street. |
| TELEPHONE |
The currently logged on user's telephone number. |
| TIMEZONE |
The currently logged on user's timezone offset. |
| UNIT |
The currently logged on user's unit. |
| WEBSITE |
The currently logged on user's website URL. |
| PORTALDESCRIPTION |
The portal's description (from the site settings page). |
| PORTALEMAIL |
The portal's admin email address (the portal administrator's email address). |
| PORTALFOOTERTEXT |
The portal's "footer text" as specified in the site settings page - "copyright" field. |
| PORTALNAME |
The portal's name (title) from the site settings page. |
To use a pre-defined value in your portal, just specify the token name from the list above with the surrounding [/$...] characters. For example: [$YYYY] to display the current year.
5. Specifying "token" default values in web.config
You can specify "token" nodes on the tokenExchanger root node or for any portal node to add pre-defined tokens to the TokenExchanger token values table. These values can serve as default values, or can be used for commonly used values you choose to centralize in your web.config file.
<tokenExchanger command="getTokenValues">
<token name="company" value="Inventua" />
<token name="fullname" value="Anonymous User"/>
<portal portalid="1">
<token name="company" value="ACME Corporation"/>
</portal>
</tokenExchanger>
In the example above, a value called "company" is set to "Inventua", so that the variable name [$Company] could be used in your page. This value is valid for all portals because the token node that specifies it is a child of the top-level tokenExchanger element - but the value is over-ridden for portal 1 with the value "ACME Corporation". Another value called "fullname" is specified - this is a value that gets automatically set by TokenExchanger to the name of the currently logged-on user, so the value "Anonymous User" would be used only if the user is not logged on.
As an alternative to specifying fixed values for tokens in web.config, you can specify a "file" attribute to read data from a text file (including a HTML file). Use the ~ character to specify the file relative to the root DNN directory. The entire contents of the text file are inserted in place of the token. For example:
<tokenExchanger command="getTokenValues">
<token name="company" file="~\portals\0\companydata.htm" />
</tokenExchanger>
You can also specify an XML file and an xpath to read data from an XML file. For example:
<tokenExchanger command="getTokenValues">
<token name="company" file="~\portals\0\data.xml" xpath="//data/companydata" />
</tokenExchanger>
When the xpath attribute is included, TokenExchanger parses the XML file and uses the value corresponding to the specified "xpath". In the example above, the XML file would look like this:
<data>
<companydata>ACME Corporation</companydata>
</data>
6. Adding tokens to your pages
Once the TokenExchanger is installed, you can add tokens to your pages. Tokens are variables in the form [$TOKENNAME], where TOKENNAME is the name of the token you want to replace. Token names must contain only letters and numbers, and are not case sensitive. Tokens can be used in skins, containers, as values in modules and even in Javascript code.
How it works
The TokenExchanger reads token values in the following order:
1. From web.config, first for the top-level tokenExchanger element, then for your current portal.
2. From the user and portal objects in DotNetNuke. The pre-defined token names are listed above in the section "pre-defined values".
3. From the database, by calling the stored procedure nominated in the command attribute.
If a token name is specified more than once - for example, in web.config, and in the returned result from the database - the "last" non-blank value is used.
4. Just before your DotNetNuke page is returned to the user, TokenExchanger scans the returned HTML for tokens and replaces them with the appropriate token values.
When you are logged on as an admin or as the host user, output filtering is disabled (so tokens are not replaced). This is so you can view the tokens - whether in your skin, or as values in a Text/HTML module (or other module) for editing.
|