Creating a RelatedProductsBox custom control

This guide explains how to create a custom DataList to show a box with products related to the content of a page using a specific set of keywords, a bit like Google AdSense if you want. Here is a screenshot of what the example box looks like.

Using AmazonECS.Net, this kind of control is very easy to create and implement. The following lines explain how to create the control and how to use it in your pages. You can download the control source code and example here.

Requirements

In order to use AmazonECS.Net, you need to register for an Amazon Subscription Id (now called Access Key) to use the library. It is an essential step that will enable you to use Amazon services.

Also, in order to make money, you will need an Amazon associate tag which you can obtain here. This step is optional but suggested.

Creating the RelatedProductsBox custom control

As mentioned before, our custom control will inherit from the DataList server control. We will add a few properties to the control and only one method. So, the first step is to create a Web Control Library named RelatedProductsBox inheriting a DataList and add a reference to the AmazonECS.Net library (Matizha.AmazonECS.Net.dll). Then, we need to add a reference to the Matizha.AmazonECSNet.WebServices namespace.

Adding the properties

We need to add 5 properties to our new control:

• Keywords: what the products should be related to.
• Size: the number of products to list in the box.
• SearchIndex: the category where to search the products (using the SearchIndex enum from AmazonECS.Net)
• AssociateTag: Amazon associate tag.
• SubscriptionId: Amazon subscription id required for all requests to Amazon webservices.

Also, make sure to add Designer support for the properties, it will be easier to configure your custom control later.

Your code should now look like something like this:

using System;
using System.Data;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.ComponentModel;
using Matizha.AmazonECSNet.WebServices;

namespace Matizha.AmazonECSNet.CustomControls
{
    /// <summary>
    /// Summary description for RelatedProductsBox.
    /// </summary>
    [ToolboxData("<{0}:RelatedProductsBox runat=server></{0}:RelatedProductsBox>")]
    public class RelatedProductsBox : System.Web.UI.WebControls.DataList
    {
        private string keywords;
        private string associateTag = "webservices-20";
        private string subscriptionId;
        private int size = 3;
        private SearchIndex searchIndex = SearchIndex.Blended;

        [Category("Keywords"),
        DefaultValue(""),
        Description("Keywords to which the products should be related to.")]
        public string Keywords
        {
            get
            {
                return keywords;
            }

            set
            {
                keywords = value;
            }
        }

        [Browsable(false)]
        public string AssociateTag
        {
            get
            {
                return associateTag;
            }

            set
            {
                associateTag = value;
            }
        }

        [Browsable(false)]
        public string SubscriptionId
        {
            get
            {
                return subscriptionId;
            }

            set
            {
                subscriptionId = value;
            }
        }

        [Category("Search Index"),
        DefaultValue(SearchIndex.Blended),
        Description("The category in which to search for the products.")]
        public SearchIndex SearchIndex
        {
            get
            {
                return searchIndex;
            }

            set
            {
                searchIndex = value;
            }
        }

        [Category("Size"),
        DefaultValue(3),
        Description("The number of products to list in the box.")]
        public int Size
        {
            get
            {
                return size;
            }

            set
            {
                size = value;
            }
        }
    }
}

Adding the method that will fill the box

All we have to do now is create a method that will send the request to Amazon and automatically load the data using the specified properties. Let’s call this method FillProductsBox.

Making the request is pretty straight forward. We use the search request from AmazonECS.Net. We specify the necessary properties and then call the Search method of SearchRequest. The true parameter specifies that the result to the request will be cached (using ASP.Net Caching) and that if the same request is made within the next 24 hours, it will be loaded from cache instead.

[...]

SearchRequest rq = new SearchRequest();

rq.SubscriptionId = this.subscriptionId;
rq.AssociateTag = this.associateTag;

rq.Keywords = this.keywords;
rq.ItemPage = "1";
rq.SearchIndex = this.searchIndex;

Items items = rq.Search(true);

[...]

Once the request is made, we should have a set of items related to the keywords specified. The next step is to create a DataTable to store our product descriptions. In this control, I only created columns for the most generic item properties (price, availability, etc.) so it can be used with almost any search index or with a blended search without any problem. If you know you will only use the control with a particular category, like DVD, then you could add columns for the properties used in DVD. For instance, you could add columns for ReleaseDate or AudienceRating.

Also, most requests will return 10 items (or less), so we have to limit the number of products to bind to the size specified.

Finally, all there is left to do is to automatically bind our DataTable to our custom control using a DataView. Here is the full listing for the method:

public void FillProductsBox()
{
    SearchRequest rq = new SearchRequest();

    rq.SubscriptionId = this.subscriptionId;
    rq.AssociateTag = this.associateTag;

    rq.Keywords = this.keywords;
    rq.ItemPage = "1";
    rq.SearchIndex = this.searchIndex;

    Items items = rq.Search(true);

    if ( items != null )
    {
        Item [] itemArray = items.Item;
        if ( itemArray != null )
        {
            DataTable productTable = new DataTable();
            productTable.Columns.Add(new DataColumn("Title", typeof(string)));
            productTable.Columns.Add(new DataColumn("Availability", typeof(string)));
            productTable.Columns.Add(new DataColumn("SmallImage", typeof(string)));
            productTable.Columns.Add(new DataColumn("AmazonPrice", typeof(string)));
            productTable.Columns.Add(new DataColumn("DetailPageURL", typeof(string)));

            int maxIndex = itemArray.Length;
            if (itemArray.Length > this.size) maxIndex = this.size;

            for ( int i = 0; i < maxIndex; i++ )
            {
                Item item = itemArray[i];
                DataRow row = productTable.NewRow();

                if (item.ItemAttributes.Title != null)
                    row["Title"] = item.ItemAttributes.Title;

                if (item.SmallImage != null)
                    row["SmallImage"] = item.SmallImage.URL;

                if (item.DetailPageURL != null)
                    row["DetailPageURL"] = item.DetailPageURL;

                if (item.Offers != null)
                {
                    Offer [] offerArray  = item.Offers.Offer;
                    if (offerArray != null)
                    {
                        if (offerArray[0].OfferListing != null)
                        {
                            if (offerArray[0].OfferListing[0].Price != null)
                                row["AmazonPrice"] = offerArray[0].OfferListing[0].Price.FormattedPrice;
                            if (offerArray[0].OfferListing[0].Availability != null)
                                row["Availability"] = offerArray[0].OfferListing[0].Availability;
                        }
                    }
                }

                productTable.Rows.Add(row);
            } 

            DataView dv = new DataView(productTable);
            this.DataSource = dv;
            this.DataBind();
        }
    }
}

That’s it! We now have a simple control based on AmazonECS.Net that shows products related to the specified keyword.

Using the RelatedProductsBox

To use your new custom control in an application, you need to add a reference to the assembly file of your control. In the above example, the assembly was Matizha.AmazonECS.Net.CustomControls.dll.

Adding the control to your page

Then, at the top of the page you want to use the box in, you need to register the control like this:

<%@ Register TagPrefix="ecs" Namespace="Matizha.AmazonECSNet.CustomControls"
Assembly="Matizha.AmazonECS.Net.CustomControls" %>

Then, somewhere in your form, you have insert your control. You can modify most of the control properties using the Designer. Also, it can be used to see the list of all the available SearchIndexes. To search in all categories at once, use the Blended SearchIndex. Customize the ItemTemplate content as you need. Also, I included the corresponding CSS classes in the example package.

<ecs:relatedproductsbox id="relatedbox" runat="server"
    searchindex="Books"
    keywords="ASP.Net"
    repeatdirection="Horizontal"
    cssclass="box"
    cellpadding="0"
    horizontalalign="Center">

    <itemtemplate>
        <a href='<%# DataBinder.Eval(Container, "DataItem.DetailPageURL") %>'>
            <%# DataBinder.Eval(Container, "DataItem.Title") %>
        </a>
        <br>
        <p><a href='<%# DataBinder.Eval(Container, "DataItem.DetailPageURL") %>'>
        <img src='<%# DataBinder.Eval(Container, "DataItem.SmallImage") %>' border="0" align="left"></a>
            <b>Availability</b><br>
            <%# DataBinder.Eval(Container, "DataItem.Availability") %>
        </p>
        <p><b>Price</b><br>
            <span class="price">
                <%# DataBinder.Eval(Container, "DataItem.AmazonPrice") %>
            </span>
        </p>
    </itemtemplate>

    <headertemplate>
        Suggested ASP.Net Books
    </headertemplate>
    <itemstyle cssclass="itemtemplate"></itemstyle>
    <headerstyle cssclass="headertemplate"></headerstyle>
</ecs:relatedproductsbox>

Code-Behind

Finally, in the code-behind of your page, you need to call the FillProductsBox method somewhere after you specified your subscription id and associate tag. Most of the time, you should call it in the Page_Load event. Also, make sure you replace the question marks with your own subscription id. If you want to be rewarded money for your referals, specify your own associate tag, otherwise, you can use the default one.

protected Matizha.AmazonECSNet.CustomControls.RelatedProductsBox relatedbox;

private void Page_Load(object sender, System.EventArgs e)
{
    if (!Page.IsPostBack)
    {
        relatedbox.SubscriptionId = "????????????????????";
        relatedbox.AssociateTag = "webservices-20";
        relatedbox.FillProductsBox();
    }
}

That’s it! You can download the full source code and example. Feel free to modify and improve it as much as you need. You can also send your comments here.