Introduction and Set-Up

This tutorial uses a simple flash movie, a XML document, and a listing of images. The Flash movie loads the XML and images to create a user initiated "slide show" (for lack of a better term) that was intended to display news snippets with an image and a link to read more.

Getting Started:

To go through this tutorial you will need the following products:

· Flash 8

· A Text Editor that can edit XML Files

Setting Up:

First thing to do is to create a new folder on your disk called "FlashNewsListing" under the C:\ directory (or wherever you would like to keep it).   In this folder create two new sub folders. Name one "images" and name the other "xml".   Also create a flash movie in the "FlashNewsListing" folder named "MyFlashNewsListings.fla".

When your done your folder structure should look something like this

C:\FlashNewsListing
   \images
   \xml
   MyFlashNewsListings.fla

On to the next page to get into the guts of it all.

Step One : Creating the XML Document

For this example we are going to keep this pretty simple. So we are going to create an XML document which will house the content for our news articles. This will contain 5 articles, each with 4 properties:

· Headline - The title of the news article

· Copy - The body of the news article.

· Image - An image that will display with the article

· Hyperlink (link) - A link to the full article, or more information

So let's get into some XML.

Create a new .xml file in any editor you choose. You can start by creating a text file and just changing the extension to .xml.

Name the file "features.xml".

Copy and paste the code below into the XML

<?xml version="1.0" encoding="utf-8"?>

<headline>HEADLINE 1</headline>

<copy>Here goes some copy you can probably put html text in here as long as its escaped</copy>

<image>images/1.gif</image> <link>http://www.sandboxcommunications.com</link>

</feature>

<headline>Feature 2</headline>

<copy>Lorem ipsumn dolomet sit</copy>

<image>images/2.gif</image>

</feature>

<headline>MustCodeMore</headline>

<copy>More mustcodemore.com, more</copy>

<image>images/3.gif</image>

</feature>

<headline>Feature 4</headline>

<copy> Lorem ipsumn dolomet sit amore dit amore.</copy>

<image>images/4.gif</image>

</feature>

<headline>Feature 5</headline>

<copy>Borem Bpsumn Bolomet Bit Bmore Bit Bmore.</copy>

<image>images/5.gif</image>

</feature>

<headline>Feature 6</headline>

<copy>asdf j lakj. This is about feature six. Man </copy>

<image>images/6.gif</image>

</feature>

</features>

So let's take a look at this to make some sense of it. Let's look at ONE article only to understand how this works.

Firstly lets look at the very top this line:

<?xml version="1.0" encoding="utf-8"?>

This line is basically a declaration to tell whatever is calling it that it is, in fact, an XML Document. It stipulates a version and the content encoding type. Its required for all xml documents.

This is the beginning tag of our collection of features. If you look at the bottom of the XML Document you will also see that this has a closing tag like : </features> Everything inside these two tags is considered a part (or element of) the features collection.

Now lets actually look at a feature and its properties:

<headline>HEADLINE 1</headline>

<copy>Here goes some copy you can probably put html text in here as long as its escaped</copy>

<image>images/1.gif</image>

</feature>

So above is one feature. Notice how it's made up of a hierarchy of tags. Starting with the <feature enabled="true"> tag. This tag also has a property "enabled" and its set to true. This tells our movie that this feature is available to use. If you switch that to "false" the feature will effectively be disabled and will not show up in the flash movie.

Under that tag there are our tags that define the content of the features. We have :

<headline> This is where you put the title of the feature.

<copy> Put the actual text content of the feature or article in here. You could use HTML Text if it's escaped (or encoded) but you should be careful as flash does not always parse html as expected.

<image> This is the RELATIVE path to the image file from the page hosting your flash movie. Since the page will be in the ROOT directory ("FlashNewsListing") we must specify the path to the images folder and the image name.

And this is just repeated for the number of news articles, or features we have.

So once that’s all set up just save and close the xml document. If you have Visual Studio or another XML Editor you can also probably check the document for errors, which is quite useful but beyond the scope of this article.

Now lets move on to the next step...

Step Two : Putting your images in your image folder

Perhaps the Easiest step of them all. The images you named in your xml file. Go make them up and put them in your images folder. That’s it. Use Photoshop or Fireworks. The images are small in my example but the content and sizes are really up to you, so get creative!

Once you have each image for your articles in your image folder your ready to move on to Step Three.

Step Three : Creating a Flash Movie To Display your Articles

Open the flash movie I asked you to create in the Set Up section of this article. From here we will be making a few objects. Me personally, I like to put each object on its own layer and have all my actionscript on its own layer as well. So let's create 6 layers on your timeline. Name them whatever you want but make the topmost one named "Actionscript" as this is where we will be putting all our code in.

Once that is done we got to make some movie clips. 4 to be exact. One for the image, One for the Read More (or Learn More) button, and two additional buttons, previous and next. Please note that for this example I use Movie Clips for everything, but you can use buttons if you want too. There is really no difference in the execution.

Create the image movie clip

Go to your library and right click in there. Choose "New Symbol".
Name the symbol "image_mc"
Go into the symbol and draw a square in it at approximately the same size as your images (this is for no other reason than to make it easy to layout on the timeline when designing it) you do not need to draw the square if you do not want too.
Close it and place it on your stage in one of the layers you created. Name the instance "image_mc" (same as the library object name)

Create the learn more button movie clip

Go to your library and right click in there. Choose "New Symbol".
Name the symbol "learnmore_btn"
Make a button design on it with some text that says "Learn More".
Close it and place this on the stage on a layer designated for it. Name the instance "learnmore_btn".

Create the Next Button

Go to your library and right click in there. Choose "New Symbol".
Name the symbol "next_btn"
Make a button design and add some text saying "Next"
Close it, place it on the stage and name the instance "next_btn"

Create the Previous Button

Go to your library and right click in there. Choose "New Symbol".
Name the symbol "prev_btn"
Make a button design and add some text saying "Previous"
Close it, place it on the stage and name the instance "prev_btn"

Ok, so let's re-cap here. Now we have a movie made, with 6 layers. 4 of which are taken up by movie clips we just made, one is reserved for Actionscript, and one is blank (the blank one we are going to use now). Also, all the clips instances are named the same as the library items. (that’s its property name when it's placed on the stage) .

In addition to these clips we need to add two text fields directly on the stage. One for the HEADLINE and one for the Body Copy. So Place two text fields on the stage in the remaining blank layer. Name them txtHeadline and txtCopy and make them both dynamic. You may want to make the txtHeadline Font Bold and maybe a different colour than the other field. Also make the other field big enough to fit your article text (mine covers about 3 or 4 lines of text).

So now that you're done all that please save the movie and move on to the next step.

Step Four : Writing the Actionscript to wire up our movie

Now we are ready for the Actionscript. Go to the layer you named actionscript. Click in frame 1 (you should only have one frame) and press F9 to open the ACTIONSCRIPT panel. Once that is opened Copy and paste the code below into it:

/* initialize variables */

var xmlObj:XML = new XML();

var featuresArray = new Array();

var counter:Number = 0;

/* stylize text areas */

txtHeadline.html = true;

txtHeadline.wordWrap = true;

txtCopy.html = true;

txtCopy.wordWrap = true;

//load the xml into the Xml Object

xmlObj.ignoreWhite = true;

xmlObj.load("xml/features.xml");

/* parses the xml file and copies to array */

xmlObj.onLoad = function(success) {

var temp = new Array();

temp = xmlObj.childNodes[0].childNodes;

//remove any disabled items

for (var p = 0; p<temp.length; ++p) {

if (temp[p].attributes["enabled"].toString() == "false") {

temp.splice(p, 1);

}

//assign the temp array to our declared features array

featuresArray = temp;

//call the bind method - this just adds the necessary

bindFeatures(0);

};

/* bind the data to the controls */

bindFeatures = function (index) {

/* set up text fields */

txtHeadline.text = featuresArray[index].childNodes[0].firstChild.nodeValue.toString();

txtCopy.text = featuresArray[index].childNodes[1].firstChild.nodeValue.toString();

this.image_mc.loadMovie(featuresArray[index].childNodes[2].firstChild.nodeValue.toString());

};

/* EVENT HANDLERS */

/* Learn More Button Event */

btnLearnMore.onRelease = function() {

getURL(featuresArray[counter].childNodes[3].firstChild.nodeValue.toString(), "_blank");

};

/* Next Button Event*/

btnNext.onRelease = function() {

counter++;

//this just makes sure we are not at the end of our list of items - if so it goes back to 0

if (counter>=featuresArray.length) {

counter = 0;

}

bindFeatures(counter);

};

/* Previous Button Event */

btnPrevious.onRelease = function() {

counter--;

//this just makes sure we are not at the beginning of our list of items - if so it goes to the last feature

if (counter<0) {

counter = featuresArray.length-1;

}

bindFeatures(counter);

};

Wow, that seems like a lot of code, but really its not. Let's go through each piece together to understand what i am trying to do here.

/* initialize variables */

var xmlObj:XML = new XML();

var featuresArray = new Array();

var counter:Number = 0;

These three lines simply set some variables up we need to use in our movie. The first one is "xmlObj" this is a new instance of the XML class provided in Flash for us to use. "featuresArray" is the name of the new array we will put all the XML into when we load it into memory. "counter" is simply a counter that keeps track of our position in the array and makes sure we don't try to move to an article number that does not exist.

/* stylize text areas */

txtHeadline.html = true;

txtHeadline.wordWrap = true;

txtCopy.html = true;

txtCopy.wordWrap = true;

These are simply setting some additional properties for those two text boxes we created. We are making them HTML enabled so we can inject html text in there (if we want too), and i am setting wordWrap on both of them so the text wraps around (especially needed for the txtCopy Text Box).

//load the xml into the Xml Object

xmlObj.ignoreWhite = true;

xmlObj.load("xml/features.xml");

These two lines load the XML document into Flash's memory. The first statement "ignoreWhite" is used to ensure if there are any white spaces in the xml document, flash does not incorrectly interpret them as actual values. The second line actually gets the xml document at the path specified and loads it to that xmlObj we declared at the top.

/* parses the xml file and copies to array */

xmlObj.onLoad = function(success) {

var temp = new Array();

temp = xmlObj.childNodes[0].childNodes;

//remove any disabled items

for (var p = 0; p<temp.length; ++p) {

if (temp[p].attributes["enabled"].toString() == "false") {

temp.splice(p, 1);

}

//assign the temp array to our declared features array

featuresArray = temp;

//call the bind method - this just adds the necessary

bindFeatures(0);

};

This is an event method. Basically, when we run that line: "xmlObj.load("xml/features.xml");" it loads the xml. Once it's loaded it runs the method listed above. Notice how the method is defined for the onLoad event of our XmlObject. The XmlObject has many events you can attach methods to in this fashion.

This method looks for a parameter passed to it from the load operation named success. If it's true we can go ahead, if success is not true it will fail silently and will not process anything. (ex: if it can not find the path to the XML file it would fail). So let's assume everything was a success. We start by creating a new Array in our method. Then we assign the children of our xml Object to this array, (xmlObj.childNodes[0].childNodes) < This is looking two levels down from the top of the XML document. So its grabbing everything in the <features> tags.

From there it looks at the attributes of each feature (we only have one attribute which is "enabled"). If this is false it removes it from the array (remember disabling the feature) using the array classes splice method.

We then copy the temp array we created to our publicly available "featuresArray" we declared way at the top of the Actionscript. By doing this we allow the array that is only available in this method to be available to all methods in the movie.

After that it calls another function "bindFeatures" which does the work of actually tying the text to the text boxes and image to the image box. Let's look at that code now.

/* bind the data to the controls */

bindFeatures = function (index) {

/* set up text fields */

txtHeadline.text = featuresArray[index].childNodes[0].firstChild.nodeValue.toString();

txtCopy.text = featuresArray[index].childNodes[1].firstChild.nodeValue.toString();

this.image_mc.loadMovie(featuresArray[index].childNodes[2].firstChild.nodeValue.toString());

};

bindFeatures method takes one parameter named "index". This is the index position in the array of the specific article you want to display. So at first it shows the first article, but when you press the next and previous buttons it passes different numbers into this method to display different articles or features.

All this method does is look in the features array and traverses the XML nodes that are stored in there. It’s a bit cryptic to read childNodes[0].firstChild.nodeValue.toString(); but basically we are looking at a specific features children (which are the headline, copy, image, link properties). You can issue trace statements to help you get a grasp on what element is where in the XML DOM. Once we find each element we assign it to the proper text box. In the case of the image we issue a simple loadMovie Command like so :

this.image_mc.loadMovie(featuresArray[index].childNodes[2].firstChild.nodeValue.toString());

So that’s pretty much it, this method binds the information to the text boxes, etc and displays it on the page. Now to wire up the buttons:

/* EVENT HANDLERS */

/* Learn More Button Event */

btnLearnMore.onRelease = function() {

getURL(featuresArray[counter].childNodes[3].firstChild.nodeValue.toString(), "_blank");

};

This (above) is the event handler for clicking on the learn more button. Basically it issues a getURL with the hyperlink you specified in the xml document. It also uses a "_blank" target to spawn a new window (no sense driving traffic away for little 'ol me).

/* Next Button Event*/

btnNext.onRelease = function() {

counter++;

//this just makes sure we are not at the end of our list of items - if so it goes back to 0

if (counter>=featuresArray.length) {

counter = 0;

}

bindFeatures(counter);

};

This event is for the Next Button. All it does is increment the counter we declared at the top of our actionscript by one. It then does a tiny bit of error checking to make sure our new index position is not greater than the number of articles we have available. If it is, we just re-set it back to the beginning.

/* Previous Button Event */

btnPrevious.onRelease = function() {

counter--;

//this just makes sure we are not at the beginning of our list of items - if so it goes to the last feature

if (counter<0) {

counter = featuresArray.length-1;

}

bindFeatures(counter);

};

This event is for the Previous Button. All it does is decrement the counter we declared at the top of our actionscript by one. It then does a tiny bit of error checking to make sure our new index position is not less than zero. If it is, we just set it to the LAST article.

Using this type of error checking ensures that your users will be able to loop through all articles without ever reaching an "end" or getting an error.

Conclusion And Related Links

That’s about it for this, you should be able to test your movie, and provided you followed my naming conventions and folder structure you should have it running in no time. I have included all the source files for this in the attached .zip file so you can use them for reference.

Also note that this can be used for anything, and if you wanted to ADD data to your XML document (say an authors name or something) all you need to do to process it is make a text field for it, and modify the bindContents method slightly to find the XML Node and assign it to the new text box.

Below are some links you may find useful that relate to the terms and practices demonstrated in this article:

Adobe XML Topic Center
http://www.adobe.com/devnet/topics/xml.html

Actionscript 2.0 Language Reference - Arrays http://livedocs.adobe.com/flash/8/main/wwhelp/wwhimpl/js/html/wwhelp.htm?href=Part4_ASLR2.html

Happy Programming,

Mike Mckinnon