Chapters

This Page

    Section API

    Introduction

    PageLines Section system allows developers to use their imagination in creating their own unique sections. These sections can add extra functionality and can also be packaged and given away (or sold) to other PageLines users.

    Using this 'API', you can define what kind of content the sections load on the page, and use the option engine to add options directed at that particular sections.

    Example Starter Section

    To help you understand the basic configuration and setup for a section, we've created a basic starter section for you to use and reference.

    View Starter Section

    Setup

    Section File Structure

    The first part of section development, is setting up your section files.

    Sections are supported in a variety of areas; and are used primarily as plugins in your WordPress plugins folder. However, they are also supported inside of child themes.

    A basic section will have a folder name.
    The folder should be names as follows: pl-section-[section_id].

    Inside the section you will have the primary PHP file that should be named the same as the folder: pl-section-[section_id].php.

    If there is a file names style.css inside of the section plugin, this CSS file will be automatically loaded when the section if found on a page.

    Aside from this, this base folder can support any number of files and media; just make sure that the section code calls these files appropriately.

    wp-content
    └──plugins
        └── pl-section-[section_id]
            ├── pl-section-[section_id].php
            ├── style.css
            ├── readme.md
            └── (other files)

    Section Headers

    Once you open up the main section PHP file, the first thing you'll see is the section headers. These are the basic information that you use to set up your section and its meta information inside the system.

    /*
      Plugin Name:  PageLines Section [Section Name]
      Description:  [A short description...]
      Author:       [Your Name]
      Author URI:   [Your URL]
      Docs:         [Docs Url]
      Version:      [Version Number e.g. 5.0.0]
      PageLines:    [Section_Class_Name]
      Filter:       [Where to show in the builder: component, basic, advanced, gallery, slider, content, localsocial, wordpress]
      Category:     [category tags (comma separated)]
      Tags:         [standard tags (comma separated)]
      Loading:      [Should this section force frame reload (active or refresh)]
    */
    • PageLines Header Set to the same as the section PHP class name.
    • Filter Header Determines where section is shown in add-new panels.
    • Loading Header If set to refresh, the section will force a frame reload when added to a page.

    The Section Class Format

    To control the when and where of the section functionality, PageLines uses a standard PHP class format. Here is the the basic structure, with inline formatting explaining what each component does:

    <?php
    
    /*
      Plugin Name:    PageLines Section My Section
      Version:        5.0.0
      PageLines:      PL_My_Section_Class
    */
    
    /** A PHP Guard to prevent the section from loading if it's not supposed to */
    if( ! class_exists('PL_Section') ){
      return;
    }
    
    /** The section class extends a standard core PL_Section class */
    class PL_My_Section_Class extends PL_Section {
    
      /** This method runs on every page load on both the admin and front end. Ideal for options and other hooks (ajax) */
      function section_persistent(){ // persistent code and hooks here }
    
      /** This method runs if a section is placed on a page. This way we can ensure that scripts and styles are only included if need be. */
      function section_styles(){ // styles here }
    
      /** This method should return an options configuration array for the section */
      function section_opts(){ return array(); }
    
      /** This is the HTML output that shows on the page for the section */
      function section_template(){ // HTML here }
    
    }
    

    Now your section is started! Now let's build on this...

    Basic Section Class Attributes

    Since the sections extend a base class, each section gets several standard attributes and methods that can be references in your code:

    $url  = $this->base_url;      // The base URL for the section
    $dir  = $this->base_dir;      // The base directory for the section
    $id   = $this->id;            // The section ID
    $nm   = $this->name;          // The section name
    $opt  = $this->opt('key');    // Get the option value for: 'key'

    Methods

    Adding Scripts and Styles

    All section scripts and styles should be included using the pl_script and pl_style functions respectively, from within the section_styles method in a section.

    function section_styles(){
    
      // pl_script( 'unique_id', 'http://url_to_file.js' );
      // pl_style(  'unique_id', 'http://url_to_file.css' );
    
      pl_script(  $this->id,          plugins_url( 'pl.popthumbs.js', __FILE__ ) );
    
      pl_script(  'prettyphoto',      plugins_url( 'prettyphoto.min.js', __FILE__ ) );
      pl_style(   'prettyphoto-css',  plugins_url( 'prettyPhoto/css/prettyPhoto.css', __FILE__ ) );
    
    }

    Adding Hooks & Filters

    Sections can easily use hooks and filters to access other elements of the WordPress system. Add these hooks inside of the section_persistent method.

    function section_persistent(){
    
      add_filter('the_content', array($this, 'adjust_content'));
    
    }
    
    function adjust_content( $content ){
    
      // do something...
    
      return $content;
    }

    AJAX Callbacks

    A typical use of a hook inside of Platform 5 is to create an AJAX callback for a callback binding. To add an AJAX callback, again simply add it to the section_persistent method with the appropriate name.

    function section_persistent(){
      add_filter('pl_binding_' . $this->id, array( $this, 'callback'), 10, 2);
    }
    
    
    function callback( $response, $data ){
    
      $response['template'] = $this->do_callback( $data['value']);
    
      return $response;
    }

    Templating

    Section Template

    The section_template method is what outputs all the HTML that is rendered for your section on the page.

    // This will be output wherever the section is located on the page.
    function section_template(){ ?>
    
     <div class="my-element">Some Text</div>
    
    <?php }

    Great! Now that we know how to output HTML, all we have to do is create some options for users and "bind" them to the HTML output.

    Options

    To add options for any section, we just need to use the section_options method and return a standard options array.

    function section_options(){
    
      $options = array();
    
      $options[] = array(
          'type'    => 'text,             // type of option
          'key'     => 'my_unique_key',   // the unique key for option, referred to in HTML bindings
          'title'   => 'My Option Title', // Title for option UI
          'help'    => 'Any help for the user',
          'label'   => 'Option Label',
        );
    
      return $options;
    }
    
    

    Options arrays are a powerful way to control the options for your section and are fully documented in the 'options array' document.

    Bindings

    Once we have options created for the section, all that is left is for us to 'bind' them to the section template.

    In PageLines, bindings are done via a very simple data-bind HTML api.

    
    function section_template(){ ?>
     <!-- This will sync to the value of the option with the 'my_unique_key' key parameter -->
     <div class="my-element" data-bind="pltext: my_unique_key"></div>
    
    <?php }

    Bindings are very powerful and are fully covered in their own document within PageLines developer docs.

    Nested Sections

    Sections can also allow for sections to be nested inside of them. In other words, sections can contain other sections.

    And do enable this within a section only requires two lines of code! They are:

    • A section header of Contain: yes
    • The function pl_nested_container( $this ); inside of section_template

    Something like this:

    
    <?php
    /*
      Plugin Name: My Section
      (other headers)
      Contain:      yes
    */
    
    class PL_Section_MySection extends PL_Section {
    
      function section_template(){ ?>
        <div class="my-other-section-stuff">
            <?php pl_nested_container( $this ); // render nested sections ?>
          </div>
        </div>
      <?php
      }
    }

    Other Methods

    Section Head

    If you'd like to output raw HTML into the head of your HTML document (if the section is one the page) then you'll want to use the section_head method.

    function section_head(){
      // This will out put in between your sites <head> tags.
      // For example, adding javascript:
      ?>
    
      <script>
      jQuery(window).ready(function() {
        // Javascript could go here.
      });
      </script>
    
    }

    Section Foot

    Likewise if you'd like to output HTML specifically in the page footer. You'll want to use the section_foot method.