Building Templates

Building a Template is a matter of building an ad and making some sections of the content dynamic so that they can be edited in the ONE by AOL: Creative interface. If you can already build a ONE by AOL: Creative ad using Actionscript or Javascript, you can build a ONE by AOL: Creative template! If you are new to ONE by AOL: Creative and have never built an ad before, then you should start by following our regular ad build guides and then come back to this template guide. These are the key articles to read: The five rules of ad building, Tracking Clicks and Events alongside some of the build guides: Building a Polite Ad, Building an Expand.

Already an expert at building ads? You have an ad and you have a section of it that you want to be dynamic so that users within ONE by AOL: Creative can customise it? This is the method on our API that will be your best friend:

ADTECH.getContent("Name" [String], "Default Value(s)" [String or JSON])

The Name will identify either the name of the Single Property that can be edited in ONE by AOL: Creative, the name of the group of properties (Property Group) that can be edited in ONE by AOL: Creative or the name of the Collection of items can be edited in ONE by AOL: Creative. The Default Values parameter is either a string or a string representation of a JSON object (json.org). Please note that all strings in JSON must be in “double quotes”.

The Default Values parameter has two important roles – it both sets the default value(s) to use (obviously!) but also defines the value(s) and type of value(s) you want to expose to the ONE by AOL: Creative user so that the value(s) can be set outside of the flash movie (or html ad) in the ONE by AOL: Creative interface.

How you call ADTECH.getContent will be dictated by the type of dynamic content you want to include in your ad and expose within ONE by AOL: Creative: a Single Property, a Property Group or a Collection

Single Property

This is the most simple use of ADTECH.getContent. If you just have a single string, file, colour, number or boolean that you want to allow ONE by AOL: Creative users to edit, then rather than hard code the value into the ad, you can make a call to:

ADTECH.getContent("Property Name", "Default Value");

When testing locally (in AS3 or Javascript) this will simply return “Default Value” but once uploaded to ONE by AOL: Creative, the method will return whatever the user in ONE by AOL: Creative defines for ‘Property Name’ in the Content panel. The return type will be a String, Boolean or Number.

If you would like to restrict what the user can enter in ONE by AOL: Creative to a predetermined set of values, you can include these values in the Default Value and separate them with “||”. For example, if you want the user to choose between the border styles solid, dashed and dotted you can include a call to:

ADTECH.getContent("Border Style", "solid || dashed || dotted");

In ONE by AOL: Creative, this will give the user a select box from which they can choose one of the values.

A few examples of using the single property, shown in AS3 and Javascript follow:

Setting the value in a text box

AS3:

titleTextField.text = ADTECH.getContent("Title", "Advertisement");

JS:

var myTitleDiv = document.getElementById("title-div");
myTitleDiv.innerHTML = ADTECH.getContent("Title", "Advertisement");

Loading in a logo file

AS3:

var logoLoader:Loader = new Loader();
logoLoader.load(new URLRequest(ADTECH.getContent("Logo File", "myDefaultLogo.png")));
addChild(logoLoader);

JS

var myLogoImage = document.getElementById('logo-image');
myLogoImage.src = ADTECH.getContent("Logo File", "myDefaultLogo.png")

Note: when running as an ad in either ONE by AOL: Creative or live on a website, the file value will be returned as a string of a full path to the file so you DON’T need to use ADTECH.getFileUrl when you’re using ADTECH.getContent.

Changing the background colour

AS3:

private function hexToUint(hex:String):uint {
 return uint(hex.replace('#', '0x'));
}

var bgLayer:Shape = new Shape();
bgLayer.graphics.beginFill(hexToUint(ADTECH.getContent('Background Colour', '#FFFFFF')));
bgLayer.graphics.drawRect(0, 0, stage.stageWidth, stage.stageHeight);
addChildAt(bgLayer, 0);

JS:

var myAdDiv = document.getElementById('ad-div');
myAdDiv.style.backgroundColor = ADTECH.getContent('Background Colour', '#FFFFFF');

Using a Boolean to decide whether to expand on rollover or on click

AS3:

function myExpand(e:MouseEvent):void {
 goToAndStop(2);
 ADTECH.expand();
}

var rollover:Boolean = ADTECH.getContent('Expand on Rollover?', true);
if (rollover) {
 expandButton.addEventListener(MouseEvent.MOUSE_OVER, myExpand);
} else {
 expandButton.addEventListener(MouseEvent.CLICK, myExpand);
}

JS:

function myExpand() {
 document.getElementById('expand-section').style.visibility='visible';
 ADTECH.expand();
}

var rollover = ADTECH.getContent('Expand on Rollover?', true);
var expandButton = document.getElementById('expand-button');
if (rollover) {
 expandButton.onmouseover = myExpand;
} else {
 expandButton.onclick = myExpand;
}

Property Group

Property Groups are very similar to Single Properties except in the ONE by AOL: Creative interface they are grouped together in collapsible sections (regular content panel) or tabs (expanded content panel). It is advisable to use property groups if the template contains a lot of editable properties and some of them are relevant to a particular part of the advert.

In this instance, the first parameter of ADTECH.getContent is used to define the Group name and the Default Value parameter should be defined as a single JSON Object to define the property names and values. An example call to set a title, logo and clickthrough in the defined ‘Header’ section of an ad is …

ADTECH.getContent('Header','{"Title":"My Ad Title","Logo File":"mylogo.png","Clickthrough":"http://www.adtech.com"}');

The return type will be an Object. When testing locally this Object will contain the properties and default values defined in the default value of the call. Once uploaded to ONE by AOL: Creative, the method will return an Object in which the value for each property is what has been set by the ONE by AOL: Creative user under the Group name in the Content panel. Group properties support all the same properties as Single properties.

An example use case of this (setting a title, text colour, background colour and logo file in a section of the ad called “Tab 1") is shown in AS3 and Javascript below:

AS3:

// Using flash textfield component
import flash.text.TextField;

function hexToUint(hex:String):uint{
  return parseInt(hex.replace('#','0x'));
}
 
var tab1Content = ADTECH.getContent('Tab 1',
'{"Title":"My Ad Title", "Text Colour":"#FFFFFF", "Background Colour":"#000000", "Logo File":"mylogo.png"}');

var tab1Title = tab1.titleBox as TextField;
tab1Title.textColor = hexToUint(tab1Content['Text Colour']);
tab1Title.background = true;
tab1Title.backgroundColor = hexToUint(tab1Content['Background Colour']);
tab1Title.text = tab1Content['Title'];

var logoLoader:Loader = new Loader();
logoLoader.load(new URLRequest(tab1Content['Logo File']));
tab1.addChild(logoLoader);

JS:

var tab1Content = ADTECH.getContent('Tab 1','{"Title":"My Ad Title","Text Colour":"#FFFFFF","Background Colour":"#000000","Logo File":"mylogo.png"}');

var tab1Title = document.getElementById('tab1-title'); 
tab1Title.innerHTML = tab1Content['Title']; 
tab1Title.style.color = tab1Content['Text Colour']; 
tab1Title.style.backgroundColor = tab1Content['Background Colour']; 

var tab1Logo = document.getElementById('tab1-logo'); 
tab1Logo.src = tab1Content['Logo File'];

Collection

A Collection can be used to represent items that form a natural group, such as a product gallery (a collection of products). You should use them when you want to allow the ONE by AOL: Creative user to edit, add, remove and reorder a series of Property Groups (hereafter referred to as ‘Items’) used in the ad. In programming terms, you are effectively giving a ONE by AOL: Creative user full control of the Objects in an Array.

The first parameter of ADTECH.getContent is used to define the Collection name and the Default Value parameter should be defined as a JSON Array of JSON Objects to define the property names and default values in that Collection.
An example call to define a collection of products that each have a product name, product image and product description is as follows:

ADTECH.getContent('Products','[{"Name":"Product A", "Image":"product_a.png","Description":"Description of Product A"}, {"Name":"Product B", "Image":"product_b.png","Description":"Description of Product B"}, {"Name":"Product C", "Image":"product_c.png","Description":"Description of Product C"}]')

The key part that differentiates this from a Property Group is the usage of the square brackets ([ ]) to contain the Item(s). At least one Item must be declared so that, on upload, ONE by AOL: Creative can determine the properties that should be editable for each Item in the ONE by AOL: Creative interface. Since Items can be added and removed in the ONE by AOL: Creative interface, the number of Items you choose to declare in the call to getContent is only determined by how many you wish to test your code with. Since you will likely be writing code to process a collection of more than one item (e.g. a carousel or gallery of product images), it would usually be advisable to define more than one default item. This will allow you to test that your code correctly processes multiple items in a collection. The property names of course have to be the same for each item whilst the property values will usually be different.

The return type of getContent in this context will be an Array of Objects. When testing locally this Array will contain an Object for each Item defined in the default value of the call. Once uploaded to ONE by AOL: Creative, the method will return an Array which contains an Object for each Item defined by the user in the content panel in the ONE by AOL: Creative interface.

Some sample code using this is shown below. In this example we are iterating over a collection of product items and calling a function for each item.

JS

function createProduct(name, file, description) {
 // Code to add a new product to the product carousel. That's your bit :-)
}

var products = ADTECH.getContent('Products',
    '[{"Name":"Product A", "Image":"product_a.png","Description":"Description of Product A"}, {"Name":"Product B", "Image":"product_b.png","Description":"Description of Product B"}, {"Name":"Product C", "Image":"product_c.png","Description":"Description of Product C"}]')

for (i = 0; i < products.length; i++) {
  var p = products[i];
  createProduct(p['Name'], p['Image'], p['Description']);
}

AS3

function createProduct(name:String, file:String, description:String):void {
 // Code to add a new product to the product carousel. That's your bit :-)
}

var products = ADTECH.getContent('Products',
 '[{"Name":"Product A", "Image":"product_a.png","Description":"Description of Product A"}, {"Name":"Product B", "Image":"product_b.png","Description":"Description of Product B"}, {"Name":"Product C", "Image":"product_c.png","Description":"Description of Product C"}]')
for (i:int = 0; i < products.length; i++) {
   var p:Object = products[i];
   createProduct(p['Name'], p['Image'], p['Description']);
}
Once a content property, content group or content collection has been defined, elsewhere in the code, it is possible to reference just the name of content item in order to retrieve it, rather than defining default values again. An example:
var contentGroup = ADTECH.getContent(‘My Content Group Name’);
//will return just the content group without re-defining default values

This can prove useful when you need to reference the same content properties in different asset containers, such as in an in-page and floating format.

Clickthroughs

The destination url should be defined as a regular content property in either a Single Property, Property Group or Collection as described above. This means that you can define a default clickthrough url if you wish (it’s fine if it’s an empty string) and importantly the ONE by AOL: Creative user can enter their own url in the Content panel.

In code, you can pass these content properties containing the content group name and url property into the ADTECH.contentClick("Content Group Name", 'Click Property Name')method. Here’s an example in AS3 using a Property Group that contains a property named clickthrough and value of a url:

var myHeader:Object = ADTECH.getContent('Header', '{"Title":"My Ad Title", "Logo File":"mylogo.png", "Clickthrough":"http://www.adtech.com"}');
ADTECH.contentClick("Header", "Clickthrough");

Clickthroughs defined in Collections

In some cases you may want to track clickthroughs defined in each Item of a Collection separately. For example, in a gallery of products, you may want to count how many people clicked on Product A, how many on Product B, Product C etc – i.e separate click tracking for each Item. This is achieved with:

ADTECH.contentClick("Collection Name", "Click Property Name", Item)

By making the call like this the clickthrough will be tracked and reported on as Click: Collection Name : Tracking Id: Click Property Name where Tracking Id is something that the user can set for each Item within the ONE by AOL: Creative interface.

This is most easily explained via an example. Let’s again take a collection to define Products but this time with a clickthrough property that holds the clickthrough url:

function createProduct(productItem) {
 // Code that renders the product on the stage and then returns it
 return product;
}
 
var products = ADTECH.getContent('Products',
'[{"Name":"Product A", "Image":"product_a.png", "Clickthrough":"http://www.brand.com/productA"}, {"Name":"Product B", "Image":"product_b.png", "Clickthrough":"http://www.brand.com/productB"}, {"Name":"Product C", "Image":"product_c.png", "Clickthrough":"http://www.brand.com/productC"}]');

for (i=0; i < products.length; i++) {
  var renderedProduct = createProduct(products[i]);
  renderedProduct.onRelease = function() {
    ADTECH.contentClick("Products", "Clickthrough", products[i]);
  }
}

Note: the first parameter passed is the Collection Name, the second parameter passed is the Property Name that contains the URL and the third parameter passed is the individual Item itself.

In this example, the ONE by AOL: Creative user would then have the ability to add a Tracking Id to each item in the Product collection which would be used to distinguish each clickthrough on a product. The most obvious Tracking Id to use in this example is the product name so that each clickthrough would be tracked against the product name and there would be three click columns in the report:

Click : Products : Product A : Clickthrough

Click : Products : Product B : Clickthrough

Click : Products : Product C : Clickthrough

Tracking Events

Rich media ads usually contain interactive elements for the user to click on, or rollover. It is vital that these extra events are tracked and then reported on when the ad is live. You can track events in a template exactly as you would in a regular ad by making a call to:

ADTECH.event("Event Name")

As an example, if you wanted to ensure that your template includes code to track when a user clicked on an ‘Info’ tab you can simply make a call to

ADTECH.event("Info Tab Clicked")

Tracking Events on Items of a Collection

In some cases you may want to track events on each item of a collection separately. For example, in a gallery of products, you may want to count how many people rolled their mouse over Product A, how many on Product B, Product C etc – i.e a separate tracking event for each item. This is achieved with:

ADTECH.contentEvent("Collection Name", "Event Name", Item);

By making the call like this the event will be tracked and reported on as Collection Name : Tracking Id : Event Name where Tracking Id is something that the user can set for each Item within the ONE by AOL: Creative interface.
This is most easily explained via an example. Let’s again take the collection to define Products but this time add some code to track an event when a user rolls their mouse over each product.

function createProduct(productItem) {
 // Code that creates the product on the stage and then returns it
 return product;
}

var products = ADTECH.getContent('Products',
   '[{"Name":"Product A", "Image":"product_a.png", "Clickthrough":"http://www.brand.com/productA"},
    {"Name":"Product B", "Image":"product_b.png", "Clickthrough":"http://www.brand.com/productB"},
    {"Name":"Product C", "Image":"product_c.png", "Clickthrough":"http://www.brand.com/productC"}]');
 
for ( i=0; i < products.length; i++) {
 var renderedProduct =  createProduct(products[i]);
 renderedProduct.onmouseover = function() {
   ADTECH.contentEvent("Products", "Rollover", products[i]);
  }
}

Note: the first parameter passed is the Collection Name, the second parameter passed is the Event Name to track and the third parameter passed is the individual Item itself.

In this example, the ONE by AOL: Creative user would then have the ability to add a Tracking Id to each item in the Product collection which would be used to distinguish each rollover on a product. The most obvious Tracking Id to use in this example is the product name so that each rollover would be tracked against the product name and there would be three event columns in the report:

Products : Product A : Rollover

Products : Product B : Rollover

Products : Product C : Rollover

Feedback and Knowledge Base