Inventua HrefExchanger for DotNetNuke


 The Inventua HrefExchanger for DotNetNuke automatically swaps outgoing DotNetNuke URLs for friendly URLs, and incoming URLs for DotNetNuke URLs.  "Friendly URLs" are more easily published in marketing materials and more easily consumed by web spiders/bots like the ones that search engines use to index your site.

Try Before You Buy
All of Inventua's DNN modules 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
There are different versions of HrefExchanger for DotNetNuke versions 2.1.2, 3.x, 4.x and 5.x. 

Limitations
HrefExchanger uses the tab name attribute to create friendly URLs.  As a result, your tab names must be unique within each portal, or HrefExchanger will be unable to differentiate between pages (you can have identical tab names in different portals within the same DNN instance).  If your tab name contains spaces, they will be replaced with plus signs.  If your tab name contains an ampersand (&), plus sign(+), dot(.), forward or backslash (/, \) or question mark (?), the URL will not be rewritten, as these two characters are reserved characters for URLs.  Using the tab name as the friendly URL gives you complete control over what your friendly URL will be.

Switching on W3C output filtering can cause issues with some modules, and will incur a performance cost.  See the section "w3c output" for details.

Installation and Configuration

1.  Install the HrefExchanger Assembly:


The installation zip file contains a file named Inventua.HrefExchanger.dll.  You must extract this file to your DotNetNuke BIN directory to install it.

2.  Add web.config settings
You can enable HrefExchanger and configure options by adding these lines to your web.config file, inside the <configuration> tag:

If you are using IIS 6
<configSections>
  <section name="hrefExchanger" requirePermission="false" type="Inventua.HrefExchanger.ConfigurationHandler, Inventua.HrefExchanger" />
</configSections>

<system.web>
  <httpModules>
    <add name="HrefHttpModule" type= "Inventua.HrefExchanger.HrefHttpModule,Inventua.HrefExchanger"/>
  </httpModules>
</system.web>

<hrefExchanger extension=".aspx" w3c-output="none" check-language= "false" replace-spaces-with="-" />

If you are using IIS 7
<configSections>
  <section name="hrefExchanger" requirePermission="false" type="Inventua.HrefExchanger.ConfigurationHandler, Inventua.HrefExchanger" />
</configSections>

<system.webserver>
  <modules>
    <add name="HrefHttpModule" type= "Inventua.HrefExchanger.HrefHttpModule,Inventua.HrefExchanger" preCondition="managedHandler"/>
  </modules>
</system.webserver>

<hrefExchanger extension=".aspx" w3c-output="none" check-language= "false" replace-spaces-with="-" />

Ensure that the line containing section name="hrefExchanger" is a direct "child" node of the "configSections" section - do NOT place it inside the sectionGroup name="dotnetnuke" section.

You can add also custom settings for each portal in a multi-portal DNN setup by adding child entries to the hrefExchanger element.  If you are using a multi-portal DNN setup, you must still fill in the top-level settings as a default.  For example:

<hrefExchanger extension=".aspx" w3c-output="transitional">
  <portal portalid="1" extension=".page" w3c-output="none" />
  <portal portalid="2" extension=".dnn" w3c-output="strict" />
</hrefExchanger>

Note: In a standard DotNetNuke web.config file, most of the sections will already exist. You should add the lines relevant to HrefExchanger to the existing sections.  In DNN 3, DNN4 and DNN5,  the httpModules <add name= "HrefHttpModule ... line MUST appear before the line

<add name="UrlRewrite" type="DotNetNuke.HttpModules.UrlRewriteModule, 
            DotNetNuke.HttpModules.UrlRewrite" />
because the standard DNN URL rewriter disrupts HrefExchanger, even if it is disabled (if you are using HrefExchanger to provide friendly URLs, you should disable DNN friendly URLs in the "host settings" page within DNN).

extension

Specifies the URL extension you want to use for friendly URLs, including the leading "." dot character.  The default value is ".aspx".

Do not use .htm or .html, as an extension for HrefExchanger. IIS is configured to handle these extensions without passing control to ASP.NET, and therefore HrefExchanger will not be executed for these file extensions.  Other file types that are automatically configured to be handled by IIS can be found in the IIS "MIME Types" configuration tab and include .gif, .bmp, .css, .doc, .exe, .jar, .rar, .zip and many others.

w3c-output

The HrefExchanger can filter DNN output and correct it to W3C HTML 4.01 Transitional or W3C HTML 4.01 Strict format.  Available values are "none" (default), "transitional", and "strict".

WARNING:  There is a overhead involved in the processing of DNN to w3c-valid output.  For high-traffic sites, you should not use of this feature without performing your own performance testing (set to "none" to disable this feature.)  W3c output filtering may disrupt some modules.  In particular, if you get Javascript errors after installing hrefExchanger, try setting w3c-output to "none".  If you find modules that have problems running with HrefExchanger, please report the problem using our forums at http://www.inventua.com/forums.content.

check-language

The HrefExchanger can check your tab names for non-english characters - for example, Arabic, Hindi or other languages, or the copyright symbol - and only rewrite the URL if the tab name does not contain these characters. This prevents the Friendly URLs from containing character sequences that cannot be entered by end users. The default value is false (language checking is off).

enabled

If set to "false", disables HrefExchanger for a given portal.

disable-output-filtering

If set to "true", disables output filtering for a given portal.  That is, input filtering remains active (so friendly URLs can be published in external documentation and entered by users), but no processing is performed on HTML output.

replace-spaces-with

Replaces spaces in the URL with the character you specify. Make sure this attribute is a single character only.  This option only affects automatically generated Friendly URLs - it has no effect on custom URLs (see section 4 below for details).

3.  Overriding filtering for specific pages or URLs
By default, the HrefExchanger contains checks to make sure that the returned result being rewritten is a HTML file.  You may wish to override the default rule checking to enable URL rewriting for a non-HTML file. For example, the Google Site Map component for DNN (http://www.l-space-design.com/Products/Google_Site_Map_ASP_NET.aspx) returns an XML file, and you may want this file to have URLs rewritten.  You can override default rule checking by adding <url> sections to your HrefExchanger section in web.config.  The url nodes must have two attributes - path, which specifies the relative path of the file you want to control HrefExchanger filtering for, and action, which tells HrefExchanger whether to filter the file or not.  For the action attribute, the values "filter" and "ignore" are the available options.  The example below shows <url> nodes added for a specific portal - you can also add <url> nodes to the default <hrefExchanger> node.

 <hrefExchanger extension=".aspx" w3c-output="transitional">
  <portal portalid="1" extension=".page" w3c-output="none">
    <url path="GoogleMap.aspx" action="filter" />
   
<urlpath="images/SomeImage.aspx?getimage=1" action= "ignore"/> 
 
</portal>
  <portal portalid="2" extension=".dnn" w3c-output="strict" />
</hrefExchanger>

4.  Setting specific custom URLs for particular pages
(DNN 3, 4 versions only). By default, HrefExchanger uses your DNN page name as the basis for the "friendly" URLs it generates. You can override the default friendly URL for specified pages by adding <customurl> nodes to the <hrefExchanger> node, or to the relevant <portal> node.  For example:

 <hrefExchanger extension=".aspx" w3c-output="transitional"> 
  <customurl tabid="10" path="my-custom-url.aspx" />
  <customurl tabid="11" path="another-custom-url.aspx" />

  <portal portalid="1" extension=".page" w3c-output="none">
    <customurl tabid="211" path="child-portal-custom-url.page" />
  </portal>
</hrefExchanger>

Your custom URLs must have the same extension as the extension configured for the portal.  For example, in the sample above, the <portal> node for portal id 1 is using .page as the extension for each Friendly URL.  Therefore, any <customurl> path settings must also use the same extension - that is, for portal 1, "child-portal-custom-url.page" is a valid custom URL path, but "child-portal-custom-url.aspx" is not, because ".aspx" is not the configured extension of portal 1.  The "path" of the custom URL you specify should not contain characters that are not valid in an URL (as per RFC1738 - invalid characters include spaces, and the <, >, #, quote character, percent (%) character, {, }, |, \, ^, ~, [, ] and ` characters).  HrefExchanger uses the exact value you specify, and does not perform character replacement or any other form of filtering or validation on your custom url.

Determining the tab id of a page:  To determine the "tabid" value to use for a specific page, log in as host or an administrator user and navigate to the page.  HrefExchanger does not rewrite URLs when you are logged in as an administrator, so you can identify the tab id from the query string displayed in your browser.

5.  Configure Internet Information Services (IIS)
If you are using a non-standard extension (that is, anything but the ".aspx" extension), you must configure Internet Information Services to accept it, and direct processing to ASP.NET.  Go to your virtual directory setup in the IIS Manager, and in the Virtual Directory tab (or for a "web site", the Home Directory tab), click Configuration, then add an application extension for the extension you set your extension to. The application "executable" path should be set to the .NET 1.1 ASP.NET ISAPI dll - "C:\WINDOWS\Microsoft.NET\Framework\v1.1.4322\aspnet_isapi.dll". Un-check the "Verify that file exists" checkbox and click OK to complete this step.

If you are unable to configure IIS (for example, because you are in a hosted environment), use the standard ASP.NET extension ".aspx".

How it works
HrefExchanger "friendly url" swapping works in two ways - on the request coming in, and on the HTML going out.  For URLs in the HTML going out, HrefExchanger scans the URL and determines whether the URL is for the current site.  If it is, it converts the URL to a Friendly URL using the relevant page's tab name.  For all requests coming in, HrefExchanger looks for the extension you specified, and converts the URL back to a DotNetNuke "tabid=nn" style URL.

When you are logged on as an admin or as the host user, output filtering is disabled (this includes friendly URLs and W3C output filtering).  This is a safety mechanism so that if you encounter any problems, you will still be able to access your site as an administrator.

 

Conditions of use
Permission is hereby granted, on a Try-before-you-buy basis, to any person obtaining a copy of the Inventua DNN HrefExchanger and associated documentation files (the "Software"), to use the Software without restriction, including the rights to use, copy or otherwise use the software for commerical or non-commercial use, but excluding any rights to reverse engineer or remove Inventua logos and licensing information. This permission does not imply or otherwise grant any rights to any other Inventua intellectual property including but not limited to logos, trademarks, documentation and software products.

THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

This help file, the accompanying software and other materials supplied with the software are Copyright © Inventua, 2004-2009. All Rights Reserved.

About DotNetNuke
The Inventua DNN HrefExchanger is a ASP.NET Http Handler, designed for DotNetNuke. For more information on DotNetNuke, visit http://www.dotnetnuke.com.

About Inventua
Inventua provides software tools for information technology organisations that facilitate and maximise synergy and cohesion between development, support, marketing and management teams, improves software product quality and helps information technology organisations to provide great products and great support. Visit Inventua on the web at http://www.inventua.com