The LoadVars Object


The LoadVars Object

The LoadVars object, introduced back in Flash MX, is an object whose sole purpose is to send and load data in and out of Flash. Because it is its own object with its own events, properties, and methods, you do not have to create a movie clip object to hold the data (which would take up more memory).

Creating a LoadVars object is the same as creating any other object. Create a variable, give it a name, and set it to a new LoadVars() object like this:

 var myLoader_lv:LoadVars = new LoadVars(); 

There you have it; you have just created your first LoadVars object. Now let's see how to use them.

The LoadVars object has three basic methods for sending and loading data:

  • load This method loads content from either a text file or middleware.

  • sendAndLoad This method sends data out of Flash to middleware and returns the results created by the middleware back to Flash.

  • send This method posts variables to a specified URL and does not return anything.

The last two methods are beyond the scope of this chapter because they deal strictly with middleware, which are scripts that run on web servers designed to create dynamic content when requested. You will be exposed to them in later chapters.

The method that will be covered in this chapter in regard to the LoadVars object is the load() method.

The load() Method

The load() method for the LoadVars object is used to load content into Flash. The format for the content is the same as we have been using, the MIME format.

Here is the load() method's basic usage:

 loadVars.load(URL); 

There is only one parameter for this method:

  • URL A path to the text file or middleware to load variables from.

Now that you see what it looks like, let's use it.

1.

Create a new Flash document.

2.

Save this document as sample-20-5.fla in the same directory you have been working in.

3.

Open up the Actions panel in the first frame of the main timeline and place these actions within it:

 //create the LoadVars object var myLoader_lv:LoadVars = new LoadVars(); //load the content myLoader_lv.load("sample.txt"); 

Now test the movie and notice that, as before, nothing appears to have happened, but if you select Debug, List Variables, you will see that the variables have been loaded from the original text file you created, as before.

Because LoadVars is its own object, it has its own event for when the variables have completely loaded, the onLoad event.

The onLoad Event

The onLoad event is the only supported event for the LoadVars object. It is triggered when data has been loaded into the LoadVars object that the event is associated with, and the data has been parsed. It is called only when either the load() or the sendAndLoad() methods have finished running.

Its generic layout is

 LoadVars.onLoad = function(success){ } 

Notice that unlike the onData event we used earlier, the onLoad event has a parameter that can be passed through the function. This parameter, success, is a Boolean variable, and if the data is loaded correctly, it will be true. If there was an error, success will be false.

The success parameter can be useful, especially when dealing with middleware, which is a bit more complex than the examples we have done in this chapter. You can see its use in the next example, which builds on the preceding one.

After the code that has already been placed in the Actions panel, place this:

 //the event for when the variables have loaded myLoader_lv.onLoad = function(success:Boolean){      if(success){           trace("my name is - "+this.name);           trace("my age is - "+this.age);           trace("my location is - "+this.location);      }else{           //there has been an error           trace("an error has occurred");      } } 

Notice that we used the success parameter to detect whether everything loaded and parsed correctly.

To see an example of what would happen if success had been false, change the line of code that says

 myLoader_lv.load("sample.txt"); 

to

 myLoader_lv.load("doesntExist.txt"); 

Now when you test the example, instead of all the variables being displayed in the Output panel, the error message is displayed along with an error message from Flash, as you can see in Figure 20.6.

Figure 20.6. Because Flash could not find the file we were looking for, the error message we created is displayed.


The onLoad event is the only supported event for the LoadVars object. However, it is not the only event in general for the LoadVars object.

The Undocumented onData Event

There is an undocumented event for the LoadVars object that is triggered long before the onLoad event is ever triggered: the onData event. This event is called when data is first received by the LoadVars object. It then parses the data into individual properties of the LoadVars object and triggers the onLoad event. You can, however, use this event for your own use, and it can come in quite handy when debugging, especially when working with middleware.

Here is the basic layout of the onData event:

 loadVars.onData = function(src){      //do something } 

Notice in this event, we use a parameter called src. This parameter, when used inside the callback function, is all the variables being returned in their raw format, before they are parsed. That means that you will be able to see everything coming back from the text file (or middleware), including all the variable names, the values, equal signs, and ampersands.

Let's do an example using this event.

1.

Start a new Flash document.

2.

Save this document as sample-20-6.fla.

3.

In the first frame of the main timeline, open the Actions panel and place these actions in it:

 //create the LoadVars object var myLoader_lv:LoadVars = new LoadVars(); //load the content myLoader_lv.load("sample.txt"); //the event for when the LoadVars object first receives data myLoader_lv.onData = function(src:String){      trace(src); } 

Now test the movie. This time, instead of getting the usual trace message that you have seen before, you get the entire string of information coming from the text file, as you can see in Figure 20.7.

Figure 20.7. Using the onData event, you can see the entire string coming back to the LoadVars object.


But what if you want to use the onLoad event in conjunction with the onData event?

Take a look at this next example to see what happens:

1.

Start a new Flash document.

2.

Save this document as sample-20-7.fla.

3.

In the first frame of the main timeline, open the Actions panel and place these actions in it:

 //create the LoadVars object var myLoader_lv:LoadVars = new LoadVars(); //load the content myLoader_lv.load("sample.txt"); //the event for when the LoadVars object first receives data myLoader_lv.onData = function(src:String){      trace("onData"); } //the event for when the variables have loaded myLoader_lv.onLoad = function(success:Boolean){      trace("onLoad"); } 

Now test the movie and notice that only the onData is sent to the Output panel when the onData event is triggered, but the onLoad was not sent to the Output panel because the onLoad event was never triggered. This is because the onData event by default will trigger the onLoad event; however, because we have overwritten the onData event, the onLoad event is never triggered. Like everything else, you can work around this, too.

To trigger the onLoad event from the onData event, two things have to occur. First, the string of information coming to the LoadVars object must be decoded using another undocumented feature of the LoadVars object, the decode() method. The decode() method will take the raw name/value pairs passed to it and change them into properties and values for the LoadVars object receiving the data. It looks like this:

 loadVars.decode(src); 

The second thing that needs to be done is the actual triggering of the onLoad event by passing a true Boolean value to it like this:

 loadVars.onLoad(true); and 

Now that you've seen the two actions that need to be called within the onData event before the onLoad event can be called, let's take a look at that example again.

1.

Start a new Flash document.

2.

Save this document as sample-20-8.fla.

3.

In the first frame of the main timeline, open the Actions panel and place these actions in it:

 //create the LoadVars object var myLoader_lv:LoadVars = new LoadVars(); //load the content myLoader_lv.load("sample.txt"); //the event for when the LoadVars object first receives data myLoader_lv.onData = function(src:String){      trace("onData");      //the two actions that need to be called      this.decode(src);      this.onLoad(true); } //the event for when the variables have loaded myLoader_lv.onLoad = function(success:Boolean){      trace("onLoad"); } 

Now test the movie again, and notice that both TRace functions are executed and both messages are sent to the Output panel.

Now that you know how the undocumented onData event works, you should have no problems debugging your applications when you run into data integration issues.

We have gone over a lot of ways to move data into and out of Flash, and they will be revisited in the next few chapters in conjunction with some server-side scripting. But before we move on to that, let's go over a new feature in Flash 8 that makes integration with JavaScript a breeze.




Macromedia Flash Professional 8 Unleashed
Macromedia Flash Professional 8 Unleashed
ISBN: 0672327619
EAN: 2147483647
Year: 2005
Pages: 319

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net