Salmon version 4

A complete rework of the JS framework.

Whether you are new to Salmon or were using a previous version, V4 is aimed at keeping things easy while adding further mechanisms. Concepts are still the same as they were in previous versions, and of course we tested and insured it won't break code you may have made with prior versions.

1)The Salmon base model

The base model is for the client application to interact with the server. In most cases this is querying the server to retrieve data. This is done though the helper -> getData -> behavior concept. An helper function prepare the query, the getData function handle the request to server, the behavior function do something with the data returned from server.

Helper functions are pre-made, to assist with general cases and help you get started quickly, however of course you may develop your own helpers functions. The getData and behavior core functions form what we call the engine and should not be modified. However, you may create your own behavior functions to be called from the engine. We will get back on this later.

For now, let see a simple example how the base model is implemented and how to use it.

For this we will use an example helper function as bellow:

function e2c_4_example_helper() {
    var he = new e2c_engine();
    he.E2C.commons.apidata = "t=items";
    he.E2C.commons.bcode = 20;
    var ret = he.E2C.commons.getData();
    ret.done(function(data) { 
      //do something here
      alert("I got some data from server.");
    }); 
}

In this helper example, we are creating a new Salmon engine instance, and set its commons apidata variable to "t=items" and bcode to 20. Then we call the engine getData function. As we will see later, there are many more variables we could have set, however for now we will use default settings except for the apidata and bcode.

The apidata is a set of query parameters to be sent to the server. You don't need to understand each of them now. You can always refer to the API documentation later. The bcode is the number which identify the behavior you want to be executed with the data that is returned from server. In most cases, it will be behavior number 20, or B20 for short. Just keep in mind, there are pre-set behaviors in the engine, and they should not be modified, but you may add your very own custom behaviors.

So, let rather keep focused on the base model itself for now.

What we did exactly with our example helper is we said to query the server with some parameters, and to execute behavior 20 with the data the server returned. That's all. This is the helper -> getData -> behavior concept. What will be done with the data itself pretty much rely on which behavior you did set. Here, B20 mainly serve the purpose to populate the web page with the data, something we will demonstrate further bellow.

Because the behavior will take care of whatever we want done with the data, we are not obliged to have a ret.done() part, but in the example above we wanted to show some message upon getting the data. Indeed, we could have set the engine with a callback function to be executed along specific parameters for that function. To do so we would have set the engine callbackfunc and cbfparams variables, such as bellow:

function e2c_4_example_helper() {
    var he = new e2c_engine();
    he.E2C.commons.apidata = "t=items";
    he.E2C.commons.bcode = 20;
    he.E2C.commons.callbackfunc = my_callback_function;
    he.E2C.commons.cbfparams = ["Hello","blabla"];
    he.E2C.commons.getData();
    } 

function my_callback_function(arr){
alert(arr[0]);
}

The helper -> getData -> behavior concept itself is pretty simple. The more you will use it, the more simple you will see it. It waves most complications from you.

2)The Salmon engine

The engine is made of the getData and behavior parts of the Salmon base model.

The engine itself is constructed with the code bellow in e2c.js:

var e2c_engine = function() {
    var E2C = E2C || {};
    E2C.commons = {
        apiname: "e2cList", apidata: "", bcode: 20, subbcode: 0,
        gdmethod: 1, xdata: null, docache: false, turl: "",
        callbackfunc: null, cbfparams: null, dor: true,
        getData: function() {
            var x = e2c_getData(this);
            //x.done(function(data) { }); //for future use
            return x;
        }
    };
    this.E2C = E2C;
};

You can see the variables. We may and likely will, add more. Your app may also declare more, but you should not modify the e2c.js code itself. Never. If you ever need to extend e2c.js, do so in a separate file.

- apiname: the name of the server end point to be queried, as per API documentation
- apidata: the query parameters relevant to the apiname
- bcode: the number identifying the behavior function to be executed with data returned from server
- subbcode: the number identifying the subsection of a behavior to be executed
- gmethod: the method how to get data from server (1 for json, 2 for jsonp) or locally (3 for local json)
- xdata: some parameters for the behavior execution
- docache: whether or not to cache the ajax query
- turl: the url of the server and apiname (rare usage)
- callbackfunc: the function to be executed after the behavior returns
- cbfparams: the params for the callback function
- dor: whether or not to return the ajax object to the calling helper
- getData: the getData part of the engine

You may view the e2c_getData() function in e2c.js if you want. But, mainly what it does is handling the request to server and forwarding the returned data to the behavior function.

Just remember to instantiate the engine from your helper functions. This is what we have done in our helper example: new e2c_engine() . Though tempting, do not instantiate it as a global variable in your web app. Most ajax calls are asynchronous and even so you may run into various, hard to debug issues. Let your helper create a new instance each time it needs to call the API. There are ways to store and access data, such as Salmon client caches, which will be covered later.

3)The core behaviors

As we wrote earlier, core behaviors should not be modified because they are part of the Salmon engine. That is, they are the foundation of most uses an application makes of data it receive from the server. We will describe bellow the core behaviors system and how to add your owns.

Behaviors are all handled by the e2c_behavior() function in e2c.js . Mainly, it says:

function e2c_behavior(status, data, textStatus, e){
 if (e.bcode == 1) {
       if(e.subbcode == 1){ //do this and that }
       if(e.subbcode == 2){ //do this and that }
       and so on ...
    }
 if (e.bcode == 2) {
       if(e.subbcode == 1){ //do this and that }
       if(e.subbcode == 2){ //do this and that }
       and so on ...
    }
and so on ...
}

Pretty simple, isn't it?

Thus, you may execute any behavior by setting its number as bcode variable of the engine. And for a said behavior you may have the option to even set a subbcode to execute specific code within a said behavior.

The core behaviors where really many in the first Salmon version. With time we moved most of them into a single one, the behavior with bcode 20, which we like to refer to as the B20. B20 handles most complex operations of rendering the data on a web page, and many consequent mechanisms. It also handles calling data without rendering it, which has its own use. Ultimately, all remaining core behaviors will remain into B20 only.

Honestly, you don't need to dig into the core behaviors code, and surely not the B20. You may, of course, if you have ample time to spare. But what you really need is to understand that by calling a particular behavior the data will be processed to achieve a certain goal. For example, if bcode is set to 20, you will be able to populate the web page with the data.

For now, what you need to remember is that:

bcode up to 4000 are reserved for the Salmon engine.
bcode from 4001 to 5000 are for your own use.

Although we do not believe you will ever need to create your own behavior function, but rather rely on core pre-made ones, it's there for you to freely extend.

That is, if you ever want to use your very own behavior function, you will need to provide the engine a bcode between 4001 and 5000. Also, you will need to create a function named e2c_my_behavior(), outside of e2c.js of course.

function e2c_my_behavior(status, data, textStatus, e){
if(e.bcode == 4001){//do this and that}
and so on ... up to 
if(e.bcode == 5000){//do this and that}
}

All functions that Salmon expect you may create for your own use as an extension of e2c.js existing functions starts with e2c_my_ instead of e2c_ alone.

By the way, have you noticed that e2c_behavior() got the engine object as the e parameter? Yep, the engine instance is there for you to use anytime.

What have we covered so far?

Every Salmon web application follows a model which is helper -> getData -> behavior
How to make a basic helper and have it instantiate the Salmon engine
How to set the Salmon engine variables to be used by getData and behaviors
How to trigger the execution of a specific behavior by its bcode