With the latest release of the Url Master module version, and the release of the Blog Module Friendly Url Provider, keen developers want to know about how they can create their own customised Url providers.
For a talented developer, there’s not much to it. It’s just a case of implementing a derived version of a defined base class, and providing your own implementation of three main methods, one each for Url Rewriting, the generation of Friendly Urls and (optionally) any redirecting that must be done.
It’s possible to implement any combination of these, for example, to create a module that just does redirections or one that handles the translation of Friendly Urls back into a format for Url Rewriting. Or you can implement all three.
Additionally, it’s possible to provide a user interface for the custom settings that go into the module – or you can skip the creation of the UI and just configure it via the web.config file.
Simply put, you can make it as simple or as complicated as you like – the power is in your hands!
The first port of call for any module developer is to download these files:
Extract the Url Master instructions zip file, and open the file called ‘Url Master Creating a Custom Module Provider.htm’. This contains detailed instructions on the process, which this post will cover in a more basic form.
You can install the example Module provider (which is called YourName YourModule Module Friendly Url Provider , so you can do a find/replace). This installs through the DotNetNuke Extensions page like any other module.
This provider has a hard-coded set of Url transformations within it. Once it is installed, just activate it via the ‘Module Providers’ tab on the Admin->Portal Urls page. This is done by both checking the ‘Use this provider?’ checkbox, and by selecting a page to use with. In this case, the ‘Home’ page has been selected and the >> button clicked to assign the Home page to use the provider.
Above : Assigning the YourName YourModule Friendly Url Provider to work with the ‘Home’ page.
Don’t forget to click the ‘Apply Changes’ button.
Once this is done, you can then go the ‘Test Urls’ page, and test out Urls for the Home page.
Do this by selecting the ‘Home’ page, and then adding &ItemId=1 as the querystring to add. The module looks for the ItemId parameter and replaces it (this works only on ItemId=1 and ItemId=2)
Above : Testing out the ‘YourName YourModule’ provider.
If everything has worked OK, you should see the generated Url look something like /Home/thefirsturl.aspx
This is because the module provider has detected the &ItemId=1 on the Home page, and replaced it with ‘the first url’. Note that the options for space replacement will affect the way it appears, in this case, the space replacement option hasn’t been used.
Clicking on the ‘Test Url Rewriting Section’, you’ll see that this is then translated back into a rewritten path of /Default.aspx?TabId=59&ItemId=1&thefirsturl
Above : The Rewriting Test showing translation of the /thefirsturl back into &itemId=1.
Finally, if you replace the ‘friendly’ Url with what it would have originally have been, you will see that it gets redirected.
This redirects the /itemId/1.aspx Url back to /thefirsturl.aspx version.
Once you have these features working as an example, you can build the source code of the example project, then replace the newly built .dll and .pdb files into your website bin, and step through with a debugger to see any part of the code working.
Creating your own Module Url Provider
Now that you’ve got an idea of how it all works, it’s time to use the starter project to build your own. Here’s the process:
Step 1 : Decide on the name for your module Provider. You will need a value for the YourName (name or company name), YourModule (ie Blog, Store, Forum, Widget) and example.com – your website. Write these down – it is imperative that you keep it consistent throughout the project, or ‘ere be dragons when you go to compile and install. The examples are all set up for a consistent renaming, and failing to do so (or changing your mind halfway through) will make it difficult to unpick.
Step 2 : Extract the source code into a directory. Rename the directory and the YourName.YourModule.ModuleFriendlyUrlProvider.csproj project file to match your chosen names.
Step 3 : Open the newly-renamed project file in Visual Studio.
Step 4 : Do a global (Entire Solution) find and replace for YourName and replace with the value you have chosen.
Step 5 : Do a global (Entire Solution) find and replace for YourModule and replace with the value you have chosen for the module name.
Step 6 : Rename the YourModuleModuleProvider.cs class file so that the YourModule part matches the value you have chosen for the module name.
Step 7 : Rename the package/YourModule Friendly Url Provider.dnn file to match the value you have chosen for the module name.
Step 8 : Recompile the project.
Step 9 : Open up a CMD window, and navigate to the path that the project file is in. Enter the command 'packageForInstall.bat XXXXX' where XXXX is either DEBUG or RELEASE, depending on the type of compile you just did.
Step 10 : Your custom module provider is now ready to install. Once you have verified that it installs OK, and that it works for the ItemId/1 and ItemId/2 tests (as shown above), you can modify the provider as you like.
If it’s all working at this point, then you’ve got the bare bones of a provider you can start modifying anyway you like.
How to Customise the Example Provider
There are three main areas to modify, the TransformUrlsToQueryString method, the ChangeFriendlyUrl function, and the CheckForRedirect function.
I would advise working on the TransformUrlsToQueryString method first. This involves designing how you want your Urls to look (ie http://example.com/my-really-cool-url-here) and then working backwards to get that to return the correct querystring values. This might involve a regex pattern, a database lookup, or some other method that you devise.
Once you have the desired Urls working correctly, then modify the ChangeFriendlyUrl function so that the supplied querystring/path items are changed into the friendly url format you desire.
For more ideas on how to implement this in a real-world module, you can also look at the source code for the Blog Module Provider, which is available for download.
I would strongly advise to follow the caching pattern shown in the Blog Module provider. It is not a good idea to lookup the database for a Url value for every request, and it is far better to use a cached hashtable of values for the lookup. I specify a hashtable because they are inherently thread-safe, which Dictionaries and other complex datastructures are not.
Once you have the workings of the module as you want them, you can turn your attention to the UI. The Url Master module looks for and loads up a single .ascx control for each module provider. The module providers, by default, don’t install as a ‘normal’ module, in that they don’t appear on the drop-down list of modules to add to DotNetNuke pages. The example source code has a settings.ascx control, which is loaded by the Url Master module when you click on the link for the specific Module Provider.
This control is modelled on the DotNetNuke module ‘Settings’ control, and is provided a hashtable of settings for the ‘load’ and ‘save’ events. These settings are those that will be saved as attributes in the module providers web.config entry. The input/output from this form is just the hashtable of settings – beyond this, you’re free to design the user interface however you like.
If you don’t have any database access or UI components, you can safely remove these from the provider. In fact the only real requirement for a provider is just the overriden ModuleFriendlyUrlProvider class and the web.config entries.
NOTE: While this provider is in a separate project/assembly, there is no reason why the provider and other components/classes cannot be included within a module along with the rest of the code. The code lies dormant until the Url Master module is configured and activated to access it.
Have you built one?
If you’ve built a custom Url provider for an internal or client project, or you’ve built one to be available along with your module, please let me know via the comments, and leave a link.
If you have any other comments or questions, please feel free to start asking via the comments. This is a big new development in the field of DotNetNuke Urls, and I’d like to see it pushed in ways I haven’t yet thought of.