Multi Panel Positioning

Adform Multi Panel Positioning is compound banner placement and positioning feature used in conjunction with single tag. Main purpose of this feature is to simplify work needed to place banners with synchronized animation in right positions on the page.

Effected banner types are Standard, Expanding and SingleExpanding without floating behavior. If any other type of banner is found on compound members list panel script will deliver that member without any modifications.

NOTE: currently floating type banners are not supported in singleTag. If there's a floating banner, it will be drawn twice.

Getting started

First thing you will need is compound banner tag. For example: 

<script
  src="http://track.adform.net/adfscript?bn=2169165;compoundSeqNo=1"
  type="text/javascript"></script>

Now you just replace compoundSeqNo=1 with singleTag=1 (single tag parameter) and add data-panels="1=f:3,p:lti;2=f:3,p:rti;3" attribute which defines compound members positions, more on these in multi panel tag section.

Result would be: 

<script
  src="http://track.adform.net/adfscript?bn=2169165;singleTag=1"
  data-panels="1;2=f:1,p:lb,z:1;3=f:1,p:rb,z:1"
  type="text/javascript"></script>

Configuration & API

Whole multi panel configuration is implemented thru Adform Rich Media API (ARMA).

Multi Panel Positioning configuration is read and merged from several places: compound banner settings, JavaScript URL (before section), data-panels attribute and finally media site ARMA code.

API:

#.panel.id

Used to merge Adform and media multi panel configurations. For example: [ '#media-stuff.panel', { ... } ] will extend [ '#2.panel', { id: 'media-stuff', ... } ] settings.

#.panel.from

If from property is type string it is interpreted as DOM Element ID of a placement where banner should be rendered. Usually string form would be used by publishers to define various placements on the page.

Type number is used to define from which member should banner floated.

#.panel.position

In total it can be 25 banner positions for floated positioning and 3 for static.

Position values are made up from letters T - top, R - right, B - bottom, L - left and suffix i - inner. Position string is case insensitive.

Float positions are used then panel.from is type number (banner is floated from other member).

Static positions:
L
R
Float positions:
LT
LTi
L
LBi
LB
LiT
LiTi
Li
LiBi
LiB
T
Ti
Bi
B
RiT
RiTi
Ri
RiBi
RiB
RT
RTi
R
RBi
RB

#.panel.x, #.panel.y

Horizontal and vertical offset in pixels from banner current position. Used to slightly modify banner position.

#.panel.z

Value of style property z-index set to banner. Used to manage page layout overlaps with banner.

#.panel.sticky

Pixels from top of window then to trigger sticky behavior, if value set to true element behaves as fixed floating banner.

Sticky positioning combines floated and fixed positioning. Normally sticky positioned tags behaves as floated positioned, i.e. on page scroll the tag moves and preserves relation to other elements in page. When placement moves up out of viewport the tag starts to behave as fixed positioned and remains on top of page despite scroll.

#.panel.hidden

Compound member is hidden, used in conjunction with ADFCall('<bn>', 'show') to show members later. Works same as #.hidden ARMA code.

Events & Panel API:

In order to change some panel(s) properties on the fly, user should use Panel API, which will be passed as settings.options.panel object before on.init event.

Examples: 

// globaly - for every banner
(_adform = window._adform || []).push(['on.init', function () {
  console.log(this.options.panel);
}];

// for 2nd synchronized banner only
(_adform = window._adform || []).push(['#2.on.init', function () {
  console.log(this.options.panel);
}];

API methods

#.set()

Set desired panel property or properties.

#.get()

Get desired panel property value.

Examples: 

// will change every panel z-index to 100001
(_adform = window._adform || []).push(['on.init', function () {
  var panelAPI = this.options.panel;
  panelAPI.set('z', 100001);
  console.log('z-index: ' + panelAPI.get('z')); // z-index: 100001
}];

Configuration in media

Mainly multi panel configuration in media is used to define placements for static members. For example _adform.push([ '#top.panel.from', 'top-ad-placement-id' ]);

Media configuration differ from tag in that way that media should use #<panel id> instead of #<compund sequance number>. In that way we can separate banner sequence number from banner positioning in media.

Multi Panel TAG

Multi panel tag is Adform single tag with additional data-panels attribute which represents shortened (is translated to) ARMA code.

data-panels attribute syntax

Each compound member expression separated by ; and consists of compound sequence number, = character for assignment and configuration string with parameters separated by comma. 

<compund seqence number>=<option name>:<option value>;<compund seqence number>=<option name>...

In some cases option value is optional and be translated as true.

Translation to ARMA

As mentioned multi panel attribute is translated to ARMA code. Translation rules is as follows:

From: 

<compund seqence number>=<option name>:<option value>;<compund seqence number>=<option name>...

To: 

_adform.push(
  [ '#<compund seqence number>.panel', { '<option name>': '<option value>' } ],
  [ '#<compund seqence number>.panel', { '<option name>': true } ]);

Some option names are shortened for convenience. Shortened options are: