Salmon by Code Examples - Integration Example 1

This page is to help developers quickly get started with Salmon. Salmon is all about simplicity. To that end, you can expect simple documentation and examples.

The average Salmon learning curve is less than one hour. Many developers can start working with the framework in as little as 30 minutes.

We assume that you are starting with an HTML mock-up site or an HTML template. But you can also see the Salmon online demo store to view this example in a live environment.

1) Placing e2c.js In Your Pages

In your HTML template, there will be distinct pages, each representing various steps of a customer's online shopping experience. You'll have a home page, a category listing page, a product detail page, the shopping cart, and the checkout page, and so on, as your web site project's needs demand. On each page, load the e2c.js client-side JavaScript file.

<script type="text/javascript" src="path/e2c.js"></script>

2) Preparing DOM Element IDs for Salmon

Though Salmon will populate your HTML pages with relevant data, such as categories listing, product information, cart content etc, you need to let Salmon know where you would like such data to be placed on your pages. The example below shows how to populate a product description, but the approach is the same to place other data on your pages.

Let say you have code that looks about below:

<div class="product">
  <div>Product Title</div>
  <div>Product Description</div>
  <div>Product Price</div>
</div>

Now you would simply add Salmon relevant IDs so your code as below:

<div class="product">
  <div id="e2cname">Product Title</div>
  <div id="e2cdescription">Product Description</div>
  <div id="e2cprice">Product Price</div>
</div>

The ID name is made of a prefix and a string. For example, in e2cname above, e2c is the prefix and name is the string. The prefix can be set to whatever string you want to help you quickly identify Salmon related blocks of code in your page. As a convention, we recommend using prefixes that start with e2c, such as e2ccategories, e2cproduct, e2ccart, and so on, but it is really up to you.

The string part of the ID must be identical to the data table column name in your database, because Salmon will retrieve data as JSON formatted key:value pairs before it iterates though it and populates your DOM elements.

In the JSON bellow, items is the database table name, while name description and price are that table columns names. The JSON keys are the columns names.

{"items:"[{'name":"somename1",'description':"somedescription1",'price':"someprice1"},{'name":"somename2",'description':"somedescription2",'price':"someprice2"},{'name":"somename3",'description':"somedescription3",'price':"someprice3"}...]}

3) Call Salmon JS Function to Populate the DOM Elements

Now that you have prepared your DOM elements, it is time to dynamically populate them with the relevant data.

In this example, we will populate only one product DIV, the <div class="product"> above, but the approach is similar to populating multiple spaces such as categories, listing, cart etc. The Salmon client-side JavaScript file e2c.js has prepared functions and helpers, to make common tasks easy to integrate.

Here we will use the helper function getItem(itemref) which will return to us the item with reference itemRef. If itemRef is empty, Salmon will return a random item.

In your HTML page HEAD section, you could place code such as:

<script>
$(document).ready(function() {
  e2c_getItem('');
});
</script>

Now your <div class="product"> has been populated with a random product. This is because when you called the function getItem(), Salmon handled the Ajax call for you, gathering the item data (here a random item), parsing the JSON key:value pairs, and populating data on your DOM.

4) Using Behaviors to Manipulate the DOM

Obviously, you will want to do more complex tasks than just populating a single product DIV. Now we will show you how to populate a product listing and demonstrate Salmon behaviors.

When you ask Salmon to retrieve data, though a helper function, for example, Salmon will handle the Ajax process for you and retrieve a JSON formatted object. This object is now ready for processing. You can now do whatever you want with that JSON data object. In Salmon scripting, a behavior will handle this object. You can either define what you want to do with the data, or you can use one of the preset behaviors to handle typical operations.

In this example, we will use a behavior that is able to list a categories products and format it with some HTML.

Behaviors are defined in the e2c_behavior(bcode, status, data, textStatus) function in e2c.js.

The parameters are:

Generally, you'll only care about the bcode and data.

Naturally, if you had used an helper function, it would have transparently passed the relevant bcode to the e2c_behavior function. This way the relevant behavior will be executed.

function e2c_behavior(bcode, status, data, textStatus) {
  if (bcode==1) {
    // behavior 1
    if (status=="s") {}
    if (status=="e") {}
  }
  if(bcode==2) {
    //behavior 2
    if (status=="s") {}
    if (status=="e") {}
  }
  ... and so on
}

If the bcode was '1', it would execute behavior 1. If the bcode was '2', it would execute behavior 2, and so on.

The status == "s" decides what to do if the Ajax request was successful, while status == "e" handles what happens if there was an error.

For example, you may want to alert a specific error message when an error occurs. Anything you want can be done on either success or error. This is great for developers because you can simply do what you want with the JSON data. In most cases, you will want to iterate though it and populate some DOM on your page.

We said we would do a category products listing. For this, we can use the helper e2c_ListItems(categoryID). This triggers the behavior 3 (bcode==3 in the e2c_behavior function).

On Ajax success, it starts with:

var items = data.items;
$('#e2cprods').html("");

Here, data.items is the first array in JSON, which is the database table. e2cprods is a DIV on the target web page where we will later render the products listing.

Then, this behavior will iterate though the items array:

for(var key in object) {
  ... do something
}

The 'do something' could be as simple as:

Which would result in listing all returned products each in its own individual DIV within the container DIV e2cprods.

If you look at behavior 3 of Salmon demo store, this is exactly what we do.

- For each item in items array we set content and add it to e2cprods.

var content=''+'<li>'+'<a id="e2citemIDlink'+i+'" href=""><img class="prodlist" id="e2cpics'+i+'" src="images/img1.gif" alt="" /></a>'+'<p class="title" id="e2cname'+i+'"></p>'+'<p>#<span id="e2citemID'+i+'"></span> <span class="price bold">$</span> <span id="e2cprice'+i+'" class="price bold"></span></p>'+'<a id="e2ccartproductID'+i+'" href="" class="button"><span>Buy Now</span></a>'+'</li>';
lnav=lnav+content; $('#e2cprods').html(lnav);

- Then populate with relevant values.

if(key!="reference") {
  if(key=="pics") {
    var epic=pics_prod_th+object[key]; $('#'+eid2).attr("src",epic);
  } else {
    $('#'+eid2).html(object[key]);
  }
}

Rather then preparing the individual DOM IDs for each data as in the getItem example above, here we are just placing in our page the e2cprods DIV  (<div id="e2cprods"></div>), and define its HTML inside the behavior.