Flash MX Local Shared Objects (aka Flash Cookies)

May 9, 2002
by Gary Rosenzweig

[Editor's note: Technically, this ain't Lingo, but we're just glad Gary's back! -DP]

One of the new features in Flash MX is the ability for a Flash movie to store small pieces of information, usually called cookies, on the user's hard drive. Flash programmers have been praying for this for years. Until MX, the closest thing was to call out to JavaScript and use JavaScript cookies to store the information. But this didn't work on many browsers, so it was a poor solution.

This new Flash MX feature is called Local Shared Objects. An object in Flash is sort of like a property list in Lingo. Each object can have many properties, and each property will have a value. These values can be numbers, strings, arrays, or even other objects.

A local shared object is an object that exists both in memory, like a normal object, and on the user's hard drive. When the movie is gone, the object persists in a safe place on the hard drive. The next time the movie runs, it can get the values in that local shared object, use them, and make more changes to them.

The example movie uses a local shared object to remember the user's name. When it starts, it will try to get the local shared object savename from the hard drive. When it doesn't find this object, it will create it. No properties are stored in this new local shared object. A reference to this object is stored in the variable myLSO.

myLSO = SharedObject.getLocal("savename");

To access properties of the object, you need to access the data property of the object. For instance, to get the property a, you would reference myLSO.data.a. You can get or set the value of properties. If you set a property that doesn't exist, the property is created and its value is filled. If you try to get a property that doesn't exist, you get the ActionScript constant undefined.

The next bit of code will check for the existence of the property username. If it exists, then it will populate the dynamic text field username with the value of the property and go to a frame named olduser. However, if the username property is not found, it will take the movie to the frame labelled newuser.

if (myLSO.data.username == undefined) {

  // no user name, so ask for one
  gotoAndStop("newuser");

} else {

  // has a user name, so use it
  username = myLSO.data.username;
  gotoAndStop("olduser");
}

The newuser frame has an input text field linked to the variable inputname and a button. When the user fills out the field with his or her name and presses the button, the new value of myLSO.data.username is set to the value of inputname. Then, the object is written out to the hard drive with the flush command.

on (release) {
myLSO.data.username = inputname;
myLSO.data.flush();
}

The flush command allows you to control when and how often the local shared object writes itself out to the hard drive. This comes in handy when you are changing several properties of the object. You can wait until the end of the code that changes the properties and issue the flush command just once.

There are the basics. Now for some more details. The name of a shared object file, savename in the example, needs to follow your standard Internet-safe conventions. In other words, use normal letters and numbers, no spaces, and you'll be fine.

The getLocal command can be used with only one parameter, as in the example. Or, you can use a second parameter to define the path of the object. This has little to do with the object file's path on the user's hard drive. Instead, it is a system that lets you define a virtual path for the object so that more than one Flash movie can share the same object.

This path must be either a local relative path, or use the same domain as the movie. For instance, if the movie is at

http://clevermedia.com/content/mymovies/mymovie.swf

then the getLocal path can be /content/mymovies. This would be the same as http://clevermedia.com/content/mymovies.

myLSO = SharedObject.getLocal("savename", "/content/mymovies");

You would want to do this if the shared object is to be shared by more than one movie in the mymovies folder. Otherwise, if the shared object is for only one movie, leave the second parameter out, or use the full path, /content/mymovies/mymovie.swf. You can also use / for a shared object to be used by any movie on your domain.

Another thing that you should know about local shared objects is that they do not work silently like Lingo's setPref and getPref commands. Instead, the user will get a nice dialog box inside your Flash movie the first time your code tries to access the object. If you have easily-frightened users, you may want to mention something in your movie about it first, so they know what is going on.

A Flash MX file is available in ZIP or SIT archive format.

To see a demonstration of the local shared object in action, take a look at the demo movie (requires the Flash MX Player to be installed for your browser).

Gary Rosenzweig is the Chief Engineer, founder, and owner of CleverMedia, a game and multimedia development company in Denver, Colorado. He is the author of ten books on Macromedia Director and Flash, including his latest, Special Edition Using Director MX.