Enable persistence in a mobile application

The following example sets the persistNavigatorState property to true for an application to enable session persistence:

<?xml version="1.0" encoding="utf-8"?>
<!-- containers\mobile\SparkSingleSectionPersist.mxml -->
<s:ViewNavigatorApplication xmlns:fx="http://ns.adobe.com/mxml/2009"
    xmlns:s="library://ns.adobe.com/flex/spark"
    firstView="views.EmployeeMainView"
    persistNavigatorState="true">
    
    <fx:Script>
        <![CDATA[
            protected function button1_clickHandler(event:MouseEvent):void {
                // Switch to the first view in the section.
                navigator.popToFirstView();
            }
        ]]>
    </fx:Script>
    
    <s:navigationContent>
        <s:Button icon="@Embed(source='assets/Home.png')" 
                  click="button1_clickHandler(event)"/>
    </s:navigationContent>
</s:ViewNavigatorApplication>

This application uses EmployeeMainView.mxml as its first view. EmployeeMainView.mxml defines a List control that lets you select a user name:

<?xml version="1.0" encoding="utf-8"?>
<!-- containers\mobile\views\EmployeeMainView.mxml -->
<s:View xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    title="Employees">
    <s:layout>
        <s:VerticalLayout paddingTop="10"/>
    </s:layout>
        
    <fx:Script>
        <![CDATA[
            import spark.events.IndexChangeEvent;

            protected function myList_changeHandler(event:IndexChangeEvent):void {
                navigator.pushView(views.EmployeeView,myList.selectedItem);
            }

        ]]>
    </fx:Script>
    
    <s:Label text="Select an employee name"/>
    <s:List id="myList"
        width="100%" height="100%"
        labelField="firstName"
        change="myList_changeHandler(event)">
        <s:ArrayCollection>
            <fx:Object firstName="Bill" lastName="Smith" companyID="11233"/>
            <fx:Object firstName="Dave" lastName="Jones" companyID="13455"/>
            <fx:Object firstName="Mary" lastName="Davis" companyID="11543"/>
            <fx:Object firstName="Debbie" lastName="Cooper" companyID="14266"/>
        </s:ArrayCollection>
    </s:List>
</s:View>

To see session persistence, open the application, and then select “Dave” in the List control to navigate to the EmployeeView.mxml view:

<?xml version="1.0" encoding="utf-8"?>
<!-- containers\mobile\views\EmployeeView.mxml -->
<s:View xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:s="library://ns.adobe.com/flex/spark" 
    title="Employee View">
    <s:layout>
        <s:VerticalLayout paddingTop="10"/>
    </s:layout>
    
    <s:VGroup>
        <s:Label text="{data.firstName}"/>
        <s:Label text="{data.lastName}"/>
        <s:Label text="{data.companyID}"/>
    </s:VGroup>
</s:View>

The EmployeeView.mxml view displays the data about “Dave”. Then, quit the application. When you restart the application, you again see the EmployeeView.mxml view displaying the same data as when you quit the application.

Information in a local shared object is saved as a key:value pair. The methods of the PeristenceManager, such as setPropery() and getProperty(), rely on the key to access the associated value in the local shared object.

You can use the setProperty() method to write your own key:value pairs to the local shared object. The setProperty() method has the following signature:

setProperty(key:String, value:Object):void

Use the getProperty() method to access the value for a specific key. The getProperty() method has the following signature:

getProperty(key:String):Object

When the persistNavigatorState property is true, the persistence manager automatically saves two key:value pairs to the local shared object when the application quits:

When the persistNavigatorState property is true, Flex automatically performs session persistence. You can still persist application data when the persistNavigatorState property is false. In that situation, implement your own persistence mechanism by using methods of the PeristenceManager.

Use the setProperty() and getProperty() methods to write and read infomration in the local shared object. Call the load() method to initialize the PeristenceManager. Call the save() methods to write any data to disk.

You can cancel the saving of an applications state to disk by calling the preventDefault() method in the handler for the navigatorStateSaving event. Cancel application loading on restart by calling the preventDefault() method in the handler for the navigatorStateLoading event.

When session persistence is enabled, the application opens to the view that was displayed when the application quit. You must store enough information in the view’s data property, or elsewhere such as in a shared object, to be able to completely restore the application state.

For example, the restored view might have to perform calculations based on the view’s data property. Your application must then recognize when the application restarts, and perform the necessary calcualtions. One option is to override the serializeData() and deserializePersistedData() methods of the View to perform your own actions when the application quits or restarts.

Built-in data type support for session persistence

The persistence mechanism automatically supports all built-in data types, including: Number, String, Array, Vector, Object, uint, int, and Boolean. These data types are automatically saved by the persistence mechanism.

Custom class support for session persistence

Many applications use custom classes to define data. If a custom class contains properties defined by the built-in data types, the persistence mechanism can automatically save and load the class. However, you must first register the class with the persistence mechanism by calling the flash.net.registerClassAlias() method. Typically you call this method in the preinitialize event of the application, before the persistence storage is initialized or any data is saved to it.

If you define a complex class, one that uses data types other than the built-in data types, you must convert that data to a supported type, such as a String. Also, if the class defines any private variables, they are not automatically persisted. To support the complex class in the persistence mechanism, the class must implement the flash.utils.IExternalizable interface. This interface requires that the class implements the writeExternal() and readExternal() methods to save and restore an instance of the class.