Chapters
This Page
Section Javascript
Introduction
To enable real-time editing of javascript driven elements, such as carousels or sliders, there are special considerations in Platform 5. This is because the javascript has to be made aware of new elements and rerendered.
To get around this problem, PageLines has engineered some utilities to. Specifically, trigger classes and simple rerendering functions.
How it works
The basic process for working with javascript elements works like this:
- After section is rendered, trigger javascript script for element.
- Use a render function duplicate the 'synced' output from the system.
- Apply the plugin script to the duplicated item.
- Every time the settings changed for the section, destroy the rendered section and repeat the first three steps
Starter Section
The starter section has a javascript file included that has the basic structure for working with javascript in PageLines.
Setting Up
Javascript File
The first step is to include the javascript file and structure the js so that it fires after the section is setup:
To include the file, simply use the pl_script
function within the section_styles
method of the section class.
/**
* Include extra scripts and styles here
* Use the pl_script and pl_style functions (which enqueues the files)
*/
function section_styles(){
/** Include the sample script */
pl_script( $this->id, plugins_url( 'starter.js', __FILE__ ) );
}
Structuring the Javascript File
jQuery Namespace Wrapper Note that we wrap the entire file in a wrapper designed to contain the jQuery namespace and prevent leakages between scripts.
template_ready The template_ready
event is designed to fire on the section wrapper after it is loaded and whenever an element with the .pl-trigger
class changes. This allows you to rerender based on user option changes.
plRenderItem The plRenderItem()
function will scan the entire section for items with the pl-render-item
class. If it finds, them it will duplicate the item and use it to apply any scripts (e.g. a jQuery plugin).
.loaded Optionally you can use a loaded class guard to prevent scripts from being applied to the same elements multiple times. This can happen if the template_ready event fires multiple times for whatever reason.
!function ($) {
/** Set up initial load and load on option updates (.pl-trigger will fire this) */
$( '.pl-sn-starter' ).on('template_ready', function(){
$.plStarterSection.init( $(this) )
})
/** A JS object to encapsulate functions related to the section */
$.plStarterSection = {
init: function( section ){
var that = this
/**
* plRenderItem()
* Use a wrapper to look for and clone elements with the .pl-render-item class
* This prevents the binding code from getting confused by the slider code
*
* (If it finds one already there, remove it and create a new one)
*/
var rendered = plRenderItem( section )
/** Apply the JS to the element */
rendered
.not('.loaded')
.addClass('do-something-here') // Here is where you'd apply any scripts
.addClass('loaded') // Use a loaded class to prevent things triggering multiple times ()
}
}
/** end of jQuery wrapper */
}(window.jQuery);
pl-trigger
Class
Apply a class of pl-trigger to elements that, when their binding values change, should cause a rerendering of the section (via JS).
A common example might be the wording inside a slide from a rendered section, this will require a rerender because the users won't see the change until it is rerendered.