Client side javascript library tutorial

In this tutorial we will be building up this demo page, demonstrating some features from the client side javascript library. It's a product detail page that contain a large product image, a gallery with alternative images and a list of recently viewed products.

Setting up

The html page

We start out with just a basic html page. On this page we will make a couple small affordances for the javascript library:

None of these things are design restrictions of the javascript library. They are just some things we find are easy to work with.

<html>
<head>
    <title>Farmaframe client library demo</title>
    <style>
        body {width:860px; margin:0 auto; font-size:120%;}
        .section {clear:both;}
        #detail-image{float:left; padding:10px;}
        ul {margin:0px; padding:0px; float:left;}
        li {display:block; float:left;margin:5px; }
        li a {background-color:#eee; padding:5px; display:block;}
        .footer {clear:both;border-top: 1px solid #aaa;font-size:80%;text-align:right;}
    </style>
</head>
<body>
    <h1>Client side library demo</h1>

    <div class="section">
        <h2>Rodisonic ultrasound 500 gel</h2>
        <img id="detail-image" data-product="391631" alt="No image available">
        <p>Product description goes here ...</p>
        <ul  id="detail-gallery"></ul>
    </div>

    <div class="section">
        <h2>Recently viewed products</h2>
        <ul>
            <li><a href="#"><img class="thumbnail" data-product="39172"></a></li>
            <li><a href="#"><img class="thumbnail" data-product="391631"></a></li>
            <li><a href="#"><img class="thumbnail" data-product="857995"></a></li>
        </ul>
    </div>
    
    <div class="footer">
        <p>Product images © <a href="http://pharma-photo.be/">Pharma-Photo</a></p>
    </div>
</body>
</html>

Initializing the client side library

Adding the farmaframe client library is as easy as adding two script tags: jquery and the client library itself.

<script type="text/javascript" src="jquery-1.9.1.min.js"></script>
<script type="text/javascript" src="http://api.farmaframe.be/v1/static/clientlib/farmaframe-api-1.0.0.js"></script>

Now let's initialize the client side library. To do this we pass an options object to the constructor containing our api key, our client key and our preferred language. Haven't got a client key yet, we've got some instructions here.

var api = new farmaframe.ImageApi({
    clientKey: 'mie-key', 
    apiKey: 'mie',
    language: farmaframe.LANGUAGES.NL
});

List of recently viewed products

We can now call methods on this api object to access the farmaframe api. To add thumbnail to the list of recently viewed products we will be using the getThumbnailUrl method. This method accepts a CNK code and a thumbnail size and returns a thumbnail url.

$('img.thumbnail').each(function() {
    var product = $(this).data('product');
    var url = api.getThumbnailUrl(product, farmaframe.IMAGE_SIZES.T_150);
    $(this).attr('src', url);
});

As you might notice this is mostly jquery code. The only line that accesses the api is line 3.

Image gallery for the main product

The large product image

To show full product images we offer more options, so it is also slightly more complex. First we will use the getImages method to fetch an image listing for a product (a ProductImages object). There are some things we need to pay attention to here:

var imageNode = $('#farmaframe-detail-image');

api.getImages(imageNode.data('product'))
.done(function(listings) {
    if (listings.length > 0) {
        var listing = listings[0];		
		
        // Set the url for the big image
        imageNode.attr('src', listing.getPrimaryImage().getUrl(farmaframe.IMAGE_SIZES.F_500));
    }
});

The gallery of alternative images

Adding the gallery of alternative images is easy now. We have already retrieved the full image listing for the products so now it is simply a matter of iterating over the images and generating the appropriate html. Here's the same code again, this time with gallery generation added in.

var imageNode = $('#farmaframe-detail-image');

api.getImages(imageNode.data('product'))
.done(function(listings) {
    if (listings.length > 0) {
        var listing = listings[0];		
		
        // Set the url for the big image
        imageNode.attr('src', listing.getPrimaryImage().getUrl(farmaframe.IMAGE_SIZES.F_500));
		
        // Cycle through all the images and add a thumbnail node 
        var html = "";
        var images = listing.getImages();
        for (var i=0; i < images.length; i++) {
            var image = images[i];
            html += '<li><a href="'
                 + image.getUrl(farmaframe.IMAGE_SIZES.F_500)
                 + '" onMouseOver="$(\'#farmaframe-detail-image\').attr(\'src\', \''
                 + image.getUrl(farmaframe.IMAGE_SIZES.F_500)
                 + '\');"><img src="'
                 + image.getUrl(farmaframe.IMAGE_SIZES.T_150) 
                 + '" ></a></li>';
        }
        $('#farmaframe-detail-gallery').html(html);
    }
});

Error handling

Like usual on the internet, a lot of things can go wrong that aren't under your control. An api call like getImages is one of them. And even though we try not to make a habit of being down or unavailable, it might not hurt for you to make a habit out of handling an occasional failure on our end.

Because error handling is extremely use case specific we've limited ourselves to just the basics here. There's nothing farmaframe api specific here, just generic error handling for all things async and jquery.

.fail(function() {
	imageNode.attr('alt', "We're sorry, product photos aren't available right now. Please try again in a couple minutes.")
});

All done

And that is all that is needed for our demo page. Feel free to do a "view source" on that page. It's got all the snippets shown here tied together, with some extra comments summarizing the important points of this tutorial.