JSMF - JavaScript State Management Framework

JSMF - JavaScript State Management Framework

What is JSMF? (TOP)

JSMF (JavaScript State Management Framework) provides your web-based applications with a comprehensive mechanism to maintain state. This solution is made possible by utilizing frames (standard and inline), forms, DHTML and an OO (object oriented) JavaScript API. The API provides a standardized way to read, write, and persist session data.

Why do I need to maintain state? (TOP)

During the lifetime of a session within a web-based application, it's often necessary to save and retrieve a particular set of variables. After a webpage performs a form POST or GET, the variables you wish to save will need to be regenerated again server-side and, more than likely, stored as hidden form variables in the subsequent page. These variables may be required across multiple pages in order to identify a particular user, order, or to present a final confirmation page in a wizard-style application flow.

Table of Contents

	What is JSMF?
	Why do I need to maintain state?
	What is unique about JSMF?
	What are the benefits of using JSMF?
	Getting Started
	Test Engine
	API
	Browser Compatibility
	Download
	Feedback

What is unique about JSMF? (TOP)

JSMF leverages existing client-side technologies (frames, forms, DHTML, and JavaScript) to accomplish state management. Developers have been using very similar techniques with hidden frames and cookies over the years. But, what JSMF does is combine these techniques and provides a simple to use API that abstracts much of the JavaScript and DOM details that can be daunting at times.

What are the benefits of using JSMF? (TOP)

JSMF provides the following features and benefits:

Provides client-side storage and caching of session data (form variables).

Provides multiple data persistence ("freeze" and "thaw") mechanisms. Client-side method uses cookies, while server-side method can be implemented in any number of ways.

Reduces server-side processing and state logic.

Allows all frames within a given page to easily access and exchange data.

Getting Started (TOP)

JSMF can be used in a framed environment, and can work with both standard and inline frames. The following example illustrates how to initialize the state manager with an embedded iframe. Setting up the JSMF environment only requires a few steps:

1) Include the state_manager.js script in your application / webpage.

          <script language="JavaScript" src="state_manager.js" type="text/javascript">
          </script>

2) Insert a hidden iframe.

    
       <iframe id="state_manager" name="state_manager" style=
       "visibility: hidden; border: 1; width: 0px; height: 0px;">
       </iframe>

3) Create the state manager object at body onLoad or as an embedded script.

        
           <script language="JavaScript" type="text/javascript">
    
            var initParams = new Object();
    
            initParams.type = 'url';
            initParams.url = 'variables.html';
            initParams.frameType = 'iframe';
            initParams.frame = 'state_manager;
    
            var sm = new stateManager(initParams);
    
          </script>

That's all there is to it! See the following Test Engine and API sections for details on using the state manager object.

Test Engine (TOP)

The following links provide a sample test engine that illustrates how to invoke the JSMF API:

Inline Frame - IFrame Test

Standard Frame - Frame Test

API (TOP)

new()

Constructs state manager object.

Parameters: initParams (Object)

initParams.debug = debug level
initParams.frameType = values := ['iframe','frame']
initParams.frame = name of frame
initParams.type = values := ['url','form','hash']
initParams.url = URL to initialize form
initParams.form = form object (document.forms[0])
initParams.hashString = key value string ('name1=value1,name2=value2')

Returns: stateManager (Object)

Usage:
    
    var initParams = new Object();
    
    initParams.type = 'url';
    initParams.url = 'variables.html';
    initParams.frameType = 'iframe';
    initParams.frame = 'state_manager;

    var sm = new stateManager(initParams);

addVariable()

Adds new variable to state manager.

Parameters: name (String), value (String)

Returns: true|false (Boolean)

Usage:
    
    sm.addVariable('new_variable','new_value');

debug()

Sets debug level for state manager object.

Parameters: debug_flag (Integer) [0 = off, 1 = on]

Returns: debug_flag (Integer)

Usage:
    
    // Set debug level
    sm.debug(1);

    // Get debug level
    var level = sm.debug();

deleteVariable()

Deletes existing variable from state manager.

Parameters: name (String)

Returns: true|false (Boolean)

Usage:
    
    sm.deleteVariable('variable');

destroy()

Deconstructs/Destroys state manager object.

Parameters: none

Returns: nothing

Usage:
    
    sm.destroy();

dump()

Returns string of name value pairs in state manager.

Parameters: none

Returns: dumpList (String)

Usage:
    
    if ( sm.debug() ) {
        alert(sm.dump());
    }

freeze()

Freezes state manager data for later use.
Supports both client-side and server-side freezing.

Parameters: method (String), parameters (String)

method = values := ['client','server']
parameters = values := [cookie_name, server_url]

Returns: true|false (Boolean)

Usage:
    
    // Client freeze
    sm.freeze('client','cookie_name');

    // Server freeze
    sm.freeze('server','http://127.0.0.1/jsmf/server.cgi?action=freeze');

getVariable()

Gets variable value.

Parameters: name (String)

Returns: value (String)

Usage:
    
    var value = sm.getVariable('variable');

makeForm()

Creates an empty form inside the state manager frame.

Parameters: none

Returns: true|false (Boolean)

Usage:
    
    sm.makeForm();

makeFormInput()

Creates hidden variable inside state manager form.

Parameters: name (String), value (String)

Returns: true|false (Boolean)

Usage:
    
    sm.makeFormInput('name','value');

peek()

Makes frame visible for debugging purposes.
Currently supports iframe only.

Parameters: flagOn (Integer), Height (Integer), Width (Integer)

Returns: true|false (Boolean)

Usage:
    
    // Peek on
    sm.peek(1,100,250);

    // Peek off
    sm.peek(0,0,0);

reset()

Resets state manager object and clears all variables.

Parameters: none

Returns: true|false (Boolean)

Usage:
    
    sm.reset();

saveForm()

Stores existing form object into state manager;

Parameters: form (formObject)

Returns: true|false (Boolean)

Usage:
    
    sm.saveForm(document.forms[0]);

saveToHash()

Saves state manager variables as a hash

Parameters: none

Returns: hash (Hash)

Usage:
        
    var hash = sm.saveToHash();

    for ( key in hash ) {
        alert(key + ' = ' + hash[key] + '\n');
    }

setVariable()

Sets variable value.

Parameters: name (String), value (String)

Returns: true|false (Boolean)

Usage:
    
    sm.setVariable('variable','value');

thaw()

Thaws state manager data.
Supports both client-side and server-side thawing.

Parameters: method (String), parameters (String)

method = values := ['client','server']
parameters = values := [cookie_name, server_url]

Returns: true|false (Boolean)

Usage:
    
    // Client freeze
    sm.thaw('client','cookie_name');

    // Server freeze
    sm.thaw('server','http://127.0.0.1/jsmf/server.cgi?action=thaw');

Browser Compatibility (TOP)

This version of JSMF is a preliminary release and has only been tested with Internet Explorer version 6.0 (SP1) and Mozilla Firefox version 1.0 (Preview Release). Since browser compatibility is very important, other browsers will be tested and future releases will include compatibility fixes as they are needed.

Download (TOP)

Click (Here) to download version 1.0 of JSMF.

Feedback (TOP)

Comments, suggestions, and contributions are always welcome. Please email them to erictblue at users.sourceforge.net.