Cilantro has support for sessions corresponding to separate API endpoints. When a session is opened, it makes a request to the root endpoint of the target API, say /api/, and waits for a response which contains details such as the title, version and links to all the data resources. Cilantro will expose only the features that correspond to the resources available by the endpoint. This discovery process is as HATEOAS and drives the application's behavior.

Auto-Session

Cilantro's configuration options supports pre-defining the default session by providing a url and optional credentials. When Cilantro loads, the session will be auto-created and if autoload is true (the default), the session will immediately start. For most applications this is the recommendeded way for defining the default session.

Managing Sessions

Cilantro defines a session manager whose job is to keep track of sessions by their endpoint and can be accessed at cilantro.sessions. It is also the primary interface for opening and closing sessions.

Open Session

Takes a url and optional credentials object for endpoints that require authentication.

// Opens and starts new session. This will end the active session if one
// exists and the new session opens successfully
c.sessions.open('/api/');

// Session with a full URL and credentials
c.sessions.open('https://example.com/api/', {
    username: 'user',
    password: 's3kr1t'
});

// Opening a session already opened will cause a session switch to
// occur. Connection information is saved for the duration of the
// browser session for convenience.
c.sessions.open('/api/')
c.sessions.open('https://example.com/api/')

Close Session

// Close the current session
c.sessions.close();

Events

Events are triggered by the session manager during the lifecycle of a session. Every event gets at least the url for the session the event applies to.

  • opening - The request has been sent to the API endpoint.
  • open - The session has been successfully opened.
  • start - The session has been started which involves initialization and rendering of the UI.
  • end - The session ended which involves removing rendered components from the UI
  • close - The session has been closed. Closed sessions need to be opened before being started again.
  • error - An error occurred while opening the session. This is typically due to failed authentication. In addition to the url, the error that occurred is also passed into the event handler.
  • all - Bind to this event to trigger the handler for all session events. The first parameter is the event name followed by the data for that event

For example, a handler could be defined that echos the state of the session:

var statuses = {
    'opening': 'Opening',
    'open': 'Opened',
    'start': 'Started',
    'end': 'Ended',
    'close': 'Closed',
    'error': 'An error occurred'
};

c.sessions.on('all', function(event, url) {
    var text = statuses[event] + ' ' + url;
    $('#session-status').text(text);
});