Introduction to Salmon integration

A simple introduction to Salmon for web developers

Salmon is our brand new, innovative platform.

Salmon is a software solution aimed primarily at eCommerce, though its capabilities are ideal for many other types of sites. It is easier¹ and cheaper², from idea to deployment, compared to other popular solutions (i.e. Magento, osCommerce, VirtueMart, etc.), comes with a flexible and robust API, provides lighting fast content delivery, and has built-in SEO boosting features.

¹ Salmon is all about simplicity. You don't need advanced or special skills. Basic HTML knowledge, as you would use with any other site, is enough to start using Salmon. As with any other solution, having some knowledge of JavaScript will allow you to take further advantage of Salmon's powerful features and customization features.

² Salmon is cost-effective and time saving. Because Salmon is already simplified for integration, common eCommerce features can be loaded with a simple JavaScript function call at the document onload event. This means fewer developer hours and reduced cost necessary to build and deploy an initial site from an HTML mock-up or template. Updating and maintaining a site will be considerably easier, too.

You will not need to be exposed to Salmon's server-side code itself to make use of its powerful client-side JavaScript-based API.

Most eCommerce related functions are already built for you, accessible in easy to use client-side JavaScript API that can be easily modified. Salmon comes with its own client-side JavaScript file, called e2c.js, that contains preset functions that you can use 'as is'. If you choose, you can modify them to suit your own needs. Only a basic understanding of JavaScript is required to make use of these functions, so you don't have to be an expert to use them.

Developers that have previous experience with Magento will appreciate how fast, easy, and intuitive it is to work with Salmon.

Loading the details of a product on a page is as simple as placing a single JavaScript call in the HTML.

Just load e2c.js in the <head></head> section of your page, then call a preset JavaScript Salmon function. Salmon will render the relevant data in your web page DOM, handling all complex operations in the background automatically.

A) Helper and Behavior Functions

Helper functions are simply functions that prepare a query to be sent, via Ajax, to the Salmon powered server, which will return the relevant data. This data is then manipulated by a behavior function. A behavior function determines how to process that data, such as outputting it on your web page. The Ajax process is handled for you though a function named e2c_getData().

Typically, an Salmon process will be made of 3 steps such as: 1 some helper function 2 e2c_getData() 3 some behavior function.

B) Salmon API Abstraction

An included helper function will help you build queries to the Salmon API, including all necessary parameters. Using the power of the built-in helper functions, you don't need to delve too deeply into the Salmon API itself. Naturally you can, if you want, but more then 90% of operations can be accomplished using just helpers.

An example of an helper is the client-side JavaScript function e2c_getItem(itemRef) in e2c.js. Just calling this function on page load or in a link will populate the relevant DOM in your page.

C) DOM Elements Configuration

Salmon will need to know where you want the data that it outputs. Most client-side calls that display data to the user will require the ID of the containing element (i.e. <div>, <span> ...). Consider this example:

<div id="e2c_product">

The e2c portion of the ID of the element is the prefix, and the second part after the underscore, product, is its name.

The containing element is referred to as the container, and the elements to be populated are its children.

<div id="e2c_product">
<p>Product name: <span id="e2c_name"></span></p>
<p>Product price: <span id="e2_cprice"></span></p>
<p>Product description: <span id="e2c_description"></span></p>
</div>

In the example above, the container is e2c_product, while the 3 <span> elements are its children.

There are a few things to consider. First, the naming of the containers should be consistent with the naming scheme that you provide to the behavior that you will use. Of course, you can always edit this later. Secondly, the children naming scheme should correspond to the columns of the table in the database from which the results will be fetched.

This is explained in further detail in Salmon data, but you should first understand the concepts that we explain in the present introduction.

D) Editing Helpers and Behaviors

Since all of these JavaScript Salmon functions are in e2c.js, you have total control of them, and can modify what they do. You can even add your own. If you are using a helper function, it has a bcode parameter which sets the behavior that should manipulate the data returned by the Salmon server.

function e2c_getItem(itemref) {
  var apidata='t=items&r=' + itemref;
  e2c_getData('e2cGet', apidata, '1');
}

In the example above, the e2c_getItem() helper function, e2cGet, is the Salmon API name that we will call to receive some data. apidata contains the parameter string to be appended to the query, and 1 is the behavior code which indicates the use of behavior number 1.

function e2c_behavior(bcode, status, data, textStatus, subbcode) {
  if (bcode==1) {
    .. do something, as this is behavior 1
  } if(bcode==2) {
      .. do something, as this is behavior 2
    } if (bcode==3) {
        .. do something, as this is behavior 3
      } ... and so on
}

Therefore, by editing the behavior 1, you can reset how you want the helper e2c_getItem to behave, or, more specifically, how it should handle the data that is returned by Salmon.

This is further explained in integration example 1, but you should first understand the concepts explained here.

A Few More Considerations

You would place getItem(the_product_reference_you_want_to_load) on a link or page load. This calls, via Ajax, that product's data from Salmon server, though getdata(), and executes the behavior that you passed as a parameter to getData()

Behaviors can be executed in many ways. It all depends what you want to achieve. As the old saying goes, there are many roads to Rome. The main idea of a behavior is to execute some process, such as populating a product page, updating the shopping cart, etc.

Since this is done client-side rather then server side, you take little risk with experimenting. The exception, of course, is when building an admin interface or a user account interface where you could accidentally create or delete data. But being a careful professional, you probably wouldn't have such issues. We naturally assume that you would not test in a production environment unless you are sure of what you are doing.

If you don't know JavaScript, you could use a predefined behavior in e2c.js, but with basic JavaScript skills you can easily modify behaviors to match your own expectations. Naturally, you can also write additional behaviors. This is a key point of Salmon - you can do what you want without having to understand, or change, the server-side code.

In short, just build your HTML pages as mock-ups, add Salmon IDs to DOM elements (for rendering data), call simple JavaScript at page load, and the Salmon server-side magic works for you, saving you time, coffee, and headaches.

Salmon behaviors tend to populate data on the web page, which is why it is important to set the relevant DOM elements so that such data can be rendered. For example, a page with DIV elements named e2c_name, e2c_price, and e2c_description, will have a JavaScript behavior that will update each of them with data.

Salmon data is returned as JSON by Salmon server. This has many advantages, including the ability to pass the data to additional libraries. For example, extJS uses this to render orders int a grid. Since you have complete control over the data, you can do with it as you wish.