Anatomy of the Layers Builder Widget Design Bar

Extension Development

Last Updated: for: 1.5.4 Time to Read: 4 minutes

Along with widgets, the Design Bar is the heart of the Layers framework. It adds a simple way for users to control the layout and look of their widgets.

Location: /core/helpers/design-bar.php

The input function accepts one parameter as an array, the function then decodes the array as needed.

Default arguments are:

  • $type- Sidebar type, side/top.
  • $widget- Array containing the name and ID for our Design Bar input. Standard arguments are seen in the example below, but any value can be used for each.
  • $instance- Widget $instance, this is where the Design Bar values will be generated.
  • $components- Array of standard components to output.
  • $custom_components- Array of custom components and elements to output.

It’s important to note that the Design Bar must be used inside a widget and is best used when extending the Layers_Widget  class.

A basic example of the Design Bar being used is as follows.

Layers has the following pre-built design bar elements.

layout

This will output the Full Width / Boxed layout controls. Use the get_widget_layout() function to grab the correct layout class on the front end of your widget.

Usage inside a widget:

The values returned are as follows:

  • layout-boxed
  • layout-fullwidth

liststyle

This will output the Grid / Masonry / List controls.

Usage inside a widget:

The values returned are as follows:

  • list-grid
  • list-masonry
  • list-list

columns

This will a select box with 1 to 6 Column layouts to choose from as well as a checkbox to select whether or not to add a gutter to each li.

Usage inside a widget:

 

textalign

This will output the text align selector which we use to dictate the alignment of Tile & Excerpt text inside our Layers Widgets.

As of 1.5, it is preferable to use the fonts control and defaults to set the new Title Heading button. Use the textalign option in the design bar only on elements with no heading controls.

Usage inside a widget:

The values returned are as follows:

  • text-left
  • text-center
  • text-right
  • text-justify

fonts

This will output the font control which allows users to select text size, alignment and color.

Each part of this control is used seperately on the front end, here’s an example of how we’d put it to use in a widget to apply to a column.

imagealign

This will output the image vs. text align selector. This option is used to determine whether or not your featured image and text sit next to each or on top of one another.

Usage inside a widget:

The values returned are as follows:

  • image-left
  • image-right
  • image-top

featuredimage

This will output the featured image controller which allows users to select a featured image, enter in featured video embed code and choose an image ratio.

To use this control inside our widget let’s use the
layers_get_feature_media();
helper function.

imageratios

This will output the image ration portion of the Featured Image controller.

Here’s an example of how we’ve used this control inside the Content Widget.

background

This will output the background control which allows users to select a background for a specific widget, as well as columns and slides)

Implementation of this control is simpler than the font controls as it only requires a single line of code to be implemented on the widget front end, here’s an example of how we’d apply a background to an entire widget.

advanced

The advanced control lets users add a custom class, CSS, margin and padding to a widget. We’ve created some helper functions to take care of some of the logic for developers on the front end too.

The following line will add the margin, padding, and custom CSS using the apply_widget_advanced_styling();function.

While adding a custom class to your widget is a more manual process, here’s the implementation in our Content Widget.

custom

Custom elements utilize the input() function in the Layers_Form class. It allows you to add custom icons and group of inputs to your widget.

These elements will appear in the order that you have specified, for example, if you want your custom elements to appear after the background control but before the advanced control, you’d do the following:

The $custom_components  portion of the Design Bar accepts an array of controls each of which has its own list of elements. Here’s what that array will look like.

Each component will then take the following arguments in an array:

  • icon-css- CSS to apply to the control toggle.
  • label- Label for this control elements- Array of form elements (which will obey theLayers_Form_Elements->input();methodology)

So let’s piece this final portion together in a custom control which allows users to specify some custom display toggles and call to action button settings.