azendal edited this page Jul 18, 2011 · 2 revisions
Clone this wiki locally

Samarium is a StateMachine to help track complex state in an application, especially loading of information in an asynchronous way. To do this, Samarium splits the problem into smaller State Machines.

Samarium Initialize

var Sm = new Samarium.Manager();

This will give you access to the full set of features that Samarium offers.

Samarium Hello World

var  Sm = new Samarium.Manager();
	console.log(‘Hello World’);
Sm.link($(document).ready ,'Dom:Loaded);

This allows you to listen to jQuery Dom Ready event and trigger a state and resolve functions after this event. This might seems as lot of boiler plate for document ready, but it has some advantage. Now you can ask Samarium if Dom is Loaded.


And get a true, also you will be able to get write Sm.after event if the event has happened already and to have the function executed immediately, because Dom is already loaded.

Api Description

The Api of Samarium is divided into 3 big parts and some extra features.

Notification Api

Unique: Sets a new State that is unique, this is helpful for knowing if the event in the application already happened.
Trigger(Should change name to something like enterState or just enter): Sets a State in the application, this will count the amount of times that the application has entered this state.
SetName: You can add a name to a bunch of states into another.

Sm.after('Dom:loaded', 'Page:loaded','Field:loaded').setName('Loader')
setName can be chained by each and then or used elsewhere with event Completed.
console.log('Loader is completed');

State Api

After: This method will create a Samarium promise that will be able to notify on each change of state and also will notify once al states have happen.
Once: The same as after but it only happens ones. This is probably a better option to use on unique states.
Each: This will allow having a function executed every time a change of state happens.
Then: This will allows having a function resolve once all states have been achieved.

State Reporting

Intance: will return the name of all state factories in a particular moment, quite usefull for debugging the status in a particular moment.
Is: will check the information of a particular state, if is unique returns true, if its trigger returns the amount of times that have been triggered and if it hasn’t been use returns false
isUnique: will return if a particular state is unique

Extra Features

Link: Samarium offers a way to link external events into a Samarium State using linking.
Sm.link($(document).ready ,'Dom:Ready');
Link by default will set events as unique, to avoid this use
Sm.link($(document).ready ,'Dom:Ready',false);
Considering changing it to
Sm.link($(document), ‘ready’ ,'Dom:Ready',false);
to hook to the bind function of jQuery more easily.

While using samarium everything is created from the Manager, it has 2 other “clases”, Samarium Promise and Samarium State Factory.
At any point that you create set of states to connect to, Samarium will return the promise that you can ask for its state at any moment.

var promise = Sm.after('Dom:loaded', 'Page:loaded','Field:loaded');

At any point you can as Samarium for a particular State Factory with Sm.get and then ask for its status.
This 2 methods do deep cloning of the object so you get a the status at any moment.