TechNote (Archived)

What is a local Shared Object?

Introduction
Shared Objects are a new and powerful feature of Macromedia Flash MX. There are many ways in which to use Shared Objects and this document will get you started by showing you the basic concepts. Various uses of Shared Objects include remembering a user's score, favorite color, or the last frame visited. The example below stores the name entered by a user and the number of times they have visited the site using the functionality of Shared Objects.

Shared Objects are used to store data on the client machine in much the same way that data is stored in a cookie created through a web browser. The data can only be read by movies originating from the same domain that created the Shared Object. This is the only way Macromedia Flash Player can write data to a user's machine. Shared Objects can not remember a user's e-mail address or other personal information unless they willingly provide such information. For more information on security please see the Security white paper (PDF 716K).

To see a demonstration of Shared Objects, do the following:

1	Make sure Macromedia Flash Player 6 is installed. Refer to Version test for Macromedia Flash Player (TechNote 15507).
2	Enter any text in the text field.
3	Click the Refresh button in the browser to see that the number of visits is incremented.
4	Click the Reset button in the movie to reset the value stored in the shared object.

Download Windows source file local_so.zip (22K). Download Macintosh source file local_so.sit (24K).

Using Shared Objects

1	Creating the Shared Object A Create a Shared Object with the getLocal method of Shared Object. The movie above sets a variable (myLocalSO) and assigns a Shared Object with the name of "flashcookie" with the following ActionScript: `//create the local Shared Object myLocal_so = sharedobject.getLocal("flashcookie");` If a Shared Object with the name "flashcookie" does not already exist, then the Macromedia Flash Player will create a Shared Object with that name. Note: The name of the Shared Object must follow theNaming strategies for Flash (TechNote 14727). It is also recommend that Shared Object names use English letters. B An optional parameter called localPath can also be specified for the Shared Object. This localPath parameter allows some control over where the Shared Object is stored on the client machine. This path match or be contained within the URL that the SWF came from. Therefore, if the movie that creates the Shared Object on the client machine is at `http://www.mydomain.com/movies/mymovie.swf`then the localPath parameter can be set to`http://www.mydomain.com/movies/mymovie.swf`,`/`,`/movies`, or`/movies/mymovie.swf`. The code would look like this: `myLocal_so = sharedobject.getLocal("flashcookie","/movies/mymovie.swf");` This is useful when more than one local Shared Object is used on a site. For instance, all movies from a certain domain can access a user name stored in a local Shared Object created at the root level (set the localPath to "/") while other information specific to an individual movie can be stored in a Shared Object whose localPath parameter is specific to that movie (set the localPath to"/movies/mymovie.swf").
2	Set the value of the Shared Object Information is stored in the Shared Object by assigning attributes to the data property of the Shared Object. In the above movie, the user name entered in the text field is stored in the Shared Object by assigning a name attribute to the data property of the local shared object and setting it equal to the contents of the text field as follows: `//set the variable "name" equal to the text property //of the textfield"userName" myLocal_so.data.name = userName.text;` `//increase the variable counter by one for each visit myLocal_so.data.counter++;` The data is written to the Shared Object when the movie is removed from the Macromedia Flash Player. To write the data immediately the method`flush`can be used as follows: `myLocal_so.flush();`
3	Return the value of the Shared Object When a user returns to the page the Shared Object is read and its values are displayed. `userName.text = myLocal_so.data.name; numVisits.text = "You have been here " + myLocal_so.data.counter +" times."` Because the Shared Object "flashcookie" has already been created on the client machine,`myLocalSO = sharedobject.getLocal("flashcookie");`will get the data from the Shared Object, which can be used to display the user name and number of visits.

Additional Information
The example file uses the new Macromedia Flash MX ActionScript event methods for placing the button actions in the first frame of the main timeline. An important thing to remember is to name the button's instance.The example also uses the new feature of TextFields as objects. For more information, refer to the Macromedia Flash MX documentation orFlash MX Text fields have instance names and variable names (TechNote 16184).

For another example of using Shared Objects see Colin Moock's Address Book application at the Macromedia Flash MX Application Development Center.