Layouts Framework API

Layouts Framework API allows to register different CSS frameworks, which Layouts plugin will use to render front-end content.

Contents of this document:

Overview of Layouts integration with theme frameworks
Layouts Framework API Filters:
Example setup for integration of Layouts with the Foundation Framework

Overview of Layouts integration with theme frameworks

Layouts can work only with theme frameworks that use the 12-column system to render contents, which most modern frameworks do.

To be able to successfully integrate Layouts with any theme framework, it is important to understand how it renders the contents.

There are three basic elements that most of modern theme frameworks use: container, rows and columns. Additionally, offset for content cell is an important setting that frameworks use to define empty columns to the left of the content cell.

Basically, Layouts integration with theme frameworks means adjusting the CSS classes of these elements, so that they match the ones used by the framework.

To accomplish this, you will use the filters listed on this page. You need to put them, with according settings, in the functions.php of the theme framework you want to integrate with Layouts.

Layouts Framework API Filters

ddl-set_framework

This filter is used to set the current framework in WordPress option table in ddl_layouts_css_framework_options options record.

Synopsis

apply_filters('ddl-set_framework', 'framework-slug')

Arguments

$framework – string, the framework slug in computer readable format

Examples

private function set_default_framework( )
{
	if( !is_array( $this->options_manager->get_options() ) )
	{
		$this->set_framework( apply_filters('ddl-set_framework', self::DEFAULT_FRAMEWORK ) );
	}
}

ddl-set_up_frameworks

This filter is used to set an array of supported frameworks.

Synopsis

apply_filters('ddl-set_up_frameworks', array('framework-slug' => (object) array('label' => 'Framework Nice Name') ) )

Arguments

$frameworks_array – every framework record in the list is a $key $value pair where the $key is the framework slug as defined with the ddl-set_framework filter, while the value is an object with label as mandatory member field.

Examples

private function set_up_frameworks()
{
	$this->supported_frameworks = apply_filters('ddl-set_up_frameworks', array() );
	$this->supported_frameworks['bootstrap-2'] = (object) array('label' => 'Bootstrap 2');
	$this->supported_frameworks['bootstrap-3'] = (object) array('label' => 'Bootstrap 3');
}

ddl-get_container_class

Some frameworks use different CSS classes for the main content container tag. This filter is meant to define or override this CSS class to define a container element.

Synopsis

static function get_container_class(){
	return apply_filters('ddl-get_container_class', 'container');
}

Arguments

$class (string) – the value of the CSS class to be applied to the HTML element to behave as a container.

Examples

Override the default value with a custom value.

add_filter('ddl-get_container_class', function( $el ){
return 'container';
});

ddl-get_row_class

This filter is meant to define or override the CSS class that defines a row element in the grid.

Synopsis

static function get_row_class(){
	return apply_filters('ddl-get_row_class', 'row');
}

Arguments

$class (string) – the value of the CSS class to be applied to the HTML element to behave as a row.

Examples

Override the default value with a custom value for the Foundation framework.

add_filter('ddl-get_row_class', function( $el ){
	return 'row';
});

ddl-get-column-prefix

This filter is meant to define or override the CSS class prefix will be assigned to an element and make it behave as the “cell” unit in the rendering framework. This is the element actually displaying as a column in the grid system of the chosen framework.

Synopsis

static function get_column_prefix(){
	return apply_filters('ddl-get-column-prefix', 'col-sm-');
}

Arguments

$prefix/$array (mixed/string/array) – the value of the CSS class to be applied to the HTML elements to behave as columns.

Example

Override the default value with a custom value for the Foundation framework.

add_filter('ddl-get-column-prefix', function( $el ){
	return 'columns small-';
});

By using this API filter it is also possible to extend the class names for columns to use multiple classes by returning an array instead of a simple string.

In the following example we are using all the classes available for the Foundation framework.

add_filter('ddl-get-column-prefix', function( $el ){
	return array('small-', 'medium-', 'large-');
});

On the front-end, this will render the following code for a column.

<div class="small-6 medium-6 large-6 columns">
<!-- CONTENT HERE -->
</div>

ddl_no_templates_at_all

This filter is useful as a way of telling Layouts there are templates to render it. Layouts checks the theme directory for templates compatible with the plugin and if no such templates are found, the plugin is not fully functional and Layouts warns you of this in the WordPress administration area.

However, there are frameworks that will not have template files compatible with the plugin, but we are still able to make them compatible with Layouts. An example of this is the Genesis framework.

In this case, you are providing templates with redirections and will probably want to override this value in order to have full plugin functions.

Synopsis

apply_filters('ddl_no_templates_at_all', $bool);

Arguments

$bool (boolean) – if true, Layouts interprets this that no supported templates are available.

Examples

Override the default value with a custom value and let Layouts know there are templates to render it.

add_filter('ddl_no_templates_at_all', function( $bool ){
	return false;
});

ddl_check_layout_template_page_exists

This filter is very much like the ddl_no_templates_at_all one, but used to check if template that supports Layouts exists for a specific post type.

Synopsis

apply_filters( 'ddl_check_layout_template_page_exists', true, $post_type );

Arguments

$bool (boolean) – true if the post type has a suitable template for rendering Layouts.
$post_type (string) – the post type slug

Examples

Push your templates to the list and tell Layouts to always provide full functionalities for page post type.

add_filter('ddl_templates_have_layout', function( $bool, $post_type ){
	if( $post_type === 'page' ){
		$bool = true;
	}
	return $bool;
});

ddl_templates_have_layout

This filter returns the list of available templates that support Layouts. If no templates are available, it returns an empty array.

Synopsis

apply_filters('ddl_templates_have_layout', $layout_templates, $templates);

Arguments

$layout_templates (array) – the templates available for layouts.
$templates (array) – all templates available in theme.

Examples

Push your templates to the list and let Layouts know there are templates to render it.

add_filter('ddl_templates_have_layout', function( $layout_templates, $templates ){
	$layout_templates[] = MY_PATH . '/my-template.php';
	return $layout_templates;
});

ddl-get_container_fluid_class

This filter is used to define/override the CSS class for a fluid container element, if any.

Synopsis

static function get_container_fluid_class(){
	return apply_filters('ddl-get_container_fluid_class', 'container-fluid');
}

Arguments

$class (string) – the value of the CSS class to be applied to the HTML element, so as to make it behave as a fluid container.

Examples

Override the default value with a custom value.

add_filter('ddl-get_container_fluid_class', function( $el ){
	return 'container-fluid';
});

ddl-get_rows_modes_gui_list

Rows in layouts can have different rendering modes, for example they can have the width same as the container, they can have the 100% width of the page, etc.

This filter allows you to append your own custom mode(s) to the list of row modes in the row editing dialog.

Synopsis

function render_row_modes_gui(){
	ob_start();
	include_once 'wpddl.row-mode-gui.tpl.php';
	echo apply_filters('ddl-get_rows_modes_gui_list', ob_get_clean() );
}

Arguments

$lists_html (string) – the html string of the row modes GUI, you want to manipulate

Examples

In the next example we append to the list of modes a Genesis Framework’s Header mode, to let the user select a full background width row that features a site-header class with Genesis custom styles.

add_filter( 'ddl-get_rows_modes_gui_list', 'add_genesis_header_row_mode' );

function add_genesis_header_row_mode($lists_html){
	ob_start(); ?>

<li>

<figure class="row-type">
		<img class="item-preview" data-name="row_genesis_header" src="<?php echo WPDDL_GUI_RELPATH; ?>dialogs/img/tn-boxed.png" alt="<?php _e('Gensis head', 'ddl-layouts'); ?>">
		<span><?php _e('Genesis header row', 'ddl-layouts'); ?></span>
	</figure>

	<label class="radio" data-target="row_genesis_header" for="row_genesis_header" style="display:none">
		<input type="radio" name="row_type" id="row_genesis_header" value="genesis_head">
		<?php _e('Genesis head', 'ddl-layouts'); ?>
	</label>
	</li>

	<?php
	$lists_html .= ob_get_clean();
	return $lists_html;
}

Since we’ve added an element an additional CSS rule should be added to let Layouts GUI know that it should render the list with four elements instead of three:

.presets-list li{width:25%!important;}

ddl_render_row_start

This is a very powerful filter that allows to override the markup structure that is rendered for the row element in the grid.

Synopsis

apply_filters( 'ddl_render_row_start', $markup, $args );

Arguments

$markup (string) – html structure to be overridden
$args (array) – an associative array with all the rows’ fields

Examples

In the following example we render a custom row for the Genesis framework checking the $mode we are setting by overriding the row dialog GUI with the ddl-get_rows_modes_gui_list filter.

add_filter('ddl_render_row_start', 'genesis_site_header', 99, 2);

function genesis_site_header($markup, $args){

	if( $args['mode'] === 'genesis_head' ){
		ob_start();?>
		<<?php echo $args['tag']; ?> class="site-header full-bg <?php if ($args['additionalCssClasses']) { echo $args['additionalCssClasses']; } ?>"<?php if ($args['cssId']) { echo ' id="' . $args['cssId'] . '"'; } ?>>

<div class="<?php printf('%s', $args['container_class']) ?>">

<div class="<?php echo $args['row_class'] . $args['type']; ?>">
		<?php
		$markup = ob_get_clean();
	}

	return $markup;
}

ddl-get_additional_column_class

This filter allows to add a generic column class name if the framework you use needs one. For example, Bootstrap framework doesn’t have one while Foundation uses the columns class.

Synopsis

static function get_additional_column_class(){
	return apply_filters('ddl-get_additional_column_class', '');
}

Arguments

$class (string) – the value of the additional CSS class to be applied to the HTML elements.

Example

Override the default value with a custom value for the Foundation framework.

add_filter('ddl-get_additional_column_class', function( $el ){
	return 'columns';
});

ddl-framework_supports_responsive_images

This filter adds support for responsive image handling in the Layouts native Image Box cell. Its default value is true.

Synopsis

static function framework_supports_responsive_images(){
	return apply_filters( 'ddl-framework_supports_responsive_images', true );
}

Arguments

$bool (boolean) – whether or not to display controls for Bootstrap responsive images.

Example

add_filter('ddl-framework_supports_responsive_images', function( $bool ){
	return false;
});

ddl-get_thumbnail_class

This filter sets the class name for the CSS style of a thumbnail image.

Synopsis

static function get_thumbnail_class(){
	return apply_filters('ddl-get_thumbnail_class', 'thumbnail');
}

Arguments

$class (string) – the class name for the thumbnail image.

Example

In this example we set the class name that is used by the Foundation framework.

add_filter('ddl-get_thumbnail_class', function( $class ){
	return 'th';
});

ddl-get_column_width

This filter sets the width of a column at the time of rendering.

Synopsis

apply_filters('ddl-get_column_width', $width, $column_prefix, $this );

Arguments

$width (integer) – the width of the column in the grid
$column_prefix (string) – the column prefix for the class property of the HTML node element rendering the cell in a grid
$renderer – the WPDD_layout_render object instance that is rendering the grid

Example

Sometimes it is useful to give different proportions to the columns in a row, depending on the width of the target device.

For example, we could have a two-column layout, whose design looks best with the proportions split in 25% – 75% for small devices, 50% – 50% for medium devices and 33% – 66% for large devices.

This filter lets you manipulate the width values in order to meet these different requirements, as shown in the following example.

// Make things at the time $cells render to get some useful data

add_action('ddl-row_cells_render_start', function($row, $cells, $render){

	$count = count( $cells );

	$widths = array_map(function($cells){
	return $cells->get_width();
	}, $cells);

	$max = max( $widths );
	$min = min( $widths );

	$render = new WPDDL_CustomRenderer( $count, $max, $min );

	add_filter('ddl-get_column_width', array($render, 'get_column_width'), 10, 3);

}, 10, 3);


// A custom renderer to make php happy

class WPDDL_CustomRenderer{

	private $max;
	private $count;
	private $min;

	public function __construct( $count, $max, $min ){
		$this->count = $count;
		$this->max = $max;
		$this->min = $min;
	}

	public function get_column_width( $width, $column_prefix, $renderer ){

		if( $column_prefix === 'small' && $width === 1 || $width === 12 || $width === 11){
			return $width;
		} else if( $column_prefix === 'medium' ){

		if( $this->count === 2 && $min > 1 ){
			return 6;
		} elseif( $this->count === 4 && $min === 1 ){
			return 5;
		} else {
			if( $width > 6 ){
				return int_val( $width / 2 );
			} else {
				return int_val( $width * 2 );
			}
		}

		} else if( $column_prefix === 'large' ){

			if( $this->count === 2 && $min > 1 ){
				return 6;
			} elseif( $this->count === 4 && $min === 1 ){
				return 5;
			} else {
				if( $width > 6 ){
					return int_val( $width * 1.5 );
				} else {
					return int_val( $width / 1.5 );
				}
			}
		}

		return $width;
	}

}

This example is rough in its presentation and only a proof of concept, to show the possibilities at hand.

Example setup for Foundation Framework

This is an example setup for the Foundation Framework. These filters can be put inside thefunctions.php file of a theme that supports the Foundation framework. Test theme that is based on this framework and integrated with Layouts can be found.

// Define the name of your framework
add_filter('ddl-set_framework', function( $slug ){
	return 'foundation';
});


// Define the list of supported frameworks
add_filter('ddl-set_up_frameworks', function( $array ){
	$array['foundation'] = (object) array('label' => 'Foundation by ZURB');
	return $array;
});

// Define the CSS class that will be added to the container element
add_filter('ddl-get_container_class', function( $el ){
	return 'container';
});

// Define the CSS class that will be added to fluid container element
add_filter('ddl-get_container_fluid_class', function( $el ){
	return 'container-fluid';
});

// Define the CSS class that will be added to the row element in the grid
add_filter('ddl-get_row_class', function( $el ){
	return 'row';
});

// Define the offset prefix CSS class that will be added to the element in the grid
add_filter('ddl-get_offset_prefix', function( $el ){
	return 'offset-';
});

// Define the prefix CSS classes that will be added to the columns in the grid
add_filter('ddl-get-column-prefix', function( $el ){
	return array('small-', 'medium-', 'large-');
});

// Define any additional CSS classes that need to be added to the columns in the grid
add_filter('ddl-get_additional_column_class', function( $el ){
	return 'columns';
});

// Define if framework supports native support for Layouts Image Box cell responsive images
add_filter('ddl-framework_supports_responsive_images', function( $bool ){
	return false;
});

// Define the CSS class for the thumbnail image
add_filter('ddl-get_thumbnail_class', function( $bool ){
	return 'th';
});