States API

Overview

States are provided to simplify and accelerate the creation of dynamic user interfaces within your application.

You don’t need to know how to code to use states.  Designers can create dynamic UI via options in the design tool:

• Simply add a new state for each unique interaction in your user interface.
• For each state added, you can hide irrelevant user interface elements, show relevant ones, plus move, resize and style anything the user should see.
• You can set up triggers for state changes by setting an event property on any user interface element.  Simply choose the state you want to set the event to trigger via the dropdown menu.

For more advanced scenarios, developers can manipulate states via an API.  You can use the States API to:

• Listen for state changes in order to trigger complex animations and business logic.
• Trigger state changes via application initiated events.

API

/**

 * Sets the current state of the application interface.

 * You can subscribe to changes in state using the following call:

 *   davinci.states.subscribe("/davinci/states/state/changed", callback)

 * @return undefined

 */

 davinci.states.setState(stateName);

/**

 * Gets the current state of the application interface.

 * @return string

 */
davinci.states.getState();

Examples

In addition to the basic style changes set in the design tool, you may need to add more complex animations to your application, execute business logic, or trigger states changes via application events.  The following examples demonstrate how to accomplish these types of goals.

Adding Complex Animations

You can add complex animations to your application by listening for the state changed event, and executing a callback which triggers the desired animation from your favorite toolkit.  The following sample code illustrates how you might use the states API to implement your favorite slide effect for a login prompt.

Sample code

<script src=”my/favorite/toolkit/effects.js”></script>

<script>

davinci.states.subscribe("/davinci/states/state/changed",function(event){

	var loginPrompt = document.getElementById("loginPrompt");

	var state = "Login Prompt";

	if (event.newState == state) {

		my.favorite.toolkit.effects.slideIn(loginPrompt);

	} else if (event.oldState == state) {

		my.favorite.toolkit.effects.slideOut(loginPrompt);

	}

});

</script>

Executing Business Logic

You can execute business logic in your application when the user interface changes by listening for the state changed event, and executing a callback which triggers the desired logic.  The following sample code illustrates how you might use the states API to implement a search results interface.

Sample code

<script src=”my/business/logic.js”></script>

<script src=”my/ui/logic.js”></script>

<script>

davinci.states.subscribe("/davinci/states/state/changed", function(event){

            // If we’ve just changed to the Search Results state, then populate the results div

            if (event.newState == "Search Results") {

    	        var query = document.getElementById("searchField").value;

                var results = my.business.logic.getResults(query);

	            my.ui.logic.populateSearchResultsDivWith(results);

			}

});

</script>

Triggering State Changes via Application Events

You can trigger state changes via application events by simply calling the setState function within your code.  The following sample code illustrates how you might use the states API to implement an inactivity based logout warning.

Sample code

<script src=”my/ui/logic.js”></script>

<script>

setInterval(function(){

            var state = davinci.states.getState();


            // If we’ve already warned the user, then trigger the logout

            if (state == "Inactivity Warning") {

                        davinci.states.setState("Logging Out");

                        my.ui.logic.logout();


            // After 15 minutes, warn the user that they’ll soon be logged out

            } else if (my.ui.logic.timeSinceLastActivity() > 15*60*1000 ) {

                        davinci.states.setState("Inactivity Warning");

            }

}, 60*1000);

</script>