PremiumJS Docs

* indicates a new addition only availble in the lastest version

Premium.creative

This component is already setup in the main.js file of the boilerplates. These are functions to declare rather than to call.

Premium.creative.init

Called when the library is loaded and ready.

Premium.creative = {
...
  init: function() {
     // main initial creative code here
  }
...
}

Premium.creative.loaded

Called when the library and the DOM content has loaded.

Premium.creative = {
...
  loaded: function() {
     // code to run after DOM load here
  }
...
}

Premium.creative.removed

Called when the containing panel iframe has been removed. Only for use in a temporary expanded/overlay panel.

Premium.creative = {
...
  removed: function() {
     // code to run after panel removed here
  }
...
}

Premium.video

Premium.video.SyncAttemptInterval

Sets milliseconds between sync attempts default: 2000

Premium.video.SyncAttemptInterval = 500;

Premium.video.SyncAttemptThreshold

Sets seconds to be out of sync to trigger a sync attempt default: 0.2

Premium.video.SyncAttemptThreshold = 1;

Premium.video.endedOffset

Sets seconds to offset from the end of the video (to overcome browsers not rendering when a video is paused at the end) default: 0.15

Premium.video.endedOffset = 0;

Premium.video.sync(videoEl, numPanels, syncType)

videoEl	target video element required
numPanels	number of panels across which to sync optional
syncType	type of sync default: Premium.video.SyncType_Send

Registers video to be synced. Play, pause and mute/unmute will lock with any other videos registered. If type is SyncType_Send, when the video plays for the first time it will send its sync info to other videos. If type is SyncType_Get, the first time the video plays it will try get sync info from other videos. SyncType_Send is the default and will be the most useful. SyncType_Get is for dynamically added videos (for example expandable panels) that need to adjust themselves to the videos in the main part.
There is also SyncType_SendOnExpand (for use in a standard panel) and SyncType_SendOnRemoved (for use in a dynamic expanded panel). Using these types will make the video that is not 'in focus' pause.

// in main panel
Premium.video.sync(videoContainerEl, 2);

// in expandable panel
Premium.video.sync(videoContainerEl, undefined, Premium.video.SyncType_Get);

Premium.video.unsync()

De-registers a synced video, allowing the possiblity to dynamically sync multiple videos.

Premium.video.unsync();

Premium.video.switchOnScroll(videoContainerEl, numPanels, callOnSwitch, threshold)

videoContainerEl	target video container (usually jp-controls div) optional
numPanels	number of panels across which to sync required
callOnSwitch	callback function, will be called on switching optional
threshold	the number of pixels scroll after which to switch default: <TOP_PANEL_HEIGHT>

Registers videos to switch visibility when the browser is scrolled past a certain amount. If you need to do more custom stuff on switching the video, you can pass a function as callOnSwitch. This function will be sent either “up” or “down” as its only parameter. If required, you can even omit the video element completely and just use the callback.
Note, this function implements Premium.video.sync() automatically.
(There is a variable Premium.video.pauseVideoWhenHidden. Default is false. If true, the hidden video will pause.)

// in top panel
Premium.video.switchOnScroll(document.getElementById("video-container"), 2, switchedHandler);

// in side panel
Premium.video.switchOnScroll(document.getElementById("video-container"), 2, switchedHandler);

Premium.video.getSync(type)

type	either "all", "playpause", "volumechange" or "time" default: "all"

Sends a message to all other videos registered to send their sync info.

Premium.video.pauseWhenOutOfView(useWholeCreative, threshold, videoEl, videoPlacement, noPlayOnHover)

useWholeCreative	if true, video(s) will pause when the whole creative is out of view, rather than the video element(s) default: false (for bottom panels of mobile formats, only true works)
threshold	decimal percentage amount to count as out of view default: 0.5
videoEl	target video element default: All video elements
videoPlacement	placement of the video, either 'top' or 'bottom' (only for use with mobile skins) optional
noPlayOnHover	if true, prevents automatically adding Premium.video.playOnHover(videoEl) default: false

Plays and pauses video(s) when they are in and out of view. User interacting with the video (PremiumJpControls.getLastAction().playPause === “pause”) will override this. This works for scrollers and Skins. When used in a Skin, it refers to the top panel scrolling up and will always use the whole creative, not the video element.
If the type of the creative is in Premium.video.AutoPlayOnHoverIDs (“cf", "pu", "sa”), it will just call Premium.video.playOnHover(videoEl) instead.
Please note this function should be called only once at the entry-point of the creative code.

Premium.video.pauseWhenOutOfView(true, .5, document.querySelector("VIDEO"));

Premium.video.playOnHover()

This will play and pause a video when the user hovers over it, or on another element.

You can do this in 2 ways

Unspecified:

Premium.video.playOnHover();

Specified:

Premium.video.playOnHover(".video", "#hoverEl");

// OR

Premium.video.playOnHover(document.getElementById("video"), "body");

Premium.video.allowPauseWhenOutOfView(videoEl, allow)

videoEl	target video element required
allow	true or false will turn on or offt required

Turns on/off Premium.video.pauseWhenOutOfView()

Premium.video.allowPauseWhenOutOfView(document.querySelector("VIDEO"), false);

Premium.video.initPlayFromUser(videoEl, audioEl)

videoEl	target video element required
audioEl	target audio element optional

Initializes code to play (and then pause) the media elements from the first touchstart event. This is main for allowing video sync on IOS devices.

Premium.video.initPlayFromUser(document.querySelector("VIDEO"));

jp-createvideo-src

The jpxApi.createVideo has an HTML attribute interface. Just create a DIV with the following attributes:

jp-createvideo-src	path to a local video or a VAST tag
jp-createvideo-controls	jp-controls values
jp-createvideo-poster	path to a local poster frame

Premium.creative.createVideoPlayerAppended

This function is for use with the jp-createvideo-src interface. It is to be declared, rather than called. Perform any actions required on the video inside this function, for example Premium.video.pauseWhenOutOfView() or Premium.video.sync()

Premium.creative.createVideoPlayerAppended = function(video, container) {
// video === video tag in the HTML
// container === div with jp-createvideo- attributes
}

Premium.utils

Premium.utils.getInView(el, threshold)

el	target element required
threshold	amount to consider as being in view default: 0.5

Returns true if el is in view. It works for all the panels of scrolling formats (is, mt, fi, hi), the pd, and the top and centre panels of the wp. For all other formats it works in a limited way.

var isInView = Premium.utils.getInView(document.querySelector(".element"));

Premium.audio

Premium.audio.inactiveTabListener(elements)

elements	media elements to be inlcuded default: all media elements

Initializes media elements to either pause or mute when the current tab becomes inactive.

Premium.audio.inactiveTabListener(document.querySelectorAll('VIDEO'))

Premium.communicator

Premium.communicator.init(numPanels)

numPanels	number of panels that need to communicate together required

Initiates the communicator. Each panel will receive messages once all panels are loaded.

Premium.communicator.init(3);

Premium.communicator.api.sendMessage(message)

message	message to be sent (usually an object) required

Sends a message.

var mess = {from:"id1", action:"do-something"};
Premium.communicator.api.sendMessage(mess);

Premium.communicator.api.receiveMessage(func)

func	function will be called when a message is sent. Called with one parameter - the message required

Set function to receive messages.

Premium.communicator.api.receiveMessage(function(mess){
  if (mess.action==="do-something"){
   // do something here
  }
})

Premium.communicator.sharedObj

A shared object for sharing data between panels. It is available immediately on Premium.creative.init

// in one panel
Premium.communicator.sharedObj.frameIndex = 0;

// in another panel
Premium.communicator.sharedObj.frameIndex === 0; // true

Premium.product

Premium.product.id()

Returns the product code of the creative ("wp", "cf", "hi" etc)

if (Premium.product.id() === "wp"){
// this is a Skin
}

Premium.product.dimensions

A dynamic object with dimensions info.

var creativeWidth = Premium.product.dimensions.width;
var topWindowHeight = Premium.product.dimensions.top.height;

Premium.product.baseURL

The base URL of creative assets.

var absoluteVideoPath = Premium.product.baseURL + "assets/video.mp4";

Premium.product.creativeEl()

Returns the iframe holding the creative panel.

Premium.product.creativeMainEl()

Returns the iframe or div holding the main creative panel. In a Skin, this is the top.html panel. In a Mobile Skin this is the main.html panel.

Premium.product.topBarEl()

Returns the black bar defining the top of a scrolling creative.

Premium.product.bottomBarEl()

Returns the black bar defining the bottom of a scrolling creative.

Premium.product.initOrientationMessage(message, background)

Initiates device orientation message. Please note this function should be called only once at the entry-point of the creative code.

message	message to be displayed default: "Please rotate your device"
background	css background value for containing div default: black

Premium.product.initOrientationMessage("Rotate your device for the best experience!", "rgba(0,0,0,.5)");

Premium.product.scopeWindow

The window scope in which the product code is running. In most environments, this is the same as window.top. This should always be used in place of any direct reference to the top window.

Premium.product.scopeWindow === window.top // true (in most cases)

Premium.product.scopeWindow.addEventListener("scroll", function(){
// do some scroll action
})

Premium.clicktag

Premium.clicktag.getVars()

Returns the jp_creative_vars from the top window.

Premium.clicktag.overrideLandingPage

If set, it will override the landing page in the hosting tag.

// set landing page
Premium.clicktag.overrideLandingPage = "https://justpremium.com/";

// set back to default
Premium.clicktag.overrideLandingPage = undefined;

jp-noClick

Prevent an element from linking to the landing-page.

jp-url

This can be used to link an element to a different URL.

Formats

jp-scale

This only works for the desktop skin / wallpaper format.

As this format is responsive and combines multiple panels, sometimes you need to make elements scale to maintain the same layout on different website widths.

To help with this, you can use jp-scale. Adding this attribute to an element will make it scale to match the scale of the top panel.

At the bottom of the Skin local development preview you will find a slider. Use this to simulate the different website widths on which the Skin will be displayed.

Premium.expand

Premium.expand.expand(htmlSrc, iFrameStyle, containingDivStyle, closeDark, closeButtonStyle)

htmlSrc	path to the expandable html (relative to the main creative) required
iFrameStyle	inline style for the iframe optional
containingDivStyle	inline style for the containing div overlay optional
closeDark	true for dark style close button default: false (light style)
closeButtonStyle	inline style for the close button optional

Adds an iframe over the whole top window with html content set to the htmlSrc file. A functioning close button is automatically added

Premium.expand.expand("expanded.html", "width:500px;height:400px");

Premium.expand.callOnLoaded(func, id)

func	function to call when loaded required
id	unique reference required

Registers a function to be called when the expanded panel is loaded.

Premium.expand.callOnLoaded(function(){
console.log("expanded panel loaded!");
}, "my-id");

Premium.expand.removeCallOnLoaded(id)

id	unique reference required

De-registers a function with reference id.

Premium.expand.removeCallOnLoaded("my-id");

Premium.expand.callOnClosed(func, id)

func	function to call when closed required
id	unique reference required

Registers a function to be called when the expanded panel is closed.

Premium.expand.callOnClosed(function(){
console.log("expanded panel closed!");
}, "my-id");

Premium.expand.removeCallOnClosed(id)

id	unique reference required