Step by step guide for creating a PicLens type 3D photo viewer with Flex and Away3d. This is step 3, of a 3 part tutorial that will sweep many useful techniques used in web application design, Flex, and Flash 3D design. You will make this.

Requirements:

• Adobe Flash CS3
• Adobe Flex Builder 3
• Away3d Library (I recommend using the version I used)
• Tweener Library
• Source Files

Pre Requisites:

• Having done Part 1 and 2 of this tutorial.
• Intermediate programming skills.
• Moderate knowledge of AS3.
• Basic Familiarity with OOP.
• Basic knowledge of Flash CS3.

Step 0:

This is the last section of the tutorial we’ve been working on. We’re going to wrap up everything we’ve done so far and make our work a solid, working application, which we can use and even extend in the future. First, we will centralize all arbitrary parameters into what’s known as a model, then, we’re going to connect the photo gallery into an external xml so we can load images dynamically, and finally we’re going to enhance our graphics a little bit by adding a reflection effect to the 3D scene.

Step 1 – Centralizing data:

As I stated before, we will start by creating a place holder for all arbitrary variables used so far. With arbitrary variables I mean values that we’ve chosen such as the camera’s tween time in the “moveTo()” method within CameraController, or the Z position of the cameraTarget that can greatly affect the nature of the camera’s motion. All these will be placed in a class that will hold these static constants and will also be used to hold dynamic variables further on, so they can be accessed easily from anywhere in the application. So, go ahead and create a new folder next to “view” called “model”. In it, create a new Actionscript Class called “Model.as”.

Now, I need you to work alone for a while. The job to do is recognise all the values you have used so far throughout the application, that you think would be a good idea to name into a variable and control from this central class. Then, all these variables will be declared in Model.as as static constants. This is how my class looks after doing just that:

package  com.li.photoviewer.model

{ 

     public class Model

     {

          public static const  CAMERA_Z:Number = -2000;

          public static const  CAMERA_Z_ZOOMED:Number = -1500;

          public static const  CAMERA_ZOOM_TIME:Number = 1;

          public static const  CAMERA_ZOOM_EASE:String = "easeoutexpo";

          public static const  CAMERATARGET_FRICTION:Number = 0.95;

          public static const  CAMERATARGET_BOUNCE_FACTOR:Number = 0.5;

          public static const  CAMERATARGET_DRAG_FACTOR:Number = 0.1;

          public static const CAMERATARGET_SPEED_FACTOR:Number  = 0.05;

          public static const  CAMERATARGET_Z:Number = -100;

          public static const  CAMERATARGET_MOVETO_TIME:Number = 1;

          public static const  CAMERATARGET_MOVETO_EASE:String = "easeoutexpo";

          public static const  PHOTO_PLANE_SEGMENTS:Number = 3;

          public static const  PHOTO_MATERIAL_SMOOTH:Boolean = true;

          public static const  PHOTO_FADEIN_TIME:Number = 0.25;

          public static const  PHOTO_SPACING:Number = 750;

          public static const  BG_COLOR1:uint = 0x222222;

          public static const  BG_COLOR2:uint = 0x000000;

          public static const  BG_COLOR_RATIO:uint = 80

          public function Model()

          {

          }

     }

}

“public static const” is a way to declare a variable that will be accessible from the outside of the class, can be accessed without instantiating the holder class, and will not change. If you don’t what Im talking about, you should see how we are going to use these variables and then come back to what I’ve just said and you should get it right away.

Step 2 – Connecting to the centralized data:

So far all this is completely useless unless we connect our classes to Model.as, so that the constants can be used. This is done very easily; for instance to connect the “0.05” value representing a camera velocity factor, we do as in the following code:

private function followTarget(evt:Event):void

{

     camera.lookAt(cameraTarget.position);

     var dX:Number = cameraTarget.x - camera.x;

     camera.x  += dX*0.05;

...

Simply change to:

private function followTarget(evt:Event):void

{

     camera.lookAt(cameraTarget.position);

     var dX:Number = cameraTarget.x - camera.x;

     camera.x  += dX*Model.CAMERATARGET_SPEED_FACTOR;

     ...

As long as the model has been imported in CameraController of course:

import com.li.photoviewer.model.Model;

So this is what you should do next. Import Model.as in all the view and controller classes, and connect the values to it. If you’ve imported the model into a class first, you should get useful codehints from Flex to help you complete this task. When you’re done, you’ll have the power to very precisely tweak the entire application from Model.as. You should play around with this to tune it to your liking.

Step 3 – Setting up an external XML:

Now that our model is set up and working, we will read data from an external xml, and also use the model to store the data contained in the xml. We will trigger a service that will read an xml and detail the images that will be loaded in our application, and once this service is done, the 3D scene will build itself based on this data. For this, lets start by designing our xml. Create a folder named “data” and in it a new file named “data.xml”. The folder should be next to “com” or  “away3d” folders. Then design the xml structure of data.xml like this:

<?xml  version="1.0"?>

<imgs>

     <img name="testImage.jpg"/>

     <img  name="1.jpg"/>

     <img  name="2.jpg"/>

     <img  name="3.jpg"/>

     <img  name="4.jpg"/>

     <img  name="5.jpg"/>

     <img  name="6.jpg"/>

     <img  name="7.jpg"/>

     <img  name="8.jpg"/>

     <img  name="9.jpg"/>

     <img  name="10.jpg"/>

</imgs>

The xml is extremely simple, it just contains the name of each image.

Step 4 – Creating an XML Reader:

We should continue by creating a folder called “services” next to “view” and in it a new Actionscript Class called “XmlReader”, which will take care of extracting the data from the xml. This class should have two variables in its constructor, “xmlPath” as a string and “onComplete” as a function, It will also have a “loader” variable as a URLoader:

private var xmlPath:String;

private var onComplete:Function;

private var loader:URLLoader;

public function XmlReader(xmlPath:String,  onComplete:Function)

{

     this.xmlPath = xmlPath;

     this.onComplete = onComplete;

     loader = new URLLoader();

     loader.addEventListener(Event.COMPLETE,  completeHandler);

     loader.load(new URLRequest(xmlPath));

}

The path of the xml file is stored, (as well as “onComplete” which we will see in a minute), then the loader is initialized and triggered. The function “completeHandler()” will, as its name says, handle the loader once it’s done:

private function completeHandler(evt:Event):void

{

     var xmlDocument:XMLDocument = new  XMLDocument();

     xmlDocument.ignoreWhite  = true;

     var xml:XML = new XML(evt.target.data);

     xmlDocument.parseXML(xml.toString());

     for(var i:uint; i<xmlDocument.firstChild.childNodes.length;  i++)

          Model.data.push(xmlDocument.firstChild.childNodes[i].attributes.name);

     onComplete();

}

The handler parses all the data in the xml and injects it in the model. Of course, we need to go back to Model.as and declare this “data” variable that we are referring to. Just add it after all the constants:

public static var data:Array = [];

Finally (referring again to the completeHandler method), “onComplete()” gets called as soon as all the parsing is done. Remember that we designed this XmlReader to receive a reference to this external function when it is instantiated. This will simply be the function to be called when the reader has finished its job.

Step 5 – Using the reader:

Lets implement this now in the application’s main class, PhotoViewer3D.as. Carefully study these modifications:

package

{

     import com.li.photoviewer.services.XmlReader;

     import com.li.photoviewer.view.PhotoScene;

     import flash.display.Sprite;

     import flash.display.StageAlign;

     import flash.display.StageScaleMode;

     [SWF(backgroundColor="0x000000", frameRate="30")]

     public class PhotoViewer3D extends Sprite

     {

          public function PhotoViewer3D()

          {

               stage.scaleMode  = StageScaleMode.NO_SCALE;

               stage.align  = StageAlign.TOP_LEFT;

               var reader:XmlReader = new XmlReader(”data/data.xml”, init);

          }

          private function init():void

          {

               var photoScene:PhotoScene = new PhotoScene();

               addChild(photoScene);

          }

     }

}

I’ve just instantiated an XmlReader, pointed it to the xml path, put the creation of the scene in its own separate method, and also pointed the reader to this method so its called as soon as its done.

Step 6 – Loading the images:

The next step is pretty obvious. We now have the data array containing all the names of our images, waiting for us in the model and we’ve also delayed the creation of the 3D scene till after this data has been obtained. So we just need to alter the “initObjects()” method of PhotoScene.as to read this data. It’s too simple actually:

private function initObjects():void

{

     for(var i:uint; i<Model.data.length; i++)

     {

          var photo:PhotoLoader = new PhotoLoader("imgs/" + Model.data[i]);

          photo.x  = i*Model.PHOTO_SPACING;

          scene.addChild(photo);

          cameraController.maxX  = photo.x;

          photo.addOnMouseDown(photoClickHandler);

     }

}

That’s it. Test the application and see how it now loads all the corresponding different images. We’re practically done now, I just want to add an additional effect to the app…

Step 7 – Adding a reflection:

As it is usual in many open source projects, many people share their code in classes that can be very handy and easy to use. You can very often download a class that does a particular thing, use it, and never know how it actually works. So that’s what we’ll do, we will greatly enhance the look of our application by downloading a class, and I will make my point of showing how great it is to use other people’s classes, or even design classes yourself to be reusable in this way.

Download Reflection.as and paste it in the view folder.

The class should be ready to work, except that its package path is all wrong. This is pretty logical, since I’ve just used it for another project and it was placed completely on a different place. Correct this path to the class’ current location. You can also look into the class, now or later, to understand how it works and maybe learn new things that could motivate you to other uses or even new ideas with Away3D.

Step 8 – Plugging in the reflection:

Go back to PhotoScene.as and declare the reflection instance (we don’t need to import Reflection.as since it is in the same package as PhotoScene.as):

private var  reflection:Reflection;

Then, in the “initScene()” method, initialize it and add it to the display list:

reflection = new Reflection(scene, camera);
addChild(reflection);

And finally, in “renderScene()” add a call to the reflections rendering method:

private function renderScene(evt:Event):void

{

reflection.render();

view.render();

}

I also took the time to connect the Reflection class to the model and drop its arbitrary variables there. I even set up a USE_REFLECTION constant in the model and applied this Boolean value in the initialization of the reflection in “initScene()” and the “renderScene()” method too. All this allows you to, not only tweak the app to look good, but also to consider performance issues. With the values that you should have in the model after you do this, you can really optimize the application.

public static const USE_REFLECTION:Boolean = false;

public static const REFLECTION_OFFSET:Number = -525;

public static const REFLECTION_BLUR:Number = 8;

public static const REFLECTION_ALPHA:Number = 0.25;

public static const REFLECTION_SCALING:Number = 2;

So, that’s it! The application is flexible enough to be extended easily. Maybe a horizontal scroller could be a good idea, for example… I leave that to your creativity. I wanted to keep the MVC architecture as simple as I could by avoiding custom events, singleton classes, etc, but those could be good things to investigate for future projects. On the other hand, I really recommend playing with the Away3D engine, the possibilities with it are endless!!

I hope you’ve enjoyed the tutorial. I’m looking forward to make another one when I can =)

Step by step guide for creating a PicLens type 3D photo viewer with Flex and Away3d. This is step 2, of a 3 part tutorial that will sweep many useful techniques used in web application design, Flex, and Flash 3D design.

In the final the result will be this.

Requirements:

• Adobe Flash CS3
• Adobe Flex Builder 3
• Away3d Library (I recommend using the version I used)
• Tweener Library
• Source Files

Pre Requisites:

• Having done Part 1 of this tutorial
• Intermediate programming skills
• Moderate knowledge of AS3
• Basic Familiarity with OOP
• Basic knowledge of Flash CS3

Step 0

In this part we’re going to use the PhotoLoader component we designed previously, and set up the 3D scene showing multiple instances of it. Then, we’re going to develop the interactivity of the user for that scene. This will be the most intense part of the series, but hopefully the most fun.

Step 1 – Adapting the TestScene to the official scene

So, the first thing we have to do is rename our TestScene.as. Right click on the file, choose Rename and select PhotoScene as the new name. Flex should have updated the references to this class in your source, so that no errors are shown. However, you should go to the main file, “PhotoViewer3D” and rename the PhotoScene instance to “scene”, its not necessary, but its tidy. If any errors are thrown, it’s a good time to get to know the Flex Console. It is a panel at the bottom of Flex, in which errors are detected before compilation time. Its very probable that you noticed it already, just making sure. If you double click on one of the errors it shows you, Flex takes you directly to the source of that error. I really don’t know any quicker way to debug errors in Actionscript projects.

Step 2 – Multiple objects

Now, we’re going to modify the “initObjects()” method in PhotoScene to create 10 instances of PhotoLoader instead of just one, and arrange these instances horizontally. Use this code:

private function initObjects():void
{
     for(var i:uint; i<10; i++)
     {
          var photo:PhotoLoader = new PhotoLoader(“imgs/testImage.jpg”);
          photo.x  = i*700; <
          scene.addChild(photo);
     }
}

You should now see more instances to the right of the first one, even though we cant see all of them due to our limited camera control lines in the “renderScene()” method.

Step 3 – Enhancing camera controls

That’s what we’re going to do now; begin building a controller class that will provide more advanced camera user control. This part is pretty fun, since we’ve reached the level of complexity in which Away3D starts showing off its awesome capabilities.

Delete these lines in the “renderScene()” method in PhotoScene, we wont need them anymore:

camera.x = 3*(mouseX - stage.stageWidth/2);
camera.y = 3*(mouseY - stage.stageHeight/2);
camera.lookAt(new Number3D(0, 0, 0));

The new code that we will develop to achieve the enhanced camera motion will be more complex, logically, so it will not reside in our PhotoScene class. It will be in its own class, designed specifically for this, that is, camera motion control. Create a new folder next to “view” and name it “controller”. In it, create a new Actionscript Class named “CameraController”. Once done, make this class extend Sprite.

Now, back in PhotoScene.as, create a new variable named cameraController as:

private var cameraController:CameraController; 

After the “initScene()” call in the “init()” method in PhotoScene, place a new call to “initCameraController()”. And lets define this as follows:

private function initCameraController():void
{
    var cube:Cube = new Cube();
    cube.width  = cube.height = cube.depth = 10; 

     cube.z =  -100; 

     scene.addChild(cube); 

     cameraController  = new CameraController(camera, cube); 

     addChild(cameraController);

Don’t worry, I’ll explain. What we did is create a small cube and added it to the scene. Then, we instantiated our new CameraController, passing it two parameters and added it to the display. Why those two parameters? And what is the purpose of that cube?! As you will fully understand later, the cube will be used as the camera’s target, the camera will constantly be “looking” at it and trying to follow it. This is a very interesting technique used in 3D, since it provides a way to simulate natural and realistic camera motion effects.

Step 4 – Building the CameraController

Great, now lets go back to the controller and shape it up a little. In PhotoScene, when we instantiated it, we passed it 2 parameters. Lets assimilate them in the constructor and store these references. We’re also going to create an init method that will be called once the instance has been added to the stage, as we’ve done before:

private var camera:Camera3D; 

private var cameraTarget:Cube; 

public function CameraController(camera:Camera3D,  cameraTarget:Cube) 

{ 

     this.camera = camera; 

     this.cameraTarget = cameraTarget; 

     this.addEventListener(Event.ADDED_TO_STAGE, init, false, 0, true); 

} 

private function init(evt:Event):void 

{ 

     this.removeEventListener(Event.ADDED_TO_STAGE, init); 

}

Add a new event listener in the “init()” method to call a new “followTarget()” in enterframe.

this.addEventListener(Event.ENTER_FRAME,  followTarget);

And define “followTarget()” as:

private function followTarget(evt:Event):void 

{ 

     cameraTarget.x  += 10; 

     camera.lookAt(cameraTarget.position); 

}

Test it out. You should be able to see the little cube starting next to the first photo and then moving to the right. The camera will look at it as it goes away. Lets extend it a bit further by telling the camera not just to look at it, but also to try to keep up with it. Add these lines to the “followTarget()” method:

var  dX:Number = cameraTarget.x - camera.x;

camera.x += dX*0.05;

Test it again… Im sure you can tell the different and understand the code with what you see.

Before we go on, delete the first line in “followTarget()” that moves the camera target to the right, it was just used for demonstration purposes. From now on, the target wont move by its own, we are going to move it.

Step 5 – Setting up interactivity

That looks good, but now lets make it more realistic, and most importantly, interactive. In PhotoScene, we are going to modify the “initObjects()” method again to register a click listener on the photos, and that method is going to call another method in the camera controller, telling it to move the camera to that photo. Don’t worry, you’ll be amazed by how simple this is going to be.

In the for loop inside of “initObjects()” in PhotoScene, add this line at the end:

photo.addOnMouseDown(photoClickHandler);

And add a couple of lines in the constructor of PhotoLoader to tell the cursor to show a hand when we roll over the photos:

this.ownCanvas = true; 

this.useHandCursor = true; 

Then, define the “photoClickHandler()” back in PhotoScene method as:

private function photoClickHandler(evt:MouseEvent3D):void 

{ 

     cameraController.moveTo(evt.object.x); 

}

Yes, we need to define the public “moveTo()” method in the CameraController, so lets do it:

public function moveTo(X:Number):void 

{ 

Tweener.addTween(cameraTarget, {x:X,  time:1, transition:“easeoutexpo”}); 

}

It will work as long as you import the Tweener class in CameraController. Test the application and click on the images. That’s it!!

Step 6 – Setting up mouse drag

Next, the app is going to have a pretty cool feature, which is the ability of the user to click on the canvas and drag himself (the camera that is) around the scene. We’ll manage this in 3 steps, so follow along.

First, we’re going to need 2 clips that will capture the mouse down and mouse up for the dragging. One will be behind the photos, and the other above them. Besides, we will take advantage of the one behind to make the app look a bit better by using it as a background as well. Modify “initScene()” in PhotoScene like this:

private function initScene():void 

{ 

     scene = new Scene3D(); 

     camera = new Camera3D(); 

     camera.zoom  = 10; 

     camera.focus  = 200; 

     camera.z =  -2000; 

     background  = new Sprite(); 

     var mat:Matrix = new Matrix(); 

     mat.rotate(-Math.PI/2); 

     background.graphics.beginGradientFill(GradientType.LINEAR,  [0x222222, 0x000000], [1, 1], [0, 80], mat); 

     background.graphics.drawRect(0,  0, stage.stageWidth, stage.stageHeight); 

     background.graphics.endFill(); 

     addChild(background); 

     background.addEventListener(MouseEvent.MOUSE_DOWN,  handleBackgroundMouseDown); 

     view = new View3D(); 

     view.camera  = camera; 

     view.scene  = scene; 

     view.x =  stage.stageWidth/2; 

     view.y =  stage.stageHeight/2; 

     view.clip  = new RectangleClipping(-stage.stageWidth/2,  -stage.stageHeight/2, stage.stageWidth/2, stage.stageHeight/2); 

     addChild(view); 

     foreground  = new Sprite(); 

     foreground.graphics.beginFill(0×00FF00,  0.5); 

     foreground.graphics.drawRect(0,  0, stage.stageWidth, stage.stageHeight); 

     foreground.graphics.endFill(); 

     foreground.visible  = false; 

     addChild(foreground); 

     foreground.addEventListener(MouseEvent.MOUSE_UP,  handleForegroundMouseUp); 

     foreground.addEventListener(MouseEvent.MOUSE_OUT,  handleForegroundMouseUp); 

}

And don’t forget to declare background and foreground private variables at the beginning of the class, plus import the GradientType class:

import flash.display.GradientType; 

What we just did was add these two before and after the view. It was done in this order to maintain the layering we talked about before. The background is simply a sprite with a gradient, and the foreground is a semi transparent green clip above everything. Comment the 3 listener lines we’ve just added, and “foreground.visible = false” and test the app. As you can see, the sprites have been added to the display.

Now, uncomment those lines and go ahead and define the handler methods as:

private function handleBackgroundMouseDown(evt:MouseEvent):void 

{ 

     foreground.visible  = true; 

} 

private function handleForegroundMouseUp(evt:MouseEvent):void 

{ 

     foreground.visible  = false; 

}

If you test the app again, you’ll see the idea behind all this. The background captures the mouse down and shows the foreground, which is simply there to capture the mouse up. Even though this might look confusing, its pretty practical. If it wasn’t there and we had set up the background to capture the mouse up, it wouldn’t work very well since we could press on the background and then, while the mouse is still pressed, move over to a photo and release the mouse once we’re there… The background wouldn’t have captured the mouse up, because the photo would have captured it. So, what we’ve just done makes sure we don’t have to worry about this kind of stuff. It’s solid, Im sure there might be other methods, but Im comfortable with this one. Before we continue, set the foreground’s draw alpha from 0.5 to 0 so we don’t see it anymore (it will do its job anyway).

Step 7 – Designing the mouse drag

We need to define the dragging now. On the handlers we’ve just created, add “cameraController.startCameraDrag();” for the mouse down handler, and “cameraController.stopCameraDrag();” for the mouse up handler. And of course, we need to define those methods in the CameraController class. These two methods will simply toggle a mouse move event listener that will continuously call a dragCamera method while the mouse is pressed:

public function startCameraDrag():void 

{ 

lastMouseX = stage.mouseX; 

     stage.addEventListener(MouseEvent.MOUSE_MOVE,  dragCamera, false, 0 , true); 

} 

public function stopCameraDrag():void 

{ 

     stage.removeEventListener(MouseEvent.MOUSE_MOVE,  dragCamera); 

} 

private function dragCamera(evt:MouseEvent):void 

{ 

     var dX:Number = lastMouseX - stage.mouseX; 

     cameraTargetVX  += dX*0.1; 

     lastMouseX  = stage.mouseX; 

}

Of course, you’re going to need to define “lastMouseX” and “cameraTargetVX” as private variables at the top of the class. Make sure you set cameraTargetVX to zero when you declare it. Ill explain what’s going on shortly, I want you to see it working first…

To apply what we’ve just done, add these lines to the “followTarget()” method:

cameraTarget.x += cameraTargetVX; 

cameraTargetVX *= 0.95;

And to correct incongruencies, add “cameraTargetVX = 0;” in the “moveTo()” method.

Check it out by testing the app and clicking and dragging from the background. Its simple code, with pretty impressive smooth results. So, as I said, let me explain a little now. When a drag is started, the controller stores the current mouse position and begins the continuous call to the drag method. In this method, the first thing that happens is that the stored initial mouse position is compared to the actual mouse position every time the mouse moves. This value is then used to alter “cameratargetVX” which is just a variable that represents the velocity of the camera, and the current mouse position is again stored. On the mean time, in the “followTarget()” method, the velocity variable is constantly being added to the cameraTarget’s position. This is the very basics of simulating velocity physics on programming. In this method, the velocity value is also dampened by 5% to simulate friction. Finally, the “stopCameraDrag()” method unplugs the continuous call to “dragCamera()”.

Step 8 – Adding zoom

Next, we will add a cool zoom effect, which is going to be really simple. Add this methods in Camera Controller:

private function zoomIn():void 

{ 

     Tweener.addTween(camera,  {z:-1500, time:1, transition:“easeoutexpo”}); 

} 

private function zoomOut():void 

{ 

     Tweener.addTween(camera,  {z:-2000, time:1, transition:“easeoutexpo”}); 

}

And add a zoomIn() call in the “moveTo()” method, and a zoomOut() call in the “startCameraDrag()” method. Test the app. It’s as simple as that, we now have a little zoom effect working.

Step 9 – Containing motion

Before we finish this part of the tutorial, we need to face a little issue you might have noticed: The user can drag himself far away from the photos, and we don’t want this. We want to contain the camera in an area where the user will always see the photos.

To define the area that the user will move in, define two public variables in CameraController. They’re public because, even though we define them in CameraController, they will be filled up from the PhotoScene each time a new photo is created:

public var minX:Number = 0; 

public var maxX:Number =  0;

Now go to PhotoScene and, in “initObjects()” add “cameraController.maxX = photo.x;” inside the end of for loop. This results in that each time a photo is created, the scene reports the camera controller how far the camera target should be able to move.

Now last, but not least, add this containment code to the end of “followTarget()” in cameraController:

if(cameraTarget.x  > maxX) 

{ 

     cameraTarget.x  = maxX; 

     cameraTargetVX  *= -0.5; 

} 

else if(cameraTarget.x < minX) 

{ 

     cameraTarget.x  = minX; 

     cameraTargetVX  *= -0.5; 

}

This simply checks if the target has exceeded the limits of the scene, and if so, docks the target at one of the limits and inverts its velocity to make it “bounce”. You may enhance this code by making it consider positions before a velocity value is applied, etc. It would look better, but I wanted to keep things as simple as possible here.

And that does it for part 2 of the tutorial… To wrap things up go to PhotoScene and add “cube.visible = false;” in “initCameraController()” so that the little cube is hidden from the user.

Next

On part 3 we will give the application a closure by centralizing arbitrary variables, enhancing graphics a bit, and connecting it to an external XML that will indicate it what images to load.

This tutorial article is a Step by step guide for creating a PicLens type 3D photo viewer with Flex and Away3d. This is step 1, of a 3 part tutorial that will sweep many useful techniques used in web application design, Flex, and Flash 3D design.

In the final the result will be this.

Requirements

• Adobe Flash CS3
• Adobe Flex Builder 3
• Away3d Library (I recommend using the version I used)
• Tweener Library
• Source Files

Pre Requisites

• Intermediate programming skills
• Moderate knowledge of AS3
• Basic Familiarity with OOP
• Basic knowledge of Flash CS3

Step 0

In this tutorial I will assume that you are familiar with the basics of building an Actionscript Away3D project in Flex. If you haven’t used these two technologies together before, it would be best if you go through my previous tutorial first. Due to the complexity of this application, I will need to skip some things to go faster. So, if something is not explained here, or suddenly a large chunk of code is dropped with no descriptions, it has been covered (hopefully) in the mentioned tutorial.

Step 1 – New Project

Lets get started. Create a new Actionscript Project in Flex and name it “PhotoViewer3D”. Then, download the libraries I listed in the requirements and paste them in the project’s folder.

Now, one of the things that will be covered here is a very simplified application architecture that could be a good starting point for any project you do that implies a moderate level of complexity. For this, all code will be placed in a folder structure, carefully separating functions between different classes, and hence emulating the basics of a Model View Controller design pattern. You should have a general grasp of it by the end of this series.

Right click on the project’s folder in the Flex Navigator and choose New -> Folder, then type “com/li/photoviewer/view” and press Finish. Naming folders this way is known as Reverse Domain Syntax, and is a good programming practice.

Step 2 – Setting up the scene

Go to PhotoViewer3D.as and build a basic main class:

package
{
     import flash.display.Sprite;
     import flash.display.StageAlign;
     import flash.display.StageScaleMode;

     import com.li.photoviewer.view.TestScene;

[SWF(backgroundColor="0x000000", frameRate="30")] 

     public class PhotoViewer3D extends Sprite
     {
          public function PhotoViewer3D()
          {
               stage.scaleMode  = StageScaleMode.NO_SCALE;
               stage.align  = StageAlign.TOP_LEFT;

               var testScene:TestScene = new TestScene();
               addChild(testScene);
          }
     }
}

Line 7 imports an away3D holding class that we haven’t made yet, so we should create it right away. Right click on the “view” folder and choose New -> Actionscript Class and name it “TestScene”. It should have the following code in it:

package com.li.photoviewer.view 

{ 

     import away3d.cameras.Camera3D;
     import away3d.containers.Scene3D;
     import away3d.containers.View3D;
     import away3d.core.clip.RectangleClipping;
     import away3d.core.math.Number3D; 

     import flash.display.Sprite;
     import flash.events.Event; 

     public class TestScene extends Sprite
     {
          private var scene:Scene3D;
          private var camera:Camera3D;
          private var view:View3D; 

          public function TestScene()
          {
               addEventListener(Event.ADDED_TO_STAGE,  init, false, 0, true);
          } 

          public function init(evt:Event):void
          {
               removeEventListener(Event.ADDED_TO_STAGE,  init); 

               initScene();
               initObjects();
               addEventListener(Event.ENTER_FRAME,  renderScene);
          } 

          private function initScene():void
          {
               scene  = new Scene3D(); 

               camera  = new Camera3D();
               camera.zoom  = 10;
               camera.focus  = 200;
               camera.z  = -2000; 

               view  = new View3D();
               view.camera  = camera;
               view.scene  = scene;
               view.x  = stage.stageWidth/2;
               view.y  = stage.stageHeight/2;
               view.clip  = new RectangleClipping(-stage.stageWidth/2,  -stage.stageHeight/2, stage.stageWidth/2, stage.stageHeight/2);
               addChild(view);
          } 

          private function initObjects():void
          {
                
          } 

          private function renderScene(evt:Event):void
          {
               camera.x  = 3*(mouseX - stage.stageWidth/2);
               camera.y  = 3*(mouseY - stage.stageHeight/2);
               camera.lookAt(new Number3D(0, 0, 0)); 

               view.render();
          }
     }
}

NOTE: If any of this shocked you, it has all been explained in the tutorial mentioned in Step 0.

Step 3 – Setting up our PhotoLoader component

Create a new Actionscript Class in the view folder and name it “PhotoLoader”. These will be our 3D photograph object. The class will extend Away3D’s Plane primitive, with a few additional features, more particularly, the ability to load an external image. So, lets start by setting up the plane:

package com.li.photoviewer.view
{
import away3d.primitives.Plane;

public class PhotoLoader extends Plane
     {
private var urlPath:String;

          public function PhotoLoader(urlPath:String)
          { 

               super();

               this.urlPath = urlPath;

               this.rotationX = 90;
               this.width = 640;
               this.height = 480;
               this.segmentsH = 4;
               this.segmentsW = 4;
          }
     }
}

As you can see, we’ve set up the constructor so that when we instantiate a PhotoLoader object, we pass it the image name it has to load as a parameter. Now, go back to TestScene, and in the “iniObjects()” method, make an instance of PhotoLoader and add it to the scene:

var testPhoto:PhotoLoader = new PhotoLoader(“imgs/testImage.jpg”);

scene.addChild(testPhoto);

The urlPath we passed this time will be irrelevant, but we’ll pass it anyway so no errors are thrown. Go ahead and test the application, you should see something like this:

Step 4 – Skinning the plane with Flash

First of all, we need to give the plane a skin or texture. Even though it will contain an image, it needs to contain something else while it’s loading, and somehow show progress for that load process. For this, we will design some graphics in Flash, and bring them to Flex with what I find to be a very practical and simple technique. We will use a fla file to generate a library.swf file that will contain some graphics for our application, and then embed that swf in Flex and extract the clips as we need them. This is a very useful technique, and I definitely recommend it for any Flex projects that contain design based vector graphics.

Open Flash, create a new AS3 Flash File and save it in your project’s folder, next to PhotoViewer3D.as. Once in it, select File -> Publish Settings and type “assets/library.swf” for the swf output path (deselect the html output). Now, create a new folder next to that fla called “assets” either from your file explorer or by right clicking the project’s folder in the Flex Navigator. Now, if you publish the fla you will see that library.swf shows up in your newly created assets folder.

Step 5 – Creating and extracting the graphics created in Flash

Great, now I wont be describing how to make the graphics in Flash since I believe you must be very familiar with this. You should download the fla and overwrite the one you just made. Sorry! Just wanted to make sure you understood what’s going on. Now, open the downloaded fla. You will see a clip called “LoaderFront” made up of a gray box and a progressBar clip which has in turn a sub clip. The important thing to notice here is that LoaderFront has a Linkage and its Base Class was changed to Sprite. Publish it again, go back to Flex, right click on library.swf in the assets folder and choose Refresh.

This is the only code you’ll need to pull those graphics from Flex, type it at the top of the PhotoLoader class (inside Public class…):

[Embed(source="assets/library.swf", symbol="LoaderFront")]
public var LoaderFront:Class;

You’ve just extracted the symbol from the swf’s library and assigned it to a LoaderFront class. If you create a new instance of this class (and add it to the display tree), you’ll have a graphics object that extends Sprite! And you can treat it as any other sprite. Great isn’t it?

Step 6 – Applying the graphics to the plane

Go back to PhotoLoader.as and create these variables for the class:

private var materialSprite:Sprite;
private var progressBar:Sprite;
private var progressBarSubClip:Sprite;

And then this method:

private function initClips():void
{
     materialSprite  = new LoaderFront();

     progressBar  = Sprite(materialSprite.getChildByName(“progressBar”));
     progressBarSubClip  = Sprite(progressBar.getChildByName(“subClip”));
}

Now we have references to all the clips that we need. You have to add the “initClips()” call at the end of the constructor class.

Next, type this new method under the last one and also make sure you call it from the constructor:

private function initMaterial():void
{
     var material:MovieMaterial = new MovieMaterial(materialSprite);
     material.smooth  = true;

     this.material = material;
}

And Test the application. You should now see that the plane has taken the graphics as its material. Your PhotoLoader class should look like this so far:

package com.li.photoviewer.view
{
     import away3d.materials.MovieMaterial;
     import away3d.primitives.Plane;
     import flash.display.Sprite;
     public class PhotoLoader extends Plane
     {
         [Embed(source="assets/library.swf", symbol="LoaderFront")]
          public var LoaderFront:Class;
          private var urlPath:String;
          private var materialSprite:Sprite;
          private var progressBar:Sprite;
          private var progressBarSubClip:Sprite;
          public function PhotoLoader(urlPath:String)
          {
               super();
               this.urlPath = urlPath;
               this.rotationX = 90;
               this.width = 640;
               this.height = 480;
               this.segmentsH = 4;
               this.segmentsW = 4;
               initClips();
               initMaterial();
          }
          private function initClips():void
          {
               materialSprite  = new LoaderFront();
               progressBar  = Sprite(materialSprite.getChildByName(“progressBar”));
               progressBarSubClip  = Sprite(progressBar.getChildByName(“subClip”));
          }
          private function initMaterial():void
          {
               var material:MovieMaterial = new MovieMaterial(materialSprite);
               material.smooth  = true;
               this.material = material;
          }
     }
}

Step 7 – Loading images into the plane

The final thing to do for Part 1 of this tutorial, is implement all the image loading features of our extended plane. For this, we will use a regular Loader instance and add a few event listeners to check for progress and complete events.

Add the loader variable next to the other class variables:

private var loader:Loader;

And call a new method under the “initMaterial()” call in the constructor as “initLoader()”, then build the method:

private function initLoader():void
{
     loader = new Loader();
     loader.contentLoaderInfo.addEventListener(ProgressEvent.PROGRESS,  progressHandler);
     loader.contentLoaderInfo.addEventListener(Event.INIT,  initHandler);
     materialSprite.addChild(loader);
     loader.alpha  = 0;
}

The loader is initialized, two listeners are registered, then the loader is injected to the plane’s material sprite completely invisible. I’ve made it invisible because I’m going to make it fade in once the image has been loaded into it.

Now, lets set up the handlers and a little “setProgress()” utilitary method:

private function progressHandler(evt:ProgressEvent):void
{
     setProgress(evt.bytesLoaded/evt.bytesTotal);
}
private function initHandler(evt:Event):void
{
     Tweener.addTween(loader,  {alpha:1, time:1, transition:“easeoutexpo”});
}
 
private function setProgress(value:Number):void
{
     progressBarSubClip.scaleX  = value;
}

Pretty straight forward. As the image downloads, the progress handler calls the “setProgress()” function which in turn sets the horizontal scale of the progress bar, and when the download completes, or more precisely when the loaded content is initialized, Tweener makes the loader fade in by animating its alpha. Don’t forget to import Tweener for this:

import caurina.transitions.Tweener;

Step 8 – Triggering the load

Next, lets trigger the load by adding a “loadImage()” method as the last method called in the constructor and defining it:

private function loadImage():void
{
     loader.unload();
     loader.alpha  = 0;
     setProgress(0);
     loader.load(new URLRequest(urlPath));
}

Finally, create the imgs folder in the project, download THESE images and paste them in it. Test the app, you should see the image loaded on the plane:

Watch the Demo HERE.

Next:

On the next part we will continue to develop our application by using multiple instances of this PhotoLoader object, developing advanced camera motion and interactivity.

In this second part tutorial we’re going to add some more features to the slideshow application.

Those would be forwarding and rewinding slides, play and pause the slideshow and linkable slides. If you haven’t read the first part tutorial yet, you should do it before continue. You can read it here.

Requirements

Adobe Flash CS3

Try / Buy

Sample files:

slideshowprt2.zip

Adjust XML structure

To store the link of each slide, we just add it as an attribute to the xml file, or to be more accurate, on the image nodes. We also set the target window of the link, which might be neccesary to set in some cases. So, our xml is looking now like this:

<slideshow>
	<image src="images/fly.jpg" desc="Fly" link="http://www.wikipedia.org" target="_self"/>
	<image src="images/mouse.jpg" desc="Computer mouse" link="http://www.google.com" target="_blank"/>
	<image src="images/country.jpg" desc="Country" link="http://www.thetechlabs.com" target="_self"/>
	<image src="images/rope.jpg" desc="Rope" link="http://www.amazon.com" target="_blank"/>
	<image src="images/flower.jpg" desc="Flower" link="http://www.adobe.com" target="_self"/>
</slideshow>

Adding new objects

Since we know, how the xml looks like, we can move on to the knew stuff on the stage. In the mcInfo movieclip we’ve added 4 new buttons. Pause/Play and Forward/Rewind, which will later be assigned to event listeners. On the main stage is a invisible button as big as the size of the slides which will be used to open the links defined in the xml.
Alright, that’s already enough to go on with the coding part.

Adding new variables

First of all, we need to add some new variables to our script.

To know, if the slideshow is currently playing or paused, we set a flag:

var bolPlaying:Boolean = true;

And we also store the current slide link and target window in a variable:

var strLink:String = "";
var strTarget:String = "";

Init function

This is all we need for the variable. Now let’s take a look about what’s changing in the init function of the slideshow. We added the following two lines at the beginning of the function to prevent the user to click any button as long as the xml file hasn’t been loaded completely:

	mcInfo.visible = false;
	btnLink.visible = false;

We’ve also changed the function that will be called once the slideTimer event is fired. Now the function nextSlide() will be called, which we’ll create later:

	slideTimer.addEventListener(TimerEvent.TIMER, nextSlide);

On the last line of the initSlideshow() function we add the event listeners for the buttons. The play and button pause event listeners will be assigned to the same function togglePause(). The next and previous button will be asssigned to the nextSlide() and previousSlide() function. And last of all, we connect the invisible link button that covers the slide area with the goToWebsite() function. And since our slideshow will automatically be playing at the beginning, we hide the play button.

	btnLink.addEventListener(MouseEvent.CLICK, goToWebsite);
	mcInfo.btnPlay.addEventListener(MouseEvent.CLICK, togglePause);
	mcInfo.btnPause.addEventListener(MouseEvent.CLICK, togglePause);
	mcInfo.btnNext.addEventListener(MouseEvent.CLICK, nextSlide);
	mcInfo.btnPrevious.addEventListener(MouseEvent.CLICK, previousSlide);
	mcInfo.btnPlay.visible = false;

onXMLLoadComplete function

Once the xml is completely loaded, we need to show the mcInfo and the button link again. So we add the following two line of code to the function onXMLLoadComplete()

	mcInfo.visible = true;
	btnLink.visible = true;

And since our switchSlide() function will now need to have the index number of the slide, we add a zero as the parameter. We’ll explain the changes in the switchSlide() function later.

	switchSlide(0);

NextSlide/PreviousSide function

Let’s take a look at the nextSlide() and previousSlide() functions. They are called when clicking the next and previous button and the nextSlide() function is also called when the Timer event of the sliderTimer has been fired.
The nextSlide() function checks, if there are any slides left to move on. If so, the current switchSlide() function will be called with the next slide index. If there are no more slides left, then the parameter will be zero standing for the first slide.
The previousSlide() function works the same way. If there are slide we can go back, then the switchSlide() function will be called with the previous slide index. If we’re already on the first slide, then we start the slideshow from the last slide with calling the switchSlide() function with the parameter of the total slide count minus one since the array count begins with zero.

function nextSlide(e:Event = null):void {
	if(intCurrentSlide + 1 < intSlideCount)
		switchSlide(intCurrentSlide + 1);
	else
		switchSlide(0);

}

function previousSlide(e:Event = null):void {
	if(intCurrentSlide - 1 >= 0)
		switchSlide(intCurrentSlide - 1);
	else
		switchSlide(intSlideCount - 1);
}

SwitchSlide function

Since the nextSlide() and previousSlide() functions are now handling the checking for the slides, we can take out this part in the switchSlide() function.
To prevent the user from clicking too fast on the next and previous button, we check, if the tweener is still fading in the slides. If so, we just ignore the action. We’re doing this by adding the following if-statement to the first line of the switchSlide() function.

	if(!Tweener.isTweening(currentContainer)) {

Now we only need to set the new link and the target of it. This will be done exactly the same way as setting the description of the slide.

		strLink		= xmlSlideshow..image[intCurrentSlide].@link;
		strTarget	= xmlSlideshow..image[intCurrentSlide].@target;

FadeSideIn function

The fadeSlideIn() function has also a small addition. We check if the slideshow is currently playing and show the number of seconds to the next slide. If the slideshow is paused, we show a status message. The text will be assigned to the lbl_info label.

	if(bolPlaying) {
		mcInfo.lbl_loading.text = "Next slide in " + TIMER_DELAY / 1000 + " sec.";
	} else {
		mcInfo.lbl_loading.text = "Slideshow paused";
	}

OnSlideFadeIn function

On the onSlideFadeIn() function we now need to check, if the slideshow is playing. If so, we can start the timer again:

	if(bolPlaying && !slideTimer.running)
		slideTimer.start();

TogglePause function

The togglePause() function will be called when the user clicks on the play and pause button. First, we check, if the slideshow is playing, if so, we show the play button, set the bolPlaying variable to false, change the status message of the lbl_info label to “Slideshow paused” and stop the timer.
If the slideshow is currently paused, we show the pause button, set the bolPlaying variable to true again, show the time to the next slide and restart the timer.

function togglePause(e:MouseEvent):void {
	if(bolPlaying) {
		mcInfo.btnPlay.visible = true;
		mcInfo.btnPause.visible = false;

		bolPlaying = false;
		mcInfo.lbl_loading.text = "Slideshow paused";
		slideTimer.stop();
	} else {
		mcInfo.btnPlay.visible = false;
		mcInfo.btnPause.visible = true;

		bolPlaying = true;
		mcInfo.lbl_loading.text = "Next slide in " + TIMER_DELAY / 1000 + " sec.";
		slideTimer.reset();
		slideTimer.start();
	}
}

GotToWebsite function

The last function we need to define is the goToWebsite() function. This function will be called once the user clicks on the invisible button. It will check, if the strLink variable is empty or null. If not, the link will be opened.

function goToWebsite(e:MouseEvent):void {
	if(strLink != "" && strLink != null) {
		navigateToURL(new URLRequest(strLink), strTarget);
	}
}

We’ve already reached the end of the second part of the slideshow tutorial. We hope that you enjoyed reading it and we appreciate any kind of feedback.

Note

The feature for clicking the invisible button only works, when you’re running the flash on a webserver or in the flash sdk.

Full code with comments

// import tweener
import caurina.transitions.Tweener;

// delay between slides
const TIMER_DELAY:int = 5000;
// fade time between slides
const FADE_TIME:Number =	1;

// flag for knowing if slideshow is playing
var bolPlaying:Boolean = true;
// reference to the current slider container
var currentContainer:Sprite;
// index of the current slide
var intCurrentSlide:int = -1;
// total slides
var intSlideCount:int;
// timer for switching slides
var slideTimer:Timer;
// slides holder
var sprContainer1:Sprite;
var sprContainer2:Sprite;
// slides loader
var slideLoader:Loader;
// current slide link
var strLink:String = "";
// current slide link target
var strTarget:String = "";
// url to slideshow xml
var strXMLPath:String = "slideshow-data.xml";
// slideshow xml loader
var xmlLoader:URLLoader;
// slideshow xml
var xmlSlideshow:XML;

function initSlideshow():void {
	// hide buttons, labels and link
	mcInfo.visible = false;
	btnLink.visible = false;

	// create new urlloader for xml file
	xmlLoader = new URLLoader();
	// add listener for complete event
	xmlLoader.addEventListener(Event.COMPLETE, onXMLLoadComplete);
	// load xml file
	xmlLoader.load(new URLRequest(strXMLPath));

	// create new timer with delay from constant
	slideTimer = new Timer(TIMER_DELAY);
	// add event listener for timer event
	slideTimer.addEventListener(TimerEvent.TIMER, nextSlide);

	// create 2 container sprite which will hold the slides and
	// add them to the masked movieclip
	sprContainer1 = new Sprite();
	sprContainer2 = new Sprite();
	mcSlideHolder.addChild(sprContainer1);
	mcSlideHolder.addChild(sprContainer2);

	// keep a reference of the container which is currently
	// in the front
	currentContainer = sprContainer2;

	// add event listeners for buttons
	btnLink.addEventListener(MouseEvent.CLICK, goToWebsite);
	mcInfo.btnPlay.addEventListener(MouseEvent.CLICK, togglePause);
	mcInfo.btnPause.addEventListener(MouseEvent.CLICK, togglePause);
	mcInfo.btnNext.addEventListener(MouseEvent.CLICK, nextSlide);
	mcInfo.btnPrevious.addEventListener(MouseEvent.CLICK, previousSlide);

	// hide play button
	mcInfo.btnPlay.visible = false;
}

function onXMLLoadComplete(e:Event):void {
	// show buttons, labels and link
	mcInfo.visible = true;
	btnLink.visible = true;	

	// create new xml with the received data
	xmlSlideshow = new XML(e.target.data);
	// get total slide count
	intSlideCount = xmlSlideshow..image.length();
	// switch the first slide without a delay
	switchSlide(0);
}

function fadeSlideIn(e:Event):void {
	// add loaded slide from slide loader to the
	// current container
	currentContainer.addChild(slideLoader.content);
	// clear preloader text
	mcInfo.lbl_loading.text = "";

	// check if the slideshow is currently playing
	// if so, show time to the next slide. If not, show
	// a status message
	if(bolPlaying) {
		mcInfo.lbl_loading.text = "Next slide in " + TIMER_DELAY / 1000 + " sec.";
	} else {
		mcInfo.lbl_loading.text = "Slideshow paused";
	}

	// fade the current container in and start the slide timer
	// when the tween is finished
	Tweener.addTween(currentContainer, {alpha:1, time:FADE_TIME, onComplete:onSlideFadeIn});
}

function onSlideFadeIn():void {
	// check, if the slideshow is currently playing
	// if so, start the timer again
	if(bolPlaying && !slideTimer.running)
		slideTimer.start();
}

function togglePause(e:MouseEvent):void {
	// check if the slideshow is currently playing
	if(bolPlaying) {
		// show play button
		mcInfo.btnPlay.visible = true;
		mcInfo.btnPause.visible = false;

		// set playing flag to false
		bolPlaying = false;
		// set status message
		mcInfo.lbl_loading.text = "Slideshow paused";
		// stop the timer
		slideTimer.stop();
	} else {
		// show pause button
		mcInfo.btnPlay.visible = false;
		mcInfo.btnPause.visible = true;

		// set playing flag to true
		bolPlaying = true;
		// show time to next slide
		mcInfo.lbl_loading.text = "Next slide in " + TIMER_DELAY / 1000 + " sec.";
		// reset and start timer
		slideTimer.reset();
		slideTimer.start();
	}
}

function switchSlide(intSlide:int):void {
	// check if the last slide is still fading in
	if(!Tweener.isTweening(currentContainer)) {
		// check, if the timer is running (needed for the
		// very first switch of the slide)
		if(slideTimer.running)
			slideTimer.stop();

		// change slide index
		intCurrentSlide = intSlide;

		// check which container is currently in the front and
		// assign currentContainer to the one that's in the back with
		// the old slide
		if(currentContainer == sprContainer2)
			currentContainer = sprContainer1;
		else
			currentContainer = sprContainer2;

		// hide the old slide
		currentContainer.alpha = 0;
		// bring the old slide to the front
		mcSlideHolder.swapChildren(sprContainer2, sprContainer1);

		// create a new loader for the slide
		slideLoader = new Loader();
		// add event listener when slide is loaded
		slideLoader.contentLoaderInfo.addEventListener(Event.COMPLETE, fadeSlideIn);
		// add event listener for the progress
		slideLoader.contentLoaderInfo.addEventListener(ProgressEvent.PROGRESS, showProgress);
		// load the next slide
		slideLoader.load(new URLRequest(xmlSlideshow..image[intCurrentSlide].@src));

		// show description of the next slide
		mcInfo.lbl_description.text = xmlSlideshow..image[intCurrentSlide].@desc;

		// set link and link target variable of the slide
		strLink		= xmlSlideshow..image[intCurrentSlide].@link;
		strTarget	= xmlSlideshow..image[intCurrentSlide].@target;

		// show current slide and total slides
		mcInfo.lbl_count.text = (intCurrentSlide + 1) + ” / ” + intSlideCount + ” Slides”;
	}
}

function showProgress(e:ProgressEvent):void {
	// show percentage of the bytes loaded from the current slide
	mcInfo.lbl_loading.text = “Loading…” + Math.ceil(e.bytesLoaded * 100 / e.bytesTotal) + “%”;
}

function goToWebsite(e:MouseEvent):void {
	// check if the strLink is not empty and open the link in the
	// defined target window
	if(strLink != “” && strLink != null) {
		navigateToURL(new URLRequest(strLink), strTarget);
	}
}

function nextSlide(e:Event = null):void {
	// check, if there are any slides left, if so, increment slide
	// index
	if(intCurrentSlide + 1 < intSlideCount)
		switchSlide(intCurrentSlide + 1);
	// if not, start slideshow from beginning
	else
		switchSlide(0);

}

function previousSlide(e:Event = null):void {
	// check, if there are any slides left, if so, decrement slide
	// index
	if(intCurrentSlide - 1 >= 0)
		switchSlide(intCurrentSlide - 1);
	// if not, start slideshow from the last slide
	else
		switchSlide(intSlideCount - 1);
}

// init slideshow
initSlideshow();

In this series of tutorials, you will learn the basics of architecting a simple but powerful Web Services Package. We’ll start off by creating a class which will be the base of all our services and then continue to create a very simple Twitter API.

Please note that due to changes in the Twitter cross domain policy, the API we will create in this tutorial will not work online, but works perfectly in an AIR application.

Requirements

Adobe Flash CS3

Try / Buy

Adobe Intergrated Runtime (AIR) for Flash CS3

Download

Source Files

Download

Pre-Requesites

Some experience in creating classes in AS3, if you dont know how to, don’t worry, you’ll learn here

Create the package

The first thing we need to do before actually coding anything is to create our class package. Creating a class package is very simple, we’ll create it right on our desktop. All you have to do is create a folder and name it “com”, that will be the main package. inthe “com” folder, create another folder identifying the name of your webservices collection, I’ll call mine “reyco1″. now in the “reyco1″ folder create another folder called “webservices”. That’s it! package creation complete. Now how easy was that? Very!

Now create create an Actionscript file, name it “WebService.as” and save it in the “webservices” folder. This is the class that all our apis, such as Twitter API will use to connect to their respective web services. Crack that puppy open and lets get to the coding goodness!

Coding the main WebService class

All AS3 classes are contained within a package. We already created our package in the first step, basically a few nested folders. So we’ll start our class as so:

package com.reyco1.webservice
{

}

Now we need to import the classes that we need from flash in order to make our class work:

package com.reyco1.webservice
{
	import flash.events.*;
	import flash.net.*;
}

Our class will extend the “EventDispatcher” class which means that we will be able to dispatch much needed events. It will have additional properties and methods which we will include in later steps. In the meantime your class should look like this:

package com.reyco1.webservice
{
	import flash.events.*;
	import flash.net.*;

	public class WebService extends EventDispatcher
	{

    }

}

Now we create the variables that we will need in order to connect to the online web services. We’ll need a URLRequest, a URLLoader and a URLVariables along with a generic data variable that will hold information returned from the web service. We want to make this data variable public so that it can be accessed from outside the class:

package com.helix.webservice
{
	import flash.events.*;
	import flash.net.*;

	public class WebService extends EventDispatcher
	{

		private var request:URLRequest;
		private var loader:URLLoader;
		private var variables:URLVariables;
		public var data:*

    }

}

Now that we have all the variables we need, we can go ahead and create our constructor. The class constructor is a special method always named the same name as the class. Constructors can accept arguments or not. Our’s will accept one, an HTTP Request (I’ll explain in a bit). We’ll call the EventDispatcher constructor by calling the “super” method and then set our request variable to accept the HTTP Request:

package com.reyco1.webservice
{
	import flash.events.*;
	import flash.net.*;

	public class WebService extends EventDispatcher
	{

		private var request:URLRequest;
		private var loader:URLLoader;
		private var variables:URLVariables;
		public var data:*

		public function WebService($servicePath:String)
		{
        	super();
			request = new URLRequest($servicePath);
		}
    }
}

Now we’ll create our one and only method. This is the method that will make the call to the webservice. Our method will accept 2 arguments: the first is a “method” (String); we can set this method to be either “POST” or “GET”, ours will default to “POST”. Usually web services will tell you which method to use in order to access their information. The second argument is “arguments” (Object); This will hold any parameters that you would need to make your service call. Again, web services will tell you if you need to send any additional information with your call, ours defaults to null.

package com.reyco1.webservice
{
	import flash.events.*;
	import flash.net.*;

	public class WebService extends DispatchExtension
	{

		private var request:URLRequest;
		private var loader:URLLoader;
		private var variables:URLVariables;
		public var data:*

		public function WebService($servicePath:String)
		{
			request = new URLRequest($servicePath);
		}

		/**
		 * Makes the web service call
		 * @param $method either POST or GET. POST is set as default
		 * @param $arguments any parameters or variables that you need to make with your web service call
		 *
		 */
		public function call($method:String="POST", $arguments:Object=null):void
		{
			variables = new URLVariables();
			if($arguments != null){
				for (var i:* in $arguments){
					variables[i] = $arguments[i];
				}
				request.data = variables;
			}
			request.method = $method.toUpperCase();
			loader = new URLLoader(request);
			loader.addEventListener(Event.COMPLETE, handleRequestLoaded);
			loader.addEventListener(IOErrorEvent.IO_ERROR, handleRequestError);
			loader.load(request);
		}
    }
}

Now let me explain what’s going on up there. Basically we set up our URLVariables by recursing through the “$arguments” parameter if it’s not set to null and set it to the “data” proerty or our URLRequest. Then we specify the call method by setting the URLRequest’s “method” property to the “$method” parameter. We then continue to set up out URLLoader instance by adding the COMPLETE and IOErrorEvent event listeners. Finally we make the service call by executing the URLLoader’s call method and passing it the URLRequest.

Now we create the handlers for our event listeners:

package com.reyco1.webservice
{
	import flash.events.*;
	import flash.net.*;

	public class WebService extends EventDispatcher
	{

		private var request:URLRequest;
		private var loader:URLLoader;
		private var variables:URLVariables;
		public var data:*

		public function WebService($servicePath:String)
		{
			request = new URLRequest($servicePath);
		}

		/**
		 * Makes the web service call
		 * @param $method either POST or GET. POST is set as default
		 * @param $arguments any parameters or variables that you need to make with your web service call
		 *
		 */
		public function call($method:String="POST", $arguments:Object=null):void
		{
			variables = new URLVariables();
			if($arguments != null){
				for (var i:* in $arguments){
					variables[i] = $arguments[i];
				}
				request.data = variables;
			}
			request.method = $method.toUpperCase();
			loader = new URLLoader(request);
			loader.addEventListener(Event.COMPLETE, handleRequestLoaded);
			loader.addEventListener(IOErrorEvent.IO_ERROR, handleRequestError);
			loader.load(request);
		}

		private function handleRequestLoaded($event:Event):void
		{
			data = $event.target.data;
			this.dispatchEvent(new Event(”RESULT”, false));
		}

		private function handleRequestError($event:IOErrorEvent):void
		{
			data = {};
			this.dispatchEvent(new Event(”FAULT”, false));
		}

	}
}

In the handlers, if the call is successfull, it sets the data variable to the data that the web service returns and fires a “RESULT” event. If the call is unsuccessful, set the data to an empty object and fires teh “FAULT” event. Now we’ll add getter and setter functions so that we may be able to dynamically set the web service path whenever we want.

package com.reyco1.webservice
{
	import flash.events.*;
	import flash.net.*;

	public class WebService extends EventDispatcher
	{

		private var request:URLRequest;
		private var loader:URLLoader;
		private var variables:URLVariables;
		public var data:*

		public function WebService($servicePath:String)
		{
			request = new URLRequest($servicePath);
		}

		/**
		 * Makes the web service call
		 * @param $method either POST or GET. POST is set as default
		 * @param $arguments any parameters or variables that you need to make with your web service call
		 *
		 */
		public function call($method:String="POST", $arguments:Object=null):void
		{
			variables = new URLVariables();
			if($arguments != null){
				for (var i:* in $arguments){
					variables[i] = $arguments[i];
				}
				request.data = variables;
			}
			request.method = $method.toUpperCase();
			loader = new URLLoader(request);
			loader.addEventListener(Event.COMPLETE, handleRequestLoaded);
			loader.addEventListener(IOErrorEvent.IO_ERROR, handleRequestError);
			loader.load(request);
		}

		private function handleRequestLoaded($event:Event):void
		{
			data = $event.target.data;
			this.dispatchEvent(new Event(”RESULT”, false));
		}

		private function handleRequestError($event:IOErrorEvent):void
		{
			data = {};
			this.dispatchEvent(new Event(”FAULT”, false));
		}

		public function set servicePath($path:String):void
		{
			request = new URLRequest($path);
		}

		public function get servicePath():String
		{
			return request.url;
		}

	}
}

That’s basically all we need for our base WebService calss! Was it easy? Hope so lets fire it up by using it in a simple Twitter API!

Using the newly created WebService class to make a simple Twitter API

Create a new Actionscript file, name it “Twitter” and save it to the webservices folder. We want this class to fire events also, so lets start off by extending the EventDispatcher class. Remember also to import the flash events package and our WebService class too:

package com.reyco1.webservice
{
	import com.reyco1.webservice.WebService;
	import flash.events.*;

	public class Twitter extends EventDispatcher
	{
    }

}

Cool, let’s create a static private var that will hold an HTTP Status method provided by the online Twitter API. You can find all the Twiiter methods over at the Twitter RESR API Docunebtation here: http://apiwiki.twitter.com/REST+API+Documentation#HTTPStatusCodes. We’re going to use only one for now. The call to get all the Tweets on the public timeline.

We’re also going to need a private variable to represent our WebService class and a public array variable which will hold the parsed xml returned byt Twitter:

package com.reyco1.webservice
{
	import com.reyco1.webservice.WebService;
	import flash.events.*;

	public class Twitter extends EventDispatcher
	{

		private static var PUBLIC_TIMELINE:String = "http://twitter.com/statuses/public_timeline.xml";

		private var twitterService:WebService;
		public var result:Array;

        }
    }
}

Ok, now let’s set up our constructor. In the constructor we will set up our instance of the WebService class. Remeber that the WebService class needs to accept a service path in it’s constructor, so we’ll pass it our PUBLIC_TIMELINE path as default. We also set the result array to an empty array;

package com.reyco1.webservice
{
	import com.reyco1.webservice.WebService;
	import flash.events.*;

	public class Twitter extends EventDispatcher
	{

		private static var PUBLIC_TIMELINE:String = "http://twitter.com/statuses/public_timeline.xml";

		private var twitterService:WebService;
		public var result:Array;

		public function Twitter()
		{
			twitterService = new WebService(Twitter.PUBLIC_TIMELINE);
			twitterService.addEventListener("RESULT", handleResult);
			twitterService.addEventListener("FAULT", handleFault);

			result = [];
		}
    }
}

before we set up the handlers for the events fired from the WebService class, let’s create the method which will make the request for the public timeline to Twitter:

package com.reyco1.webservice
{
	import com.reyco1.webservice.WebService;
	import flash.events.*;

	public class Twitter extends EventDispatcher
	{

		private static var PUBLIC_TIMELINE:String = "http://twitter.com/statuses/public_timeline.xml";

		private var twitterService:WebService;
		public var result:Array;

		public function Twitter()
		{
			twitterService = new WebService(Twitter.PUBLIC_TIMELINE);
			twitterService.addEventListener("RESULT", handleResult);
			twitterService.addEventListener("FAULT", handleFault);

			result = [];
		}

		public function requestPublicTimeline():void
		{
			twitterService.servicePath = Twitter.PUBLIC_TIMELINE;
			twitterService.call();
		}
    }
}

What we’re doing is dynamically setting the service path on the Webservices class. Now, you may be asking yourself, “didn’t we just add that path up in the constructor?”, the answer is, yes. Never the less, it is good practice for us to set it up here again, basically because later on when we add new methods, we’ll have to set it to the new service path anyway, so might as well get used to it from now

Afther the path is set, then we then execute the call method of our WebService class. Nothig is going to happen unless we add our event handlers, so let’s get to it!

package com.reyco1.webservice
{
	import com.reyco1.webservice.WebService;
	import flash.events.*;

	public class Twitter extends EventDispatcher
	{

		private static var PUBLIC_TIMELINE:String = "http://twitter.com/statuses/public_timeline.xml";

		private var twitterService:WebService;
		public var result:Array;

		public function Twitter()
		{
			twitterService = new WebService(Twitter.PUBLIC_TIMELINE);
			twitterService.addEventListener("RESULT", handleResult);
			twitterService.addEventListener("FAULT", handleFault);

			result = [];
		}

		public function requestPublicTimeline():void
		{
			twitterService.servicePath = Twitter.PUBLIC_TIMELINE;
			twitterService.call();
		}

		private function handleFault($event:Event):void
		{
			result = [];
			this.dispatchEvent(new Event(”FAULT”));
		}

		private function handleResult($event:Event):void
		{
			var myResult:XML = new XML(twitterService.data);
			result = parseResult(myResult);
			this.dispatchEvent(new Event(”RESULT”));
		}
    }
}

Nothing too fancy in the fault event handler. Basically, all it does is is just set the reult array to an ampty array and fires a new Fault event. Now, the good stuff is in the result event handler. The response we get from Twitter will be a String in an XML format, so once it arrives, we need make sure flash reads it as XML. Once that is done, we pass it to a method named “parseResult” which we will be seeing in the next step. Essentially, all the “parseResult” method does is take the xml returned from Twitter and parse it into an array of objects, better known as a “Collection”. Once the XML is parsed, it is set as the “result” array and a “RESULT” event is fired. Let’s see that crazy “parseResult” method:

package com.reyco1.webservice
{
	import com.reyco1.webservice.WebService;
	import flash.events.*;

	public class Twitter extends EventDispatcher
	{

		private static var PUBLIC_TIMELINE:String = "http://twitter.com/statuses/public_timeline.xml";

		private var twitterService:WebService;
		public var result:Array;

		public function Twitter()
		{
			twitterService = new WebService(Twitter.PUBLIC_TIMELINE);
			twitterService.addEventListener("RESULT", handleResult);
			twitterService.addEventListener("FAULT", handleFault);

			result = [];
		}

		public function requestPublicTimeline():void
		{
			twitterService.servicePath = Twitter.PUBLIC_TIMELINE;
			twitterService.call();
		}

		private function handleResult($event:Event):void
		{
			var myResult:XML = new XML(twitterService.data);
			result = parseResult(myResult);
			this.dispatchEvent(new Event(”RESULT”));
		}

		private function handleFault($event:Event):void
		{
			result = [];
			this.dispatchEvent(new Event(”FAULT”));
		}

		private function parseResult($result:XML):Array
		{
			var objectArray:Array = [];
			var xml:XML = $result
			var xmllist:XMLList = xml.children();

			for(var a:Number = 0; a < xmllist.length(); a++){
				var object:Object = {};
				for(var b:Number = 0; b< xmllist[a].children().length(); b++){
					var item:XML = xmllist[a].children()[b];
					if(item.localName().toString() == “user”){
						var userObject:Object = {};
						for(var c:Number = 0; c < item.children().length(); c++){
							userObject[item.children()[c].localName().toString()] = item.children()[c].toString()
						}
						object[item.localName()] = userObject;
					}else{
						object[item.localName()] = item.toString();
					}
				}
				objectArray.push(object);
			}
			return objectArray;
		}
	}
}

With the “parseResult” method, each node in the XML will be parsed into an object containing the following values:

id
in_reply_to_status_id
source
created_at
user
  -- name
  -- url
  -- screen_name
  -- description
  -- followers_count
  -- id
  -- protected
  -- profile_image_url
  -- location
in_reply_to_user_id
text
favorited
truncated

I think it’s time we test ride this puppy! Let’s get to it!

Creating a Twitter Application with our newly created Twitter API

Crack open an fla file and set the stage dimensions to 310 by 400. We’ll start off by creating a container for each Tweet. The container movieclip will hold the users profile image and a textfield to display the user’s tweet. Each of a users profile image is 48 x 48, so create a square on the stage 48 x 48 and create a static text field which says “LOADING” and place it right at the center of the box. Now convert the whole thing into a MovieClip and instance name it “imageContainer”;

Now create a dynamic text field with the following properties:

Set the text field right next to the imageContainer and create a MovieClip out of the whole thing. So essentially at this point you should have ONE MovieClip on the stage. This movie clip should contain an 48 x 48 MovieClip instance named “imageContainer” and a dynamic text field instance named “twitTxt”

Drag another 5 instances of the newly created movie clip from the library and drop them on the stage and align them one under the other like shown below and instance name then item0, item1, item2, item3, item4 and item5:

That’s it for the timeline stuff. Select the first frame and open up your actions panel. The first thing we need to do is import our Twitter class;

import com.reyco1.webservice.Twitter

Now we create an instance of our Twitter API and have it listen to the “RESULT” event:

import com.reyco1.webservice.Twitter

var twitter:Twitter = new Twitter();
twitter.addEventListener("RESULT", handleResult);

Let’s set up the handler for the result event. In the handler we pass the first 6 of the objects in the result array to a “populateItem” method along with its index. Let’s take a look at the event handler and then we’ll see what that “populateItem” method looks like.

import com.reyco1.webservice.Twitter

var twitter:Twitter = new Twitter();
twitter.addEventListener("RESULT", handleResult);

function handleResult($event:Event):void
{
	var result:Array = twitter.result;
	for(var a:Number = 0; a < 6; a++){
		populateItem(a, result[a]);
	}
}

Below we’ve added the “populateItem” method. Basically, this method adds the tweet to the text field in the item on stage along with adding the image to it’s imageContainer.

import com.reyco1.webservice.Twitter

var twitter:Twitter = new Twitter();
twitter.addEventListener("RESULT", handleResult);

function handleResult($event:Event):void
{
	var result:Array = twitter.result;
	for(var a:Number = 0; a < 6; a++){
		populateItem(a, result[a]);
	}
}

function populateItem($itemIndex:Number, $twitObject:Object):void
{
	this["item"+$itemIndex].twitText.text = $twitObject.text;
	var imageLoader:Loader = new Loader();
	this["item"+$itemIndex].imageContainer.addChild(imageLoader);
	var imagePath:URLRequest = new URLRequest($twitObject.user.profile_image_url);
	imageLoader.load(imagePath);
}

Now all we have to do is call the “requestPublicTimeline” method of our Twitter API and we’re DONE!!

import com.reyco1.webservice.Twitter

var twitter:Twitter = new Twitter();
twitter.addEventListener("RESULT", handleResult);

function handleResult($event:Event):void
{
	var result:Array = twitter.result;
	for(var a:Number = 0; a < 6; a++){
		populateItem(a, result[a]);
	}
}

function populateItem($itemIndex:Number, $twitObject:Object):void
{
	this["item"+$itemIndex].twitText.text = $twitObject.text;
	var imageLoader:Loader = new Loader();
	this["item"+$itemIndex].imageContainer.addChild(imageLoader);
	var imagePath:URLRequest = new URLRequest($twitObject.user.profile_image_url);
	imageLoader.load(imagePath);
}

twitter.requestPublicTimeline();

Publishing your file as an AIR application

Publishing a flash file as an AIR application cannot be any easier:

• Download the runtime installation file.
• Double-click the runtime installation file.
• In the installation window, follow the prompts to complete the installation.

Once installed, follow these steps:

• Open your Flash FLA file.
• If you’re opening a new Flash File (ActionScript 3.0), save it. If you don’t save it, a warning appears when you do the next step.
• Select Commands > AIR - Application And Installer Settings. An alert box appears, asking if you want to convert the file to Adobe AIR publish settings.
• Click OK to convert the FLA file to Adobe AIR publish settings. The AIR - Application And Installer Settings dialog box appears.

Simply publish your and all should work! I hope you have enjoyed this article and have been able to learn lots of stuff! In the next few tutorials, I’ll be adding more complex methods to our Twitter API and Hopefully at the end of the series, we’ll have a fully working Twitter Application!