Use Multi-Panel Positioning for HTML5 Banners

Greta
Greta
  • Updated

Adform Multi-Panel Positioning is a compound banner placement and positioning feature used in conjunction with a single tag. Use it to simplify the work needed to place banners with synchronized animation in the right positions on the page.

Use it for standard, expanding, and single-expanding banners without floating behavior. Multi-panel positioning feature won't work for any other type of banner.

Note

Floating type banners aren't supported with single tags.

Prepare the Script for Multi-Panel Positioning

  1. Retrieve a compound banner tag.

    Compound banner tag example

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

  2. Replace compound SeqNo=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.

    Final result example

    <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>

Implement Multi-Panel Positioning

You implement multi-panel configuration through 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

  • Media site ARMA code

Adform Rich Media API has the following settings:

API Setting

Description

#.panel.id

Type: String

Default: null, except first compound member defaults to "top"

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

#.panel.from

Type: Number or String

Default: null

If the property type is string, it's interpreted as DOM Element ID of a placement where banner should be rendered. Publishers use string form to define various placements on the page.

#.panel.position

Type: String

Default: null

There can be 25 banner positions for floated positioning and 3 for static.

Position values are made up of the following letters: T: top, R: right, B: bottom, L: left, and suffix i :inner. The position string is case insensitive.

#.panel.x #.panel.y

Type: Number

Default: 0

It's the horizontal and vertical offset in pixels of the banner's current position. Used to slightly modify the banner position.

#.panel.z

Type: Number

Default: null

It's the value of style property z-index set to the banner. Used to manage page layout overlaps with a banner.

#.panel.sticky

Type: Number or Boolean

Default: null

If the value is set to true, element behaves as a fixed floating banner.

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

#.panel.hidden

Type: Boolean

Default: false

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

Change Panel Properties Using Panel API

To change panel properties, use Panel API, which is passed as settings.options.panel object before on.init event.

Example of changing panel properties

// 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

API Settings

Description

#.set()

  • Type: Function

  • Usage: #.set(key, value) or #.set({ key: value, key2: value2 })

  • Available properties:

    • z:Number - panel and its banner z-index

    • x:Number - panel x coordinate

    • y:Number - panel y coordinate

  • Returns: nothing

Set desired panel property or properties.

#.get()

  • Type: Function

  • Usage: #.get(key)

  • Available properties:

    • z:Number - panel and its banner

    • z-indexx:Number - panel x coordinate

    • y:Number - panel y coordinate

    • width:Number - panel content width

    • height:Number - panel content height

  • Returns: any type value or undefined

Get the desired panel property value.

Example of using API methods

// 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

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

Media configuration differs from a tag, so media should use #<panel id> instead of <compund sequence number>. This way, you can separate banner sequence numbers from banner positioning in media.

Multi-Panel Tag

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

Data-panels attribute syntax

Each compound member expression is separated by a semicolon (;) and consists of a compound sequence number (character for assignment and configuration string with parameters, separated by a comma).

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

In some cases, the option name is optional and is translated as true.

Translation to ARMA

Multi-panel attribute is translated to ARMA code. See the translation of the rules below:

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:

  • position can be written as pos or p

  • from can be written as f

  • sticky can be written as s

Was this article helpful?

/
How we can make it better?

Thank you for your feedback!