The DNN Referral Module

This blog was originally posted to the DNN Community Blog on October 28, 2013 by Nathan Rover.  Nathan has been building sites using DNN for the last 9 years and has worked at DNN Corp for over 3 years.  As part of the Engineering Team, he currently works on projects for both the DNN Store and  

In an attempt to simplify participation with the referral program on the Store, I have developed a new free and open source module that anyone can use, but is specifically designed with the referral program in mind. In the module settings, there is a field where you can enter one of the referral codes from the store. Once populated with a code all of the links generated in the module output will automatically have the referral query sting value/pair added.

The module can be configured in a few basic modes and will automatically obtain the product data via a server side web service call to the store. The following render modes are currently available (more may be added based on feedback).

  • Top Selling Modules – This is the same list of products that can be found on this page
  • Top Selling Skins – Like Modules, this is the same list as found here
  • My Products – This mode is intended for store vendors and will allow them to display a list of the products that they currently have listed in the store. Once selected, they will need to also provide a vendor Id.
  • Dynamic Search Results – This mode allows you to configure the module to listen for a particular query string parameter. If that parameter is detected, the value will be executed as a full-text search on the store. The results will then be shown in the module. Using this you could place this module on the DNN search results page or a page with the blog module and have it listen to the “search” parameter. Then say, if for example, a visitor to your site searched for the term “SEO”, the referral module would display the top search results from the Store that relate to “SEO”. When utilizing this mode, the module also supports a “fall back” search. Any of the other 4 modes can be configured as a fall back that will be shown in the event that the query string parameter is not detected or the dynamic search yields no results.
  • Static Search Results – This is similar to the Dynamic Search Results, only you can specify in the module settings what you would like to set the search value to. If you had a page on your site dedicated to help desk software, you could place this module then configure it to display products based on the search results for “Help Desk”. This would allow the module to display the most relevant content to your visitors.

There is also a setting to limit the number of results pulled from the server. By default this is set to 5, but you can change this number to whatever you would like in order to customize the output to best fit your site. It's important to note that many of the search methods have a server controlled maximum result set of 100. This is by design to help keep server load to a minimum. Along the same lines, the results of each mode are cached on the server side, but an additional layer of caching is available in this module. The module can cache the results on your site. Using this will reduce the number of service calls sent to the store and will ensure that this module doesn’t slow down the load time of your site.

The module output is constructed server side and uses three templates to allow you full control over how the products are rendered. The first template is the “Primary Template”. This is the outer container for the results, and the only token in this template is [RowTemplate]. When rendered, that token will be removed and replaced with all of the rendered row templates. The next Template is the “Row Template”. This template supports only one token; however, it can be repeated. So, for example, if you would like to display one item per row and you are using a div based layout, you would use “<div>[ItemTemplate]</div>”. However, if you are using tables and would like to show three items per row, you would use “<tr><td>[ItemTemplate]</td><td>[ItemTemplate]</td><td>[ItemTemplate]</td></tr>” The module will automatically do the math, and if you set it to display twelve results using the previous template, it would create four rows with three items each. Using the previous div template example, it would make 12 rows with one item each. The third template is the “Item Template”. This is used to control how each item is rendered. This template currently supports nine tokens, which are as follows:

  • [PackageName] – This is the name of the package as it would appear in a product list on the Store.
  • [PackagId] – This is the unique ID number for the package.
  • [PackageLink] – This is a full friendly URL to the product details page on the Store. If a referral code is provided, it will automatically be added to this URL.
  • [PackagePrice] – This is the list price for the item. It will be formatted in US dollars (as that is the currency used on the Store) with a $ symbol.
  • [PackageIcon] – This is a URL to the package icon which will be located on Amazon S3 storage.
  • [PackageRatingNumber] – This is a number between 1 and 5 that represents average review rating of the product.
  • [PackageRatingImage] – This is a URL to the image used to represent the average review rating. Like the package icon, these images are hosted on Amazon S3 storage.
  • [VendorName] – This is the name of the vendor who created the product.
  • [VendorLink] – This is a URL to the vendor profile on the Store. If a referral code is provided, it will automatically be added to this URL.

There is also a fourth template that will allow you to control what is shown in the event that the module has no results to display.

As you can see, this module is capable of supporting horizontal and vertical rendering, table or div based rendering. If you want to get even more creative, you can include the right jQuery and make a product carousal or flip book. (If you do, please send me a link. I would like to see it!) I tried to keep the module as flexible as possible in the hope that everyone who wants to use this module will be able to customize it to fix the style and layout of their site.

Some additional notes about this module: it’s fully localized, even the default settings are localized. However, currently English is the only option. If anyone produces a translated resource file, let me know, and I'll include it in the package. The minimum required version of the DNN platform is 5.1.0. The minimum required version of the .NET platform is 3.5. The module is Azure compatible and passes EVS without error or warning.

The latest release of the module can be downloaded here:

The source code is available on GitHub here:

Anyone who is interested in making enhancements to the module is welcome to fork the code on GitHub. Any questions or issues with the module can be sent to me directly at [email protected]. If you would like more information about the DNN Store referral program, please check out this page:

Leave your comment