Advanced Banner Rotator skin#00

This Component is an advanced Banner Rotator written in ActionScript 3.0 for Websites, Blogs and Flash projects as well.

Take a look of this banner now.

Features:

1. Auto resizing (means objects redistribution) to adapt it to your website in seconds
2. Google Analytics click-tracking ready
3. Tilt Shifter effect
4. Title, subtitle and description TextFields, HTML powered
5. Navigation console with autopilot
6. Image mixer with 4 transition effects
7. Smooth tween animation with easy setting system
8. Optional link button

Features we are proud:

1. Tested under Flex Builder Profiler (serious stuff)
2. Complete and easy graphics customization through Flash authoring
3. No memory leak (see the chart on the bottom page)
4. Easy tween settings through xml
5. Mad clicks ready
6. Loading broken-free process
7. Powered by an advanced abstract Library

Get started: place the banner into your Website

1. Open and edit the xml content file (xml/contents.xml) with your text-editor or by using XML2CMS
2. See the ‘XML contents reference’ section for more information about its parameters
3. Upload the SWF as well as the ‘xml’ folder into your server alongside your HTML page
4. Add the swf object in your HTML page (see ‘Use and resize the SWF file’ section for more information)

Get started: edit the config xml for basic settings

1. Open and edit the xml config file (xml/config.xml) with your text-editor or by using XML2CMS
2. See the ‘XML config reference’ for more information about its parameters

Get started: use the Google Analytics feature

This banner comes with the amazing feature to be able to track user clicks and scene views.
In order to set it up correctly you need to check the following steps:

1. You need to have a regular Google Analytics account enabled
2. You need to have a Google Analytics Profile linked to your domain
3. The HTML page which will embed the banner SWF must have the JS code (no async version) provided by Google after profile creation
4. Now see the ‘Customize the Google Analytics traking’ to enable/disable or customize the tracking values

Get started: edit the skin for soft customization

1. Open the FLA file with Adobe Flash CS4 Professional
2. See the ‘Soft Skin Editing’ for more information
3. Publish it and replace the SWF into your server with the new one

Customize the Google Analytics traking

First off, the Google Analytics feature is currently not compatible with the new async version of Google Analytics snippet.
This means that you have to use the previous version which works well with Google Analytics service.
Here the compatible script:

	<script type="text/javascript">
		var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
		document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
		</script>
		<script type="text/javascript">
		try {
		var pageTracker = _gat._getTracker("UA-XXXXXXXX-X");
		pageTracker._trackPageview();
		} catch(err) {}
	</script>

If your script looks like the above one, so you are ready, while if not, you should replace it. Usually this script is placed before the closed body tag, while the new async is placed before the closed head tag.
Remember to put you tracker code instead the “UA-XXXXXXXX-X”.

To enable the Google Analytics you only need to set the ‘gaTrackerString’ parameter in the xml config file (see ‘XML config reference section’).
If it does left empty, no external calls to Google will be made.
This parameter define the virtual path to identifier your banner in the Google Analytics panel view.
For instance, setting @gaTrackerString equal to “/mybanner/” means that everytime someone click on your banner, a new page view with the url /mybanner/ will be added on the Analytics report.
Furthermore the banner will send to GA also the scene clicked, the link button clicked and the scene views.

Assuming the @gaTrackerString is equal to “/mybanner/, here how the banner usage will be tracked:

/mybanner/2/click (Second scene clicks)
/mybanner/4/view (Fourth scene views)
/mybanner/3/link/http://... (Third scene click to button with url:http://... )

And if your ‘item’ nodes in the xml contents has the attribute @label, the tracking list should looks like:

/mybanner/2_myLabel1/click (Second scene clicks)
/mybanner/4_myLabel4/view (Fourth scene views)
/mybanner/3_myLabel3/link/http://... (Third scene click to button with url:http://... )

So it will be better more readable.

Use and resize the SWF file:

Resizing the banner is quite straightforward.
Simply set in your HTML object the width and the height of the SWF. That’s it. The Component will do the dirty work for you.
So you can place the banner easily in your webpage even without open the FLA file.
Here the basic html code to embed an SWF:

<object id="banner" width="920" height="350">
	<param name="movie" value="banner.swf" />
		<object type="application/x-shockwave-flash"
			data="banner.swf"
			width="920" height="350" />
</object>

Whenever you are using the above basic code or more advanced javascript package like SWFObject, the point is the same: change width and height properties to set up the banner in your web page.

By the way there are some constraints, since this banner was designed to be an horizontal banner with a size of 920x350px. Using a vertical size or a really different size/aspect-ratio could be require some visual objects editing in the FLA file.

Soft Skin Editing

This section is intended to teach how to edit the skin of the Component in order to achieve one or both of these goals:

1. Better or different position of the elements since the size/aspect-ratio is really different from the original one
2. Customize the elements visually in order to make it better for your taste

For instance this means that you can safety change the position, alpha, colors, font, font-size, of the MovieClip available.

First off, take a brief look of the section ‘General guidelines while editing the FLA file’.
Then be sure you have got the right font (which it can be downloaded for free) if you are going to use it otherwise forget it.
Here the steps:

1. Open the FLA file with Adobe Flash CS4 or better
2. Double click the MovieClip bannerRotatoSkin00 from Library to enter in edit mode
3. You will see all the elements placed on the stage

You can change the positions of the available MovieClips, or the font/font-size of the TextFields by entering inside, or the alpha value of the backgrounds.

The XML files:

There are two xml files for this Component insite the ‘xml’ folder:

1. config.xml
2. contents.xml

The former contains setting about transitions, tweens, effects and other relevant properties you can customize. This one usually won’t be updated so often.
The latter is about the contents, and this one could be updated frequently. This xml will contains settings about your images path, title, text, links and any other properties content related.
If you have XML2CMS installed, the xml and content editing will become dead easy.

See the references below for detailed settings about both of them.

XML contents reference:

This is the XML which contains your contents data.
The xml file must be valid and it must be defined as the following example as empty list:

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

	<items>
	</items>

Then the following code specify how each node should be defined:

<item url="image_url" label="gaLabel" callback="function_name" params="function_parameter">
	<title><![CDATA[Title]]></title>
	<subtitle><![CDATA[Subtitle]]></subtitle>
	<description><![CDATA[Description]]></description>
	<button><![CDATA[Button Label]]></button>
</item>

You must use CDATA tag if your text content is unescaped:

	<title><![CDATA[ <p><font color="#ff0000>My Title</font></p> ]]></title>

While for plain text you can omit it:

	<title>My Title</title>

So here a complete contents xml with two items:

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

	<items>
		<item url="image_url" label="gaLabel callback=">
		<title><![CDATA[Title]]></title>
		<subtitle><![CDATA[Subtitle]]></subtitle>
		<description><![CDATA[Description]]></description>
		<button><![CDATA[Button Label]]></button>
		</item>

		<item url="image_url" label="gaLabel callback=">
		<title><![CDATA[Title]]></title>
		<subtitle><![CDATA[Subtitle]]></subtitle>
		<description><![CDATA[Description]]></description>
		<button><![CDATA[Button Label]]></button>
		</item>
	</items>

And the follow the reference of each node and attribute:

@url:
The path of the image to load
It can be relative to the SWF or HTML page, or absolute
It can accept images (jpg, png) and SWF as well (see "Limitations" for SWFs)

@label:
The optional label to identifier in a better readable way the scene in Google Analytics

@callback:
the function name in the root class to be called by button click.
Leave blank to hide the button

@params:
The optional parameter that will be passed
alongside the function callback
I.e. @callback="myCall" @params="Hello"
in the root of the FLA it should be a function like:
function myCall(res:String)
{
	trace(res)
}
// output: Hello

<title>:
The Title of this scene. Can be html text

<subtitle>:
The subtitle of this scene. Can be html text

<description>:
The text for the description box of this scene. Can be html text
I could use also a css style if defined in config xml
see 'XML css reference'

<button>:
The label of the button

XML config reference:

This is the XML which contains config setting for the Component.
The xml file must be valid and it could have the following global parametes, as shown the default value below:

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

And here the detailed description of each attribute:

@timer:
the time in seconds of scene persistence, set to 0 to disable the autopilot

@consoleHider:
boolean, enable the navigator console that will fade in on mouse move.
set to false to leave the console always visible

@tiltBlur:
the blur value of the TiltShifter effect. Use 0 to disable it.

@autoPickEffect:
'sequencial' | 'random' How the image effect will be picked up.

@clickAnywhere:
boolean, set to true to let the user to click anywhere to move forward the scene.

@gaTrackerString:
The custom string identifier for Google Analytics.
Leave empty to disable it.
(See the 'Customize the Google Analytics traking' for more information)

Furthermore this xml contains other xml node described in the underneath sections.

XML css reference:

This is the optional css style definition for the ‘description’ text box.
Leave it empty to not use it.
While if you are going to use it, you must set as CDATA content.
Here an example of basic css:

	<css><!--
		<![CDATA[
		h1{
			font-family: "Arial";
			font-size: 30px;
		}

		p{
			font-size: 14px;
		}
		]]>-->
	</css>

Then the text in the description node of the xml contens file should be:

<description><![CDATA[ <p>I'm an <h1>header</h1> with some text</p>]]></description>

XML Mixer reference:

This node wil define the config preference of the image mixer, which is a powerful object to make image transitions with gorgeous effects.
It must be a child of the root xml config and can have some global settings and further child effect definition.
To add effects to the mixer, simply add the ‘effect’ node with the @id and optionally other properties described after.
The following example will add 2 effect to the mixer (see the ‘Mixer Effects Reference’ section to know which effect you can use)

<image_mixer fitToCanvas="true" mantainRatio="true" >
	<effect id="1" />
	<effect id="2" />
</image_mixer>

here the global setting of the mixer:

@fitToCanvas:
Allow to fit the images size to the banner canvas size,
center them to the canvas

@mantainRatio:
Allow to maintain or not the aspect-ratio of the images on resizing.
This will be ignored when @fitToCanvas is set to false

Mixer Effects Reference

In this component there are 6 effect ready to use in the Mixer object. Adding effect nodes to the mixer will make them available. Furthermore you can use additional setting for each of them to find the right setup.
Here the list of available effect with the relative @id:

effect id="0": AlphaCrossFade:
Makes alpha cross fading between the two images

effect id="1": HorizontalSlide:
Makes horizontal slide of the two images

effect id="2": VerticalSlide:
Makes vertical slide of the two images

effect id="3": BlurSlide:
Makes horizontal or vertical slide of the two images applying a motion blur

And here the general parameter list for all the effects.
Keep in mind the each default parameter are defined for the average better result. By the way in some cases you may need to change those values:

@transition = "easeInOutExpo";
The type of the equation. Value may be any Tweener supported equations

@time = 1;
The duration in seconds of the transition

XML tweens reference:

This Component uses an advanced xml system to control tweens on objects.
The node ‘tweens’ in the config xml file will keep the tweens settings, from global parameters to single item one.
The concept is based on ‘states’, which refer to different states of view.
In this Component there are two states, the first one is about the ‘on stage elements’ while the second one is about the ‘out of stage elements’.
‘tweens’, ‘state’ and ‘clip’ nodes can have custom parameters relative to the transition, and they are:

@time: The duration of the tween
@delay: The delay for the begin of the tween
@transition: The equation of the tween

Value in nested parameters will override the same present in its parent.
The following example will tween the object named ‘someclip’ which is a child of ‘container’ clip.
‘someclip’ will be tweened by alpha property from 1 to 0 and vice-versa using transition, delay and time specified by its attributes or its state’s attributes or even by the global attributes.

<tweens delay="0" transition="easeInOutExpo">
	<state id="1" transition="easeInOutQuint" time="1">
		<clip name="someclip" alpha="1" relative="root.container"/>
	</state>

	<state id="2" transition="easeInOutQuint" time="0.5">
		<clip name="someclip" alpha="0" relative="root.container"/>
	</state>
</tweens>

The properties that can be used are the same the you can use with the Tweener Library, so refer to its reference for this.
Special value are (experimental and advanced stuff here):

- EMPTY property (i.e. alpha="")
means will try to use the original value of the DisplayObject

- % value (i.e. x="50%") available only for x, y, width and height properties
means that the value will be converted based on width and height of its parent

- OPERATOR (i.e. x="-") available only for x and y properties and only - and + operators,
means that the value will be calculated to performe x or y
value out (left, right, top, bottom) of its container

- Tweener Specials (i.e. _color="0xff0000"):
supported colors and filter so far

Editing the ActionScript in the FLA file

The Component FLA file has two Timeline frames.

1. In the first one there is the code to handle the global loading process.
2. In the last one there is the code to instantiate the banner.

In the second frame you may want to add some custom code, for example adding a new callback function for the button:

// Adding custom function to be called by the button
// this is the custom function to performe the getUrl
// you can create as many functions you need, see the xml for reference
function gotoLink(_url:String):void
{
	navigateToURL(new URLRequest(_url))
}

function doSomethingElse(_param:String):void
{
	trace(_params);
}

The above functions can be called by the buttons with this setting in the xml contents file:

	...
	<item url="image_url" callback="gotoLink" params="http://">
	...

	...
	<item url="image_url" callback="doSomethingElse" params="Hey!">
	...

Use the Component in Flash projects:

If you want to use the banner in a bigger Flash project (i.e. a Flash template), first off you need to copy the ‘banner-rotator‘ folder from the example FLA Library into your Flash Library. Make sure to set the class path of your Flash file to be able to read the two required libraries as mentioned before. Then you need to write the following code:

import maja.components.BannerRotator00;
import maja.stage.Align;

// init the Align class (required)
Align.init(this);

// create the banner, passing the size and the two XML object references.
// if you want to know how to load the xml files, you can see the example FLA file included,
// otherwise you can use your own loading strategy.
//if you need a different size in your template, you may need to use your own
// with and height instead the stage size
var banner:BannerRotator00 = new BannerRotator00(stage.stageWidth,
												stage.stageHeight,
												xmlConfig,
												xmlContents);
addChild(banner);

Loading the Component as SWF standalone:

You can load this SWF in other Flash projects easily by using code something like:

// loading the swf file
var ldr:Loader = new Loader()
var req:URLRequest = new URLRequest("banner.swf")
ldr.load(req)
ldr.contentLoaderInfo.addEventListener(Event.COMPLETE, completeLoad)

function completeLoad(e:Event)
{
	addChild(ldr)
}

Keep in mind that the SWF will use the stage size to resize its contents.
If you need a different size, you need to recompile it specifying a different width and height (see ‘Use the Component in Flash projects’).

Limitations & Issues:

1. SWF file are loaded correctly but only static SWF with no animation are correctly displayed in image mixer.
2. You can use html in textfield but keep in mind that textfield with font embed set to true won’t render some tag (i.e. bold and italic);
3. At the same time remember that textfield without font embed will not render some transformation like rotation and scale (and alpha if published for Player 9).

Requirements:

This FLA file require Adobe Flash CS4 or better to be opened and edited.
The SWF file is compiled for Flash Player 9 or better.

The Concept Behind:

Behind this Component there is an advanced design and software implementation.
To understand better what there is under the hood, consider that this Component could be split in tree main views:

1. Graphic view
2. Composition view
3. Logic view

Graphic view:
Each display object is a regular Flash MovieClip placed in Library.
This means that you can edit any visual aspect through Flash authoring, which is a great for editing shapes, textfields, colors, fonts and so on.
Further edits could be done through the config.xml file (for example effects and tween parameters).
This is important because it does mean that all the visual objects (which we would call skins) are not drawn by code, but by hand. The code part is only responsible of functionality and behaviors.
In this place you can edit all the visual elements and it is not required any ActionScript knowledge, just a bit of the Flash authoring environment.

Composition view:
This is a mixture of one Class and one main MovieClip exported in Library. Some heavy edits needs to handle the MovieClip and that Class as well to be accomplished.
This is the place where you can make some serious modifications, and it does require some middle knowledge of ActionScript 3.0.

Logic view:
All the abstract logic stuff is placed under the MajaCoreLib which is an advanced library for rapid development of Flash Components and Templates.
This means that you don’t have to handle the code behind that library.
The benefits of this strategy are:

1. Keep you focused on Design rather then Code
2. Centralize the update process, so when a component will get an update, all the instance will too, with no hassle.
3. Keep easy the support process since there won’t any issue related to user edited code
4. It will leave your project cleaner and rock solid since any code conflicts will be avoided by design.
5. Let us to reuse debugged code which is better than brand new buggy code.

Optimization

Here the chart from Flex Builder Profiler which show how the memory will remain constant across time.
This means no memory leaks for this Component, so no hassle for your website!

General guidelines while editing the FLA file

Before editing something, try to compile the SWF (by pressing Command-Enter or Control-Enter). If everything goes well, you are ready to begin the editing.
The Component needs two library included as SWC file:

1. Tweener Library
2. MajaCoreLib Library

The first one is released Open Source under MIT License and you can get it here
The last one is included in the package as SWC compiled library and full source code as well.

If Adobe Flash alert you about missing font, you have to download and install the font or use another one.
Keep in mind that edit the FLA file is about the graphics and visual placements.

If you get some compiling errors, this means one of the required library is missing. Check the ‘libs’ folder and the class path in the document preferences. If the issues persists, contact the author. By the way this shouldn’t happen.

The main constraint to keep in mind in order to avoid file break is:

1. Do not rename or delete any MovieClip that have already set a custom name up

If you need to do one of the above constraint, well you need to edit also the main class, deleting or changing the code which refer to that MovieClips.