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:

1. After section is rendered, trigger javascript script for element.
2. Use a render function duplicate the 'synced' output from the system.
3. Apply the plugin script to the duplicated item.
4. 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.

View Starter Section

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.