Blocks & Panels

Block & panel layouts are an alternative to free-form layouts that provide more visual structure to your web page content, and allow you to break your page up into bite-sized visual elements (the panels) that tile and align themselves neatly.

Blocks and panels are box-like containers for your content. Blocks span the full width and therefore "stack" vertically, whereas panels typically are smaller and will "stack" horizontally or into grids, at least on larger displays. They are are responsive, and will automatically reflow to accommodate the available screen width.

The basic block & panel layout concept is therefore something like this:

This is the block title

Because blocks are full-width, they can contain lengthly text content, unlike the panels which are very constrained in size.

Panel 1

Panel 2

Panel 3

Panel 4

Any number of panels can be appended to the panel list; they will automatically tile as shown. Any number of blocks can be appended to the block list; they will simply stack up like different sections of the page. The entire page can be comprised of blocks, or blocks can be inserted into the middle of free-form content, as in the example above.

Although blocks and panels differ in how they "stack up" visually, they are otherwise quite similar in their basic behaviours. They are both treated as box-like containers for content, which consists of:

a title or heading
some text
an image or graphic
an action button or link

These basic elements can be formatted in a variety of ways, so the actual HTML mark-up that generates the block or panel is customizable, and it is up to you whether you want to include each of the above elements in any particular case.

Panels

Panels are smaller and simpler than blocks, so we will cover them first. Here is an example of a single panel that displays each the above four elements in a simple way:

Panel Example

Panel Title

This is the panel text.

action label

Your website can support multiple panel styles. The different formats allow the four elements above to be arranged in completely different ways, depending on your design wishes. For example, images could fill the panel as a background, fill the header as a cap, float within the text as a thumbnail, or be left out entirely.

Panels also support different classes. This allows you to apply variations to your layouts (such as colours or backgrounds), without changing the basic HTML markup.

One generic panel layout is pre-defined to help get you started. However, the expectation is that you will add your own custom panel layouts and classes to your system configuration.

Example Format

The default panel format serves as a helpful illustration for how to construct your own panel formats:

<div class='panel panel-default[[?class]] panel-[[class]][[/?class]]'>
  <div class='panel-heading'><h3 class='panel-title'>[[title]]</h3></div>
    <div class='panel-body'>
    [[?img]]<img src='[[img]]' width=150 style='float:right'>[[/?img]]
    [[html]]
    <div class='panel-tools'>[[tools]]</div>
  </div>
</div>

This generates a Bootstrap panel, with a 150-px image that floats right within the pane. The merge codes in this example are:

class - this example is set up to let you use standard Bootstrap classes to style the panel, eg. primary, success, info, warning, and danger.
title - this places the title into a panel header bar.
img - if the panel has an image, this will float the image to the upper right of the panel, with a small thumbnail size of 150 px.
html - the panel text will fill the main pane of the panel.
tools - the action button will be placed at the end of the panel contents, on its own line.

Defining Panel Formats and Classes

The CMS will use the generic panel format, if no special panel format is selected. To override the generic format, specify the fomat in your main configuration file:

content.format.panel = (your panel format...)

Install alternative formats in the same way, but append your custom format name to the panel name, as shown here for a custom format named "foo":

content.format.panel_foo = ...

When configuring a panel, you can specify which layout to use in the Layout field. If you prefer, you can switch this field to a selector to make it easier to pick-and-choose from the available layouts. The list of selectable layouts is determined by the list:panel datatype in your dbmap .datatype file. Set this list to the panel types you want to be able to select from, for example:

list:panel_format select foo|bar|oof

You can name your formats whatever you want, as long as they are short alphanumeric strings. Separate the format names with the bar character, |.

Similarly, you can define a list of panel classes in the same way.

list:panel_class select info|success|danger|primary

Use the class merge code to incorporate the selected class into the panel format, as demonstrated in the example format above.

If you do not define these list types, then the panel layouts and classes will be text fields, and you must type out the format and class names you want to use.

Panel Actions

Panels support action buttons - these are just prominent links (often, but not necessarily, styled like buttons) placed in the panel. They are generated via the standard Content::tools method, and placed using the tools format merge code.

Actions consist of an URL and a label, which are combined to make the link. The URL will accept a numeric content ID, in which case, the CMS will use the URL of that content object.

The action label is optional, but defaults to "Read more..."

You do not have to implement your action link as a distinct link or button. The action URL can be used directly in your panel format using the action merge code. You can use this to hotlink your titles, images, or whatever else you want to serve as the action anchor.

Panel Images

Panels support a single image, which is incorporated into the panel layout in whatever way the format specifies. To manually set up a panel image, create a subcontent item under the panel, and upload the image there. The panel will automatically use the first image subcontent as its display image.

Use the img merge code to insert the panel image into the format in the way that suits you best. You can make it conditional to cover cases where no image is defined.

There are a few methods to insert panel images if no explicit image has been uploaded.

First, you can use the panel class to implicitly set background images using your stylesheets.

If you prefer to use an explicit img tag, you can also define default images to use based on the panel's class. Add a configuration setting like:

content.panel.image.CLASS = CONTENT_ID

where CONTENT_ID is the ID of the image you want used when the panel's class is set to CLASS.

If you want to choose randomly from a selection of images, specify your content IDs as a comma-separated list. For example:

content.panel.image.foo = 1234,1235,1236

In this case, panels of the foo class will automatically incorporate image 1234, 1235, or 1236 into their layout. If the page is static, the image choice will also be static, but will randomize every time the page is published.

To define an image for panels with no class set, use a pseudo-class name of "default" in the configuration setting, for example:

content.panel.image.default = 1230

To override automatically-defined images, simply install your panel image manually, as described above.

Note that panels will often have specific constraints for image dimensions/aspect ratios. Take care to upload appropriately-shaped images for best results.

Blocks

Blocks are 'super-panels'. They have all the attributes of panels, except:

they are full-width
they can can have two actions, not just one
they can include indexes of panels

Block indexes are basically rows of panels that fill the screen horizontally, wrapping into grids as necessary. The index fills out the block, and can be as long or as short as necessary. Blocks have an index_max configuration setting that caps the length of the panel index. It defaults to 3, but can be set to any number.

As with panels, you can define the block's actions, format, and class through its configuration settings. They also have some extra settings to preselect default styles for the block's panels.

Block Layouts

Block layouts and classes are managed the same way as panel layouts/classes, for example:

content.format.block_foo = ...
list:block_format select foo|bar|oof
list:block_class select info|success|danger|primary

You can use similar format and class names if it suits you, or different ones.

You should include an index merge code in your block format to place the panel index. If you require additional markup to wrap your panels in the index, you can optionally define start, end, and join strings to fill out the index, ie:

start PANEL1 mid PANEL2 mid PANEL3 end

Use the following configuration settings to define these wrap/fill strings:

content.block.html_start = ...
content.block.html_mid = ...
content.block.html_end = ...

Automatic Blocks & Panels

Normally your blocks and panels will be set up manually: you will define the titles, upload the images, enter the content, and define the actions. If you created a block then you will do the same thing for each of the panels within it.

Alternatively, this can be fully automated. Automatic blocks and panels will "mirror" some other content on your website. When that content updates, the blocks or panels will automatically incorporate those changes.

To set up a panel that automatically mirrors some other content, do as follows:

create the panel; you do not need to set up any of its contents
in the panel configuration, point to the source content object by entering the content ID into the "Summarize content ID" field

The panel will then automatically obtain its content (text, image, and action link) from the original content. The panel will then act like a preview for the original content, with a link for the viewer to read more if it interests them.

Automatic blocks are even more powerful, because they not only mirror the original content object, but they automatically construct a panel index that recapitulates the original content's index. For example, if you create a block to summarize a News blog, then the block will automatically generate its own panels to list the current news stories. Similarly, if you create a block to summarize a calendar, it will automatically generate its own panels to list the upcoming events.

Because these panel indexes are generated automatically, you have no direct access to the sub-panel configurations. However, you can set up rules for how to select panel formats and classes in these cases:

content.panel.format.TYPE = ...

will define the format of an auto-generated panel that represents content TYPE. (For example, TYPE could be "event" for a calendar block, or "article" for a news block.)

Similarly,

content.panel.class.TYPE = ...

will define the class of a panel of content TYPE. So an event panel could be given a different CSS class, while sharing the same markup as other panels. Alternatively, you can use the content metadata to get a class name:

content.panel.classmeta.TYPE = metaname

will set the panel's CSS class to a metadata value from the panel's reference content object. For example, if your events have an event_type metadata setting, which can be set to "course", "conference", or "webinar", then you could set:

content.panel.classmeta.event = event_type

and your panels would automatically be assigned a class of course, conference, or webinar, as appropriate. That would allow you to set colours or background images automatically to indicate the type of event being shown.

Block & Panel Content Management

Blocks and panels are special content classes, so every panel and every block is a distinct content object that is managed separately from the content around it.

In My Website, pages will automatically detect when blocks and panels are present in the page, and allow you to edit them separately from the main body of free-form content. You will also get tools to add panels to a panel index, and to re-order your panels.

When you edit a free-form page body, blocks and panels will be represented using a simple icon placeholder. You can move this icon around to reposition the block. In the low-level source (which you can access directly using the System Browser) these placeholders look like this:

< !--panel(NAME)-->

(The placeholder always says "panel" even if it is actually a block.) The behaviour of these placeholder tags is otherwise similar to the more general-purpose

< !--content(NAME)-->

You can use these placeholder tags directly if you are editing templates at the source code level.