Supports Page Builder

Page Builder plugins are often used to allow user to build a page from pre-defined blocks in a free way. Usually such pages called "Landing Pages".

We recommend to use SiteOrigin Page Builder in case you need easy management of your Landing Pages. This plugin has an interface for layout builder (rows/columns) and use usual WordPress widgets as a content blocks. So you can use standard widgets or create your own.

Current Theme Framework has a small extension to make it easier to develop landing pages with a SO Page Builder.

About Page Builder

Problems with a Page Builder plugins

All Page Builders provide a maximum flexibility for a user. They provide options to specify HTML attributes, (class and id), select backgrounds, update font styles, update mobile styles and even write a custom CSS for each element you see. For a technical person this sounds great. However most users who order a custom theme are not experienced enough to configure all these options.

Let's take a look what options user has when he creates a row:

Each row has about 20 different options to configure! The more options end-user see, the more things he can break!

This means that "flexibility" becomes a negative factor for non-technical users.

Page Builder extension

First of all we want to say "Thank you!" to a SiteOrigin developers. They inserted so many hooks inside their code, so you can customize almost anything, without modifications inside the original plugin code.

And we did it! We used these hooks to simplify interface to a few options. Same screen as above looks like this with our addon:

Introducing Layouts

We disabled all default options for rows and widgets. And we defined a new term called "Layout". So any row or widget can have a "Layout".

Layout is a pre-defined set of all the options we have before. All of them are defined inside a theme codebase. If user want to update some styles for a Layout - we just update a Layout definition and there are no need to update all options over the pages in all blocks.

This is extremely useful and our clients are very happy to use such modification.

Cleaner HTML & CSS

By default Page Builder generates a unique HTML structure and CSS styles for all elements based on the options selected inside. This makes HTML code overloaded with lot of useless div classes and pretty big inline CSS parts.

Custom theme creation is always consists of converting client designs into a custom html/css code. We use responsive techniques, media queries to display page on all resolutions and devices. We create all necessary styles before we start working with WordPress backend, and we don't need any CSS or Margins to be entered in an admin panel. Otherwise, end-user can easily break a good looking page and designer will be very sad about that :).

So in our extension we turn off a lot of bad-looking class names and inline CSS. All CSS should be inside a theme stylesheet!

HTML example

After all patches page builder generates HTML similar to this one:

<!-- main container -->
<div class="pb-container">
     
    ... 
     
    <!-- row div -->
    <div class="pb-row pb-row-cols-{number of cols in the row}">
        <!-- inner row div. Background color/image applied to this div by default! -->
        <div class="pb-row-inner">
 
            <!-- Inside rows we have columns. Plugin calls them "cells" for some reason -->
 
            <!-- Cell starts from wrapper -->
            <div class="pb-cell pb-cell-num-{column index} pb-col-sz-{x}">
                <!-- After that inner cell div -->
                <div class="pb-cell-inner">
 
                    <!-- inside cell we have numerous widgets wrapped with such html: -->
                    <div class="pb-widget pb-widget-num-{widget index} {widget type class}">
                        <div class="pb-widget-inner">
 
                        .. WIDGET HTML GOES HERE! ..
 
                        </div>
                    </div>
 
                </div>
            </div>
 
        </div>
    </div>
     
    ...
     
</div>

How it works

Enable page builder support

To enable dummy options, HTML and CSS clean up you need to create an instance of a Page_Builder_Loader class. You can do this in your Theme class inside init() method

If you want to register row or widget layouts - you will need to create a child class. For example:

{theme}/app/Page_Builder/SiteOrigin_Panels.php

<?php
namespace Boilerplate\Theme\Page_Builder;

use Boilerplate\Theme\Page_Builder\Row;
use Boilerplate\Theme\Page_Builder\Widget;
use JustCoded\WP\Framework\Page_Builder\v25\Layouts as Core;
use JustCoded\WP\Framework\Page_Builder\v25\Page_Builder_Loader;

/**
 * Class SiteOriginPanelsLoader
 * Register SiteOrigin Panels special layouts, which can define classes and other html attributes for
 * row/cell wrappers.
 *
 * @package Boilerplate\Theme\Page_Builder
 */
class SiteOrigin_Panels extends Page_Builder_Loader {
	/**
	 * Init row/widgets layouts and change disabled plugins list.
	 */
	public function init() {
		parent::init();

		$this->register_row_layout( Core\Rwd_Row_Layout::class, 'Default' );
		$this->register_row_layout( Row\Wide_Layout::class );

		$this->register_widget_layout( Core\Rwd_Widget_Layout::class, 'Default' );
		$this->register_widget_layout( Widget\Hero_Layout::class );
	}
}

As you can see to register a layout you need to specify a php class name and optional title, which can overwrite title set in a layout class. We use overwrite for a layouts, which are common for most pages and should be used by default, if admin doesn't specify anything.

Class initialisation example:

{theme}/app/Theme.php

	/**
	 * Additional classes initialize
	 */
	public function init() {
		if ( SiteOrigin_Panels::plugin_active() ) {
			SiteOrigin_Panels::instance();
		}
	}

By default this plugin already have 2 layouts, which can be used as a default:

• Rwd_Row_Layout. Registers grid classes like bootstrap. We believe that content editor should not know the direct percent of column width. So we convert percentage into a 12-columns grid system (like Bootstrap CSS framework) and generate column classes based on that. This allows you to create CSS, which match custom design with different columns perfectly.
• Rwd_Widget_Layout. Used for default "clean" layout if noone selected. Could be replaced by a custom created inside a theme.

Creating a Layout

To make your own layout you need to create a child of Row_Layout, Rwd_Row_Layout or Widget_Layout classes (don't forget about namespaces, I skip them to make easier to read).

Both layout types are required to have static $ID and $TITLE properties. You will get a fatal error in case they are empty. $ID is used to assign layout to a row. And $TITLE is used to display it inside Page Builder interface.

After that you can rewrite class methods to provide additional html attributes for a div wrapper.

Row_Layout methods

Method	Description
row( $attributes, $panel_data)	Used to patch attributes for row wrapper div.
row_inner( $attributes, $style_data)	Used to patch attributes for row inner div.
cell( $attributes, $panel_data)	Used to patch attributes for cell wrapper div.
cell_inner( $attributes, $style_data)	Used to patch attributes for cell inner div.
before_row( $html, $panel_data, $grid_data)	Ability to insert html before row.
after_row( $html, $panel_data, $grid_data)	Ability to insert html after row.
options()	Register additional options to configure.

Parameters:

• $attributes (array) Default container attributes
• $panel_data (array) Full panels data settings array
• $style_data (array) Current container data settings
• $html (string) Before/After HTML. By default it's blank.
• $grid_data (array) Grid part of panels data array

Widget_Layout methods

Method	Description
widget( $attributes, $style_data)	Used to patch attributes for widget wrapper div.
widget_inner_classes( $classes, $style_data, $widget, $instance)	Ability to set classes for widget inner wrapper. You can't control other attributes here.
options()	Register additional options to configure.

Let's check an example of a row layout to specify full width classes to a row wrappers and ability to choose background cover option:

<?php
namespace Boilerplate\Theme\Page_Builder\Row;

/**
 * Class Wide_Layout
 *
 * @package Boilerplate\Theme\Page_Builder\Row
 */
class Full_Width_Layout extends \JustCoded\WP\Framework\Page_Builder\v25\Layouts\Rwd_Row_Layout {

	public static $ID = 'full-width';

	public static $TITLE = 'Full Width';

	/**
	 * Additional options to add into Row option controls
	 *
	 * @return array
	 */
	public function options() {
		return array(
			'wide_layout_bg_strech' => array(
				'name'     => 'Strech background',
				'type'     => 'select',
				'group'    => 'layout',
				'options'  => array(
					'No',
					'Yes',
				),
				'priority' => 15,
			),
		);
	}

	public function row( $attributes, $panel_data ) {
		$attributes['class'] .= ' full-width-wrapper';

		return $attributes;
	}

	public function row_inner( $attributes, $style_data ) {
		$attributes['class'][] = ' full-width';

		return parent::row_inner( $attributes, $style_data );
	}
}

RWD plugin support

By default we left options to select background image for a row. In case you use Just Responsive Images plugin we can print background image through rwd plugin function to resize images in several resolutions.

By default it will use large image size. To overwrite this size you should set $background_image_size property in your layout class:

<?php
namespace Boilerplate\Theme\Page_Builder\Row;

/**
 * Class Wide_Layout
 *
 * @package Boilerplate\Theme\Page_Builder\Row
 */
class Full_Width_Layout extends \JustCoded\WP\Framework\Page_Builder\v25\Layouts\Rwd_Row_Layout {

	public static $ID = 'full-width';

	public static $TITLE = 'Full Width';

    public $background_image_size = 'rwd';

Styles generation is happen inside Row_Layout::row_inner() base class method. If you want to overwrite this logic you can overwrite generate_inline_styles() method in your layout.