Basic Section Programming

Sections are the most powerful feature of PageLines. It allows developers to build modularly, and is built to be optimized by utilizing the PageLines Sections API.

Learn to build sections and themes with PageLines DevCamp.

Today, I'm going to show you how to create your own section from scratch. We're going to be using one of my favorite jQuery scripts, Cycle2. It's quick, it's fast, and doesn't require a ton of jQuery knowledge at all.

Learn to build sections and themes with PageLines DevCamp.

cycle-section-demo

  Demo  Download

Section Setup

First thing's first, let's create a folder in the PageLines Sections plugin folder, and name it Cycle. That's what we'll call our section. Inside that folder, create a style.less file, and a section.php file. In the section.php file, paste this in.

<?php
/*
Section: Cycle
Author: Nick Haskins
Author URI: http://nichola.us
Version: 1.0
Description: Custom section
Class Name: baCycle
Cloning: true
Workswith: header, footer, main, templates, sb_2, sb_2, sb_wrap
*/

class baCycle extends PageLinesSection {

  const version = '1.0';

  // Loads no matter if the section is on the page or not
  function section_persistent(){
	  
  } 

  // Scripts go here
  function section_scripts() {
    
  }
  
  // Stuff going in <head>
  function section_head(){
		  
  } 
  
  // Content Display
  function section_template( $clone_id = null ) { 
		  
  }
  
  // Option Panel
  function section_optionator( $settings ){
		  
	$settings = wp_parse_args($settings, $this->optionator_default);
			
	$opt_array = array(
	  'ba_slider_option' 	=> array(
	    'type' 	 => 'text',
	    'inputlabel' => 'Option 1',
	    'title' 	 => 'Option 1',
	    'shortexp'	 => 'This is an option field.',
          ),
          'ba_slider_option2' => array(
	    'type' 	 => 'text',
	    'inputlabel' => 'Option 2',
	    'title' 	 => 'Option 2',
	    'shortexp'	 => 'This is another option field.',
	  ), 
	);
	
	$settings = array(
	  'id' 		=> $this->id.'_meta',
	  'name' 	=> $this->name,
	  'icon' 	=> $this->icon, 
	  'clone_id'	=> $settings['clone_id'], 
	  'active'	=> $settings['active']
	);
	
	register_metatab($settings, $opt_array);
  }	
	
}

Class Breakdown

Inside the class we have a bunch of functions that are utilizing the PageLines Sections API. This makes shit happen automagically, which makes it so damn easy to develop sections (and in general) using PageLines.

At the top of the file we have our document headers with the section name, author, etc. Three important ones here to note; class name, cloning, and workswith. The class name obviously matches the name of the class in your first line. Cloning let's users clone the section within drag & drop. Workswith, defines where the section can and can't be used.

function section_persistent is code that will always run, no matter if your section is on the page or not. You'll add things like actions and filters here.

function section_scripts is the function you'll use to enqueue your scripts. These scripts will only be loaded on the pages that have the section. There's also section_styles, that you can use to enqueue css files. However, everything is LESS based, so the style.less file located in your section is automatically picked up and compiled.

function section_head stuff like script initialization, and anything else you want outputted into will go here.

function section_template is where most of your code actually lives. This is what is displayed on the front-end of the site.

function section_optionator is a special PageLines function that creates an Options Panel for the section. Option panels are visible under Page Options-->Your Section, for global settings, and Single Page-->Your Section, for single page options. We won't utilize this during this tutorial, but will be utilizing it in the next tutorial.

Write Code

Let's build some shit shall we? Start in the section_template function. Remember, this is what is displayed on the front-end. PageLines will automatically wrap your section with .content and .content-pad, so all that's left is to write some code. Paste this into the section_template function.

?><div class="ba-slideshow-wrap">
  <div class="cycle-slideshow">
	<img src="http://placekitten.com/900/600" alt="cat">
	<img src="http://baconmockup.com/900/600" alt="cat">
	<img src="http://placekitten.com/900/600" alt="cat">
  </div>
</div><?php

Great so what we have is a simple div, with a few images,wrapped with an outer div. We've given it a few classes, including .cycle-slideshow, the class that Cycle2 uses to do it's thing. It's also important to note here, to namespace your div. We'll use that in LESS to nest our rules so your stuff will never conflict with anyone else's.

Load Scripts

That's literally all we really need to start. Create a page, assign it a template, load the section on the page template, and view the site. You should see 3 images, stacked one on top of the other. Now, let's load Cycle 2.

Head on over to the Cycle2 site, and download the production version of the script. You'll need to create your own .js file, paste the contents, then save the file as jquery.cycle2.min.js in your sections folder. Now, let's enqueue it. Typically, we have to register first with Wordpress, but not with the way PageLines sections work. All we need to do is enqueue the js file. Paste the below contents into section_scripts function.

wp_enqueue_script('cycle-script',$this->base_url.'/jquery.cycle2.min.js',array('jquery'),self::version);

Refresh the page where your section is at, and you should automatically see the slideshow working.

Style

Now we're ready to apply some very basic styles, just to get you in the habit of writing with LESS and using the default core LESS variables that are bundled with PageLines. If you're building a section for the general masses, use the core LESS variables to style your sections. You're being consistent by matching the default PageLines install, not to mention that it speeds up the actual paint job.

Paste this into your blank, style.less file, then refresh the page. Don't see your changes? That's because the LESS file is cached. Save the framework. Yup, just give it a random save. When you save settings, it recompiles and recaches this file. Now your settings show up. You can turn off the caching of course, just put this in your wp-config file. define('PL_LESS_DEV',true);. Do NOT use this on a production server because it compiles on every page load which will result in very poor performance. Only use it locally during development.

.ba-slideshow-wrap {
  padding:4px;
  .box-sizing(border-box);
  background:@baseContrastSlight;
  border:1px solid @baseContrast;
  .border-radius(5px);
}

The LESS variables @baseContrastSlight and @baseContrast are 2 of the core LESS variables found in PageLines. Both are similar, and will return a color a shade darker than what the user has set as their body background color. It's color automation at it's finest. More about core LESS variables on a later post. For now, bask in the amazingness that is your first PageLines section!

Wrap up

We've barely scratched the surface here with sections. I mean all we have right now is a cool slideshow, but what if you want to upload your own images? What about next and previous buttons, or letting the user control the speed? That's coming up on the next tutorial, Advanced Section Programming.

2 Replies
filed under
  • Aaron:

    Hi Nick, Awesome tutorial. With PageLines documentation as outdated/non-existent as it is, this has been my greatest source of information on writing sections so far. Any plans to follow up with the Advanced Section Programming tutorial in the near future? Thanks for the great help! p.s. The line-height in this message field is pretty smooshed, FYI. I'm using Google Chrome, but it's weird in firefox and ie9 as well. Cheers!

    Thursday 7th March, 2013, 12:00am

    • Nick:

      Awesome I'm glad it's helpful for you Aaron! Yup next article is up in the next few days here, and line-height fixed. Thanks!

      Thursday 7th March, 2013, 12:00am

  • Nick Haskins | Advanced Section Programming:

    [...] We last left off introducing what a PageLines section was, followed by a basic skeleton layout with a [...]

    Tuesday 12th March, 2013, 12:00am