Origami Frontend Components & Services

JSDoc: o-ads

o-ads is not maintained by the Origami team. While this component may be used, we make no guarantees about the support status, though we will help if we can.

clearPageTargetingForKey

Global Function

Removes page targeting for a specified key from GPT ad calls

Links

setPageCollapseEmpty

Global Function

Sets behaviour of empty slots can be 'after', 'before' or 'never'

  • 'after' collapse slots that return an empty ad
  • 'before' collapses all slots and only displays them when an ad is found
  • 'never' does not collapse any empty slot, the collapseEmptyDivs method is not called in that case

Links

enableCompanions

Global Function

When companions are enabled we delay the rendering of ad slots until either a master is returned or all slots are returned without a master

Links

updateCorrelator

Global Function

The correlator is a random number added to ad calls. It is used by the ad server to determine which impressions where served to the same page Updating is used to tell the ad server to treat subsequent ad calls as being on a new page

Links

defaults

Global Property

Default configuration set in the constructor.

Links

new Config

Defines a store for configuration information and returns a getter/setter method for access.

Links

new Slot

The Slot class.

Methods

  • parseAttributeConfig - (instance) parse slot attribute config
  • initLazyLoad - (instance) Load a slot when it appears in the viewport
  • initResponsive - (instance) Listen to responsive breakpoints and collapse slots where the configured size is set to false
  • maximise - (instance) Maximise the slot when size is 100x100
  • setName - (instance) If the slot doesn't have a name give it one
  • collapse - (instance) add the empty class to the slot
  • addClass - (instance) add the additional class to the slot
  • setFormatLoaded - (instance) sets a classname of the format
  • uncollapse - (instance) remove the empty class from the slot
  • clear - (instance) call the ad server clear method on the slot if one exists
  • destroy - (instance) call the ad server destroySlot method on the slot if one exists
  • submitImpression - (instance) call the ad server impression URL for an out of page slot if it has been configured correctly for delayed impressions
  • fire - (instance) fire an event on the slot
  • addContainer - (instance) add a div tag into the current slot container
  • centerContainer - (instance) Add a center class to the main container
  • labelContainer - (instance) Add a label class to the main container

Links

new Slots

The Slots instance tracks all ad slots on the page configures global page events used by a slot and provides utlity methods that act on all slots

Methods

  • collapse - (instance) Given a slot name or an array of slot names will collapse the slots using the collapse method on the slot
  • uncollapse - (instance) Given a slot name or an array of slot names will uncollapse the slots using the uncollapse method on the slot
  • refresh - (instance) Given a slot name or an array of slot names of slotnames will refresh the slots using the refresh method on the slot
  • clear - (instance) Given a slot name or an array of slot names will clear the slots using the clear method on the slot
  • destroy - (instance) Given a slot name or an array of slot names will destroy the slots using the destroySlot method on the slot and remove the reference to the slot
  • submitImpression - (instance) Given a slot name will submit a delayed impression for the slot
  • initSlot - (instance) Confirms a container in the page exists and creates a Slot object

Links

module:utils/events

Utility methods for o-ads events. Methods defined here are added to the utils object not the utils.event object.

Methods

  • broadcast(...) - (static) Broadscasts an o-ads event
  • on(...) - (static) Sets an event listener for an oAds event
  • off(...) - (static) Removes an event listener for an oAds event
  • once(...) - (static) Sets a one time event listener for an oAds event

Links

module:utils

Utility methods for the advertising library.

Properties

  • isArray - Test if an object is an Array
  • isString - Test if an object is a String
  • isFunction - Test if an object is a Function
  • isStorage - Test if an object is a Storage object
  • isObject - Test if an object is an Object
  • isWindow - Test if an object is the global window object
  • isPlainObject - Test if an object inherits from any other objects, used in extend to protect against deep copies running out of memory and constructors losing there prototypes when cloned
  • isNonEmptyString - Test if an object is a string with a length
  • hash - Create an object hash from a delimited string Beware all properties on the resulting object will have string values.
  • attach - Takes a script URL as a string value, creates a new script element, sets the src and attaches to the page The async value of the script can be set by the seccond parameter, which is a boolean Note, we should use protocol-relative URL paths to ensure we don't run into http/https issues
  • dehyphenise - Remove hyphens from a string and upper case the following letter
  • parseAttributeName - remove prefixes from o-ads data attributes and dehyphenise the name
  • getQueryString - return the current documents search or an empty string if non exists also strips the initial ? from the search string for easier parsing This method enables us to mock the search string in our tests reliably and doesn't really serve any other purpose
  • getQueryParamByName - Get a query string parameter by name from a url
  • getTimestamp - returns a timestamp of the current date/time in the format YYYYMMDDHHMMSS
  • iframeToSlotName - Given the window object of an iframe this method returns the o-ads slot name that rendered the iframe, if the iframe was not rendered by o-ads this will return false

Links

module:utils/log

Utility methods for logging.

Properties

  • isOn - Determine if debug logging is on and if the type if supported
  • warn - Log a warning message
  • error - Log an error message
  • info - Log an info message
  • start - Start a collapsed group
  • end - End a collapsed group

Links

module:utils/log(type, args)

Safe logger for the browser

parameter type default description
type string Sets the type of log message log, warn, error or info, if not set to one of these values log will be used
args any the arguments to be passed to console[type]

Properties

  • isOn - Determine if debug logging is on and if the type if supported
  • warn - Log a warning message
  • error - Log an error message
  • info - Log an info message
  • start - Start a collapsed group
  • end - End a collapsed group

Links

module:utils

Utility methods for postMessage api.

Properties

  • isArray - Test if an object is an Array
  • isString - Test if an object is a String
  • isFunction - Test if an object is a Function
  • isStorage - Test if an object is a Storage object
  • isObject - Test if an object is an Object
  • isWindow - Test if an object is the global window object
  • isPlainObject - Test if an object inherits from any other objects, used in extend to protect against deep copies running out of memory and constructors losing there prototypes when cloned
  • isNonEmptyString - Test if an object is a string with a length
  • hash - Create an object hash from a delimited string Beware all properties on the resulting object will have string values.
  • attach - Takes a script URL as a string value, creates a new script element, sets the src and attaches to the page The async value of the script can be set by the seccond parameter, which is a boolean Note, we should use protocol-relative URL paths to ensure we don't run into http/https issues
  • dehyphenise - Remove hyphens from a string and upper case the following letter
  • parseAttributeName - remove prefixes from o-ads data attributes and dehyphenise the name
  • getQueryString - return the current documents search or an empty string if non exists also strips the initial ? from the search string for easier parsing This method enables us to mock the search string in our tests reliably and doesn't really serve any other purpose
  • getQueryParamByName - Get a query string parameter by name from a url
  • getTimestamp - returns a timestamp of the current date/time in the format YYYYMMDDHHMMSS
  • iframeToSlotName - Given the window object of an iframe this method returns the o-ads slot name that rendered the iframe, if the iframe was not rendered by o-ads this will return false

Links

Ads#init(options)

Instance Method

Initialises the ads library and all sub modules

parameter type default description
options object a JSON object containing configuration for the current page

Links

slotMethods.defineSlot

Static Method

define a GPT slot

Links

slotMethods.destroySlot

Static Method

Tell gpt to destroy the slot and its metadata

Links

slotMethods.setUnitName

Static Method

Set the DFP unit name for the slot.

Links

slotMethods.addServices

Static Method

Add the slot to the pub ads service and add a companion service if configured

Links

slotMethods.setCollapseEmpty

Static Method

Sets the GPT collapse empty mode for a given slot values can be 'after', 'before', 'never'

Links

slotMethods.setURL

Static Method

Sets page url to be sent to google prevents later url changes via javascript from breaking the ads

Links

slotMethods.setTargeting

Static Method

Adds key values from a given object to the slot targeting

Links

FT.ads.config

Static Method

The FT.ads.config object holds the confiuration properties for an FT.ads.gpt instance. There are four tiers of configuration; cookie level config, default config (set within the constructor), metatag config and global (env) config. Global config, (set in the page FT.env ojbect) takes priority over meta followed by default config with cookie config having the least priority. The FT.ads.config() function acts as an accessor method for the config; allowing getting and setting of configuration values. Calling config() with no parameters returns the entire configuration object. Calling config passing a valid property key will envoke the 'getter' and return the value for that property key. Calling config passing a valid property key and a value will envoke the setter and set the value of the key to the new value. Calling config passing an object of keys and values will envoke a setter that extends the store with the object provided.

Links

Slot#parseAttributeConfig

Instance Method

parse slot attribute config

Links

Slot#initLazyLoad

Instance Method

Load a slot when it appears in the viewport

Links

Slot#initResponsive

Instance Method

Listen to responsive breakpoints and collapse slots where the configured size is set to false

Links

Slot#maximise

Instance Method

Maximise the slot when size is 100x100

Links

Slot#setName

Instance Method

If the slot doesn't have a name give it one

Links

Slot#collapse

Instance Method

add the empty class to the slot

Links

Slot#addClass

Instance Method

add the additional class to the slot

Links

Slot#setFormatLoaded

Instance Method

sets a classname of the format

Links

Slot#uncollapse

Instance Method

remove the empty class from the slot

Links

Slot#clear

Instance Method

call the ad server clear method on the slot if one exists

Links

Slot#destroy

Instance Method

call the ad server destroySlot method on the slot if one exists

Links

Slot#submitImpression

Instance Method

call the ad server impression URL for an out of page slot if it has been configured correctly for delayed impressions

Links

Slot#fire

Instance Method

fire an event on the slot

Links

Slot#addContainer

Instance Method

add a div tag into the current slot container

Links

Slot#centerContainer

Instance Method

Add a center class to the main container

Links

Slot#labelContainer

Instance Method

Add a label class to the main container

Links

Slots#collapse

Instance Method

Given a slot name or an array of slot names will collapse the slots using the collapse method on the slot

Links

Slots#uncollapse

Instance Method

Given a slot name or an array of slot names will uncollapse the slots using the uncollapse method on the slot

Links

Slots#refresh

Instance Method

Given a slot name or an array of slot names of slotnames will refresh the slots using the refresh method on the slot

Links

Slots#clear

Instance Method

Given a slot name or an array of slot names will clear the slots using the clear method on the slot

Links

Slots#destroy

Instance Method

Given a slot name or an array of slot names will destroy the slots using the destroySlot method on the slot and remove the reference to the slot

Links

Slots#submitImpression

Instance Method

Given a slot name will submit a delayed impression for the slot

Links

Slots#initSlot

Instance Method

Confirms a container in the page exists and creates a Slot object

Links

Targeting#getFromConfig

Instance Method

getFromConfig returns an object containing all the key values pairs specified in the dfp_targeting config.

Links

Targeting#socialFlow

Instance Method

If there is a query parameter called socialflow=xxx, we need to add it as a tag

Links

module:utils/events.broadcast(...)

Static Method

Broadscasts an o-ads event

parameter type default description
name string The name of the event
data object The data to send as event detail
target HTMLElement The element to attach the event listener to

Links

module:utils/events.on(...)

Static Method

Sets an event listener for an oAds event

parameter type default description
name string The name of the event
callback function The function to execute on the event
target HTMLElement The element to attach the event listener to

Links

module:utils/events.off(...)

Static Method

Removes an event listener for an oAds event

parameter type default description
name string The name of the event
callback function The function on the event to be removed
target HTMLElement The element the event listener is attached to

Links

module:utils/events.once(...)

Static Method

Sets a one time event listener for an oAds event

parameter type default description
name string The name of the event
callback function The function to execute on the event
target HTMLElement The element to attach the event listener to

Links

module:utils.isArray

Static Property

Test if an object is an Array

Links

module:utils.isString

Static Property

Test if an object is a String

Links

module:utils.isFunction

Static Property

Test if an object is a Function

Links

module:utils.isStorage

Static Property

Test if an object is a Storage object

Links

module:utils.isObject

Static Property

Test if an object is an Object

Links

module:utils.isWindow

Static Property

Test if an object is the global window object

Links

module:utils.isPlainObject

Static Property

Test if an object inherits from any other objects, used in extend to protect against deep copies running out of memory and constructors losing there prototypes when cloned

Links

module:utils.isNonEmptyString

Static Property

Test if an object is a string with a length

Links

module:utils.hash

Static Property

Create an object hash from a delimited string Beware all properties on the resulting object will have string values.

Links

module:utils.attach

Static Property

Takes a script URL as a string value, creates a new script element, sets the src and attaches to the page The async value of the script can be set by the seccond parameter, which is a boolean Note, we should use protocol-relative URL paths to ensure we don't run into http/https issues

Links

module:utils.dehyphenise

Static Property

Remove hyphens from a string and upper case the following letter

Links

module:utils.parseAttributeName

Static Property

remove prefixes from o-ads data attributes and dehyphenise the name

Links

module:utils.getQueryString

Static Property

return the current documents search or an empty string if non exists also strips the initial ? from the search string for easier parsing This method enables us to mock the search string in our tests reliably and doesn't really serve any other purpose

Links

module:utils.getQueryParamByName

Static Property

Get a query string parameter by name from a url

Links

module:utils.getTimestamp

Static Property

returns a timestamp of the current date/time in the format YYYYMMDDHHMMSS

Links

module:utils.iframeToSlotName

Static Property

Given the window object of an iframe this method returns the o-ads slot name that rendered the iframe, if the iframe was not rendered by o-ads this will return false

Links

module:utils/log.isOn

Static Property

Determine if debug logging is on and if the type if supported

Links

module:utils/log.warn

Static Property

Log a warning message

Links

module:utils/log.error

Static Property

Log an error message

Links

module:utils/log.info

Static Property

Log an info message

Links

module:utils/log.start

Static Property

Start a collapsed group

Links

module:utils/log.end

Static Property

End a collapsed group

Links

Switch component view

GitHub Repository

Install o-ads

If using the Build Service, add o-ads@^13.1.0 to your script and link tags.

If running a Manual Build, run bower install --save "o-ads@^13.1.0".

Help & Support

o-ads is not supported directly by the Origami team. We make no guarantees, but will help if we can. First try contacting its maintainers at:

Slack: #advertising-dev
Email: origami.advertising.technology@ft.com