Aricie
The DNN Expert for your web project
Aricie Blog

Create your rewriting provider in 15 minutes

Oct 17 2012

Aricie's Friendlier Url Provider (FUP in short) is an URL Rewriter focused on allowing you to create customized and human-readable URLs on your DotNetNuke installation. Not only does FUP provides a better overall experience for your users, it also makes your URLs more friendly to search-engines.

To showcase how easy it is to create a rewriting provider for your module, let's demonstrate in the following example.


First contact with FUP

Our story starts with a module; we’ve just finished working on our custom module for a league of gentlemen of leisure who like to challenge against one another. Each of them is listed in the main page of the module and can simulate the fight against a random opponent in a details page.

Aricie Friendlier URL provider main window  Showdown results between Number None and The CandleMaker

The League's IT guy installs the module and it works well, except there's this tiny problem: here's what the module url look like.

theuncannyleague.net/Default.aspx/tabid=55&ctl=details&mid=511&IdHero=2&IdChallenger=5

The league is pretty big on SEO and would like their urls to be more explicit.

Aricie's FUP comes with some default rewriting rules, so we can benefit from some basic url rewriting out of the box. Just by installing and enabling the FUP module, the above url is rewritten as:

theuncannyleague.net/en/getting-started/hero-match!/details/IdHero/2/IdChallenger/5.aspx

FUP makes some basic substitutions by default, for example:

  • Tab id => Tab name
  • Module id => Module title

There are lots of other parameters that FUP manages by default. Find them in the documentation.

Not bad for one module install and two clicks! But the way the ids for the Hero and his challenger show up in the url is not really satisfying. Let's take this to the next level and create a custom rewriting provider for our module.


Creating a custom provider for FUP

First, we create an assembly project where we add references to Aricie.Core, Aricie.DNN (both assemblies are packaged in the module Aricie.Shared, freely available on our website) and Aricie.FriendlierUrlProvider

Aricie Friendlier URL provider. References the rewriting provider project needs

There are different ways to implement our provider, depending on how we intend to build our application. In this tutorial, we'll use the SimpleAPI introduced in the latest version of FUP. The SimpleAPI namespace allows us to implement our rewriting provider very quickly while giving access to all the module options. To use the SimpleAPI, we create a class which inherits from the SimpleAPI.SimpleRewriterProvider base class.

using Aricie.DNN.Services.Url.FriendlyUrl;

public class HeroMatchRewriterProvider : SimpleAPI.SimpleRewriterProvider
{
    protected override List<simpleapi.simplegroupparamsrewrite> GetRewritingGroups()
    {
        throw new System.NotImplementedException();
    }
}
</simpleapi.simplegroupparamsrewrite>

Defining rewriting groups

What our provider needs now is to explain to FUP what 'groups' it will work with. A group is a way to rewrite one or many parameters in a readable string. It needs a name to be used in your configuration, a description, a list of parameters and a way to rewrite them. In our example, we have two parameters we'd like to rewrite. As they are not combined, we'll use two distinct groups. To create such groups, we'll use a fluent grammar:

using Aricie.DNN.Services.Url.FriendlyUrl;
public class HeroMatchRewriterProvider : SimpleAPI.SimpleRewriterProvider
{
    protected override List<simpleapi.simplegroupparamsrewrite> GetRewritingGroups()
    {
        var results = new List<simpleapi.simplegroupparamsrewrite>();

        results.Add(SimpleAPI.SimpleGroupFluentFactory
                    .CreateGroup("Hero", "Hero's name")             // we create a group called Hero
                    .AddParameter("IdHero")                         // that'll use the parameter IdHero
                    .SetRewritingDelegate(GetHeroName)              // this is the rewriting function
                    .Create());                                     // ok, we're done, create the group to add it to the results list

        results.Add(SimpleAPI.SimpleGroupFluentFactory
                    .CreateGroup("Challenger", "Challenger's name") // same thing here, just for the challenger
                    .AddParameter("IdChallenger")                   // obviously the challenger uses another parameter
                    .SetRewritingDelegate(GetHeroName)              // but the same method as the hero to retrieve a name from an id
                    .Create());                                     // we're done

        return results;
    }

    private string GetHeroName(SimpleAPI.SimpleGroupParamsRewrite CurrentGroup,
                                RewriteType objRewriteType,
                                System.Collections.Generic.Dictionary<urlparam,> @params,
                                FriendlierUrlStrategy strategy)
    {
        return new HeroController().GetHeroInfo(CurrentGroup.SingleParameterAsInteger(@params)).HeroName;
    }
}
</urlparam,></simpleapi.simplegroupparamsrewrite></simpleapi.simplegroupparamsrewrite>

Creating a group is straightforward. It needs a name, a description and add the parameters you need from the original url. Point the group to the method that it will use to retrieve the rewritten value, based on the parameters we've told him to use. In this case, the method GetHeroName just uses the controller we developed for our module to get a name from an id.
Note the SingleParameterAsInteger call. If your group uses just one parameter, you can use this method to directly access the parameter value parsed as an int.

I’d go on to the next step... but there's no next step! We’re done. Let's just build our assembly, and copy it to the bin folder of the DNN instance. What we've just implemented in our provider is enough to indicate to FUP what transformations are needed when an url to our module contains parameters named IdHero or Idchallenger. FUP will then manage these groups called Hero and Challenger and expose them so we can configure how to rewrite the url.
The only thing left is a bit of configuration for our new provider.


Configuring FUP

First let’s access FUP configuration by clicking the module menu and selecting “Manage”. A modal popup appears. Select the “Module Specific Providers” tab and click on “Add new Module Specific Provider”. We need to let FUP know that there's a new rewriting provider, and that this provider is for just our module.

Adding the provider to Aricie Friendlier URL provider

Fill in the textboxes with a name for your provider, then give the type of your provider in the .net format namespace/type, assembly and end with your rewriting rule (we’ll describe the rule later).

Save the configuration and get back to the main FUP settings. Now let's add the rewriting provider to our custom module. Head to the “Module Specific Strategies” tab and click “Add Module Specific Strategy” after selecting your module in the dropdown list.

Add Aricie Friendlier URL provider to the specific rewriting strategies

As you can see there's already a rewriting provider for the DotNetNuke blog defined in the above screenshot.The blog provider has just been released with FUP 2.2, and it was written using the SimpleAPI (in fact, it was the reason why this tutorial was written). FUP comes with lots of providers by default.

To add the provider we wrote for our module, we select it in the dropdown list and click “Add Provider”.

Aricie Friendlier URL provider custom provider

Finally we can explain to FUP how we would like the url to be rewritten by using the groups we’ve defined. BASE_REPLACERULE_ROOT and BASE_REPLACERULE_END are aliases that have been defined in the default FUP rewriting strategy (this is the reason why FUP was able to start rewriting urls immediately after it was installed at the beginning of the tutorial) and wrap multiple groups. What we want is just to add the Hero group and the Challenger group in the rewriting rule. A group in FUP is written with the following syntax: [${GroupName}] so we just need to add oth groups in the url rewriting rule by using this syntax. 

Adding groups to the Aricie Friendlier URL rewriting rule

You may notice that we didn't exactly use the syntax described above for the Challenger group. We've added a "/vs/" between the square brackets in the Challenger group. In fact, groups can take some parameters to allow complete customisation; here by using the following syntax [Prefix${GroupName}Suffix] we can define prefixes and suffixes. So the Hero group is prefixed with a / and the challenger is prefixed with /vs/. It adds a bit of oomph to the url, doesn't it?

Let’s check it out. Since FUP is configured by default not to work when you're connected as an administrator, just launch another browser and browse to the page where our module is installed. Click and...

Aricie Friendlier URL provider with rewritten url

Voila! We’ve got the nicknames of our two brawlers as text in the url, separated by “vs”. Our customers are happy! But since we’re there, why not go for the knockout? Just head to the FUP configuration and click “Enable Extension less Urls”. FUP acknowledges the changes. Now let's modify the rewriting rule of our provider by getting rid of the second alias:

Aricie Friendlier URL provider without the alias

What's the result?

Aricie Friendlier URL provider

Nice! From raw query string to fully rewritten custom url in three rounds!

Of course we've just scratched the surface of FUP; there are plenty of options to allow customization of your urls but as you've seen, your custom providers can benefit from the power of FUP without being too complex themselves. If you want to know more, you can consult the product page for FUP.

Bloggers
Jesse's blog
 Jesse
 1  9  12/6/2014
Musings without a muse
 samyb
 6  95  1/3/2013
Stephane DNN Blog
 Stéphane TETARD
 1  3  4/23/2012
Categories
FUP