Chains
All chains are a list of callback functions that can be manipulated at any point in the execution. As objects are sent as a reference to a function we utilize this core js functionality to achieve the desired effect.
Klevu framework uses chains for:
- control the flow of a search instance – check search instance scope for the predefined chains
- control of the core loading events – refer to Klevu Events docs
- custom event executions – refer to Klevu Events docs
The concept of Chaining is derived from the promise and callback concepts in JS with some differences.
The Klevu chains where designed to work in same way callbacks work in that they are executed at a specific point in the code and will loop through a list of previously defined functions. Depending on the settings used at the time of creation of the chain any function in that chain can stop execution of future ones and return the edited result.
They are mainly used to manipulate a data object that is attached to a specific scope, both of which are being passed as object references.
The main between callbacks and chains is that , because the chains are mainly use to manipulate data the order functions that make up that chain are executed is important and so the chains will have the possibility to change the order, remove or add functions at any point in the execution chain.
Example of a chain and what can be done with the use of interfaces:
We have function A , B , C , D that have to be executed in that order and are added to the chain that was created , there execution will be as follows:
A | B | C | D
If we insert E with the addBefore B we will get an execution of
A |E| B | C | D
If we insert F with the add we will get an execution of
A | B | C | D |F
This allows for grater flexibility in the order of execution and more granulation of the code.
To utilize a chain first it has to be created , to achieve this the following core interface has to be used:
- stopOnFalse – true/false . default false – the chain execution will stop when any element in the chain returns false
- spacer – numeric, default 10, the distance between the automatically added elements
- add (chainElement) – adds a new element to the chain at the end of it
- addAfter (name , chainElement) – adds a new element after the element with a specific name.
- addBefore (name , chainElement) – adds a new element before the element with a specific name.
- move – responsible for the moving of an element , accepts an object with following attributes
- name – required – the name of the element to move
- before – optional – if element has to be moved before a specific element
- after – optional – if element has to be moved after a specific element
- list – retrieve a list of all the existing elements in the chain
- hasData – checks if data object is set
- getData – returns data object
- setData – sets new data object – this has to always be an object type
- hasScope – checks if scope object is set
- getScope – returns scope object
- setScope – sets new scope object – this has to always be an object type
- getOptions – retrieve core options and declarations of the chain
Chain elements are attached to chains. These elements are the callback functions to be executed. Some extra options allow the modification of order the callback functions have at the time of execution.
A chain element has the following possible parameters:
- name: <str> – defines name of the element, it has to be unique per chain
- position: <numeric> – optional , defines the position of the element
- fire: <function Source> – defines what needs to be executed, accepts 2 variables, data and scope of the chain
.
