Shared Object

Up to this point, we have discussed how to get data into our application from a server. This section covers a cookie-like Flash object called a SharedObject that enables us to write data from our application and to persist the data on the client machine ”much in the same way as a cookie behaves.

Cookies are small bits of data stored in files on the client machine. They help an application or website remember information about you or how you used the website. The cookie can hold anything from your name to the contents of your last shopping cart. Quite often cookies are used to remember your preferences or state. For example, you might visit a retailer's site and they have an option to view content as HTML or in Flash. Your choice is a likely candidate for a cookie so that the next time you visit the site, you are served the correct version without being asked.

Cookies are stored in a specific location on the client machine. The directory is based on which browser the client is using. SharedObject data is also stored on the client machine in a specific directory based on the domain from which the Flash application is loaded.

Creating and Populating a SharedObject

SharedObjects behave a bit differently than most other objects in Flash. To create a SharedObject , we do not call the constructor of the object. Instead we call the getLocal() static method. The getLocal() method determines if an object exists and if it does, opens it for reading; if it doesn't exist, it creates a new one. As shown in Table 11.2, the getLocal() method returns a SharedObject instance. This table is a method summary for the SharedObject .

Table 11.3. SharedObject Methods from Flash 2004 Help Files

M ETHOD	D ESCRIPTION
SharedObject.clear()	Purges all of the data from the shared object and deletes the shared object from the disk
SharedObject.flush()	Immediately writes a locally persistent shared object to a local file
SharedObject.getLocal()	Returns a reference to a locally persistent shared object that is available only to the current client
SharedObject.getSize()	Gets the current size of the shared object, in bytes

If you recall, our loan calculator application uses several pieces of data to calculate monthly payments. It would be useful to save the last calculated loan so that when the user wants to calculate another loan, he or she is reminded of the previous use. We might also add a name to personalize the application.

Listing 11.9 shows an example of creating a SharedObject to maintain the state of our loan calculator application.

Listing 11.9. Create a SharedObject to Maintain Loan Calculator State

 //create LSO or open if it already exists var loanCalcLso = SharedObject.getLocal("loanCalc"); 

After you have created a SharedObject in the application, it is ready for writing. All SharedObjects have a property called data . This property is itself an object and is used to store user data. In Listing 11.10, the variables that we want to save for our loan application are added as properties of the SharedObject's data container.

Listing 11.10. Writing Data to a Shared Object

 //write to LSO       loanCalcLso.data.lastLoanAmount=loanAmt.text;       loanCalcLso.data.lastLoanTerm=term.text;       loanCalcLso.data.lastLoanTerm=name.text; 

We have chosen to save simple text as strings to the SharedObject . We could, however, save any ActionScript 2.0 variable to the SharedObject . We would do this if we were saving an array or an object with multiple properties.

Saving a SharedObject

Although the SharedObject has been created in the application, it hasn't yet been saved to the local storage. Saving the SharedObject to disk will happen automatically when the movie is closed. It will also happen when the SharedObject is deleted or garbage collected. You can, however, explicitly choose to save the SharedObject to disk using the flush() method.

There are different methods available to help us manage the process of writing to the disk. In Table 11.3, the two methods that will help us manage this process are clear() and flush() . By calling SharedObject.flush() , the entire contents of the object are written to the local disk. This method is preferred over passive saving because it provides you the opportunity to prompt the user with storage size requirements.

By default, the Flash Player accepts shared objects up to 100k. This is also a configurable attribute of the Player. If you right-click a Flash movie in the browser and select Settings, you will be able to modify the Player settings. Figure 11.2 shows the dialog box that enables you to increase the local storage size for shared objects.

Figure 11.2. Player settings for local storage.

If the application has minimum data requirements and the user tries to set the local storage value below the minimum, a warning dialog will be displayed, as in Figure 11.3.

Figure 11.3. Player settings warning.

N OTE

For more information on Player settings, see www.macromedia.com/support/flashplayer/help/settings/.

It's a good idea to know where the data is actually stored on the client. The file locations depend on what operating systems you are using. All local shared object files will have the extension .sol. In Windows XP for example, the shared object for the loan calculator would be stored as follows :

 C:\Documents and Settings\userName\Application Data\Macromedia\Flash Player\localhost\LoanCalculator\loanCalc.swf\loanCalc.sol Host\directoryName\applicationName\solName.sol 

Notice that the directory structure contains a reference to Host\directoryName\applicationName\solName.sol . By using the host name in the directory structure, Flash can guarantee uniqueness from other applications with the same name storing data in local shared objects.

There might be times when you will want to delete all the data from a local shared object. The method clear() will remove any existing data from the shared object. This is a good practice for keeping the size of the shared object down. We can also determine the size of the data in a shared object using the getSize() method. This will return the size in bytes. This can help us determine if we have exceeded the local storage threshold and need to respond accordingly .

N OTE

When using local SharedObjects , we are depending on the user to allow local storage. For this reason, it is a good idea to have some error checking to determine if the data was actually stored. The flush() method returns true/false, indicating whether the SharedObject was successfully written to the disk. You can use this value to inform the user to check the local storage settings.