The Layout Widget

The First-Time Users documentation briefly covered the Layout widget in the Barebones CMS. This documentation covers everything about the Layout widget that you will likely ever need to know.


The Layout widget is the main method of creating and managing wireframe layouts and general website designs. Of all the default widgets, it is slightly less complex than the Content widget and a lot more complex than the Code widget. The layout widget allows the creation of additional master widgets on a page.

The Layout widget powers each page's layout of this website.
The Layout widget powers each page's layout of this website.

The Layout widget has a dialog to manage the layouts used throughout a site and makes extensive use of the Code Editor to edit the layouts.


The Layout widget offers a number of features that are useful to web designers:

The Layout widget makes it easy to add a wireframe layout or site design to a page with areas for more widgets. It is even possible to get fancy and have Layout widgets inside Layout widgets. For example, the Barebones CMS homepage uses a two column Layout inside the main site layout.


The Layout widget lets you do whatever you want in terms of wireframe layouts on each page. The strength of this widget is creating distinct lines between wireframe and content layouts. That said, some web developers may opt to use the Layout widget to define some content for the sake of convenience. Specifically, a static header and footer across a site that does not change dynamically based on the loaded page.

One of the odd quirks about the Layout widget is that simply placing the widget on the page does nothing. A specific layout has to be "Activated" before anything shows up. This allows layouts to be swapped in and out on the fly and could be useful, for instance, to test a temporary holiday theme for the homepage.

This website uses a custom-built layout for all the pages in the site:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "">
<html xmlns="" xmlns:v="urn:schemas-microsoft-com:vml">
<link rel="stylesheet" href="Main.css" type="text/css" media="screen" />
<style type="text/css">
body {
	background-position: 0 110px;
// Site layout, header, and footer.
<div class="pagewrap">
	<div class="headerwrap">
		<a class="mainlogo" href=""><img src="/images/main-logo.png" alt="Barebones CMS" /></a>
		<div class="quicklinks">
			<a href="/download/">Download</a> | <a href="/documentation/">Documentation</a> | <a href="/forums/">Forums</a>
	<div class="contentwrap">@mw_content@</div>
	<div class="footerwrap">&copy; 2010 CubicleSoft</div>

You will note that I opted to make the header and footer completely static instead of using widgets. The only issue that this approach has is that the copyright date in the footer will not automatically "update" when the next year rolls around. Although, technically, updating a copyright every single year automatically may not be legal unless a record is kept and the year is also not really required. If you want things like years to automatically update, use Javascript and let the client's web browser fill in the blanks. Always look for a Javascript solution first, then a dynamic server-side solution after that so that your website can leverage the caching system effectively.

A few things of interest exist in the above layout. Lines that start with the following strings have special meaning and must appear in the exact order provided:

This approach allows the layout to be previewed outside of the CMS and can be used for other things too with a little parsing in PHP. For instance, I use this Layout in conjunction the site forum - the forum is separate from the main website but is carefully themed to look like it is a part of the website using a plugin I wrote for the forum.

The final line of interest is @mw_content@. The parser for the Layout widget looks for @mw_...@ between the #start and #end tokens of a layout. This tells the Layout widget to place a master widget at that location on the page with the name of the master widget being defined by the '...' portion. This website's primary layout only has one master widget placement called 'content' and is intended for the main page content to placed at that location.

How many widgets do you really need for a header or footer anyway? Probably no more than one. The Layout widget also supports what are known as "one widget only master widgets". If you create a widget, for example, with an internal name called 'site_header', you can insert it into the layout by using @mw_$site_header@. The @mw_$...@ format tells the Layout widget to create a master widget that has exactly one widget and also create a widget in the master widget that matches the specified widget name after the '$' symbol and before the '@'. The standard master widget controls do not display when using this feature so it becomes possible to avoid messing up the design in the preview area.

Once the main layout has been designed and the site more or less built, there is one more feature of the Layout widget called Cache Profiles that can be used. A cache profile is cached content for a specific view of the page. Most websites that want to reach the widest possible audience will cater to a very large screen with a full feature set (desktop), a tiny screen with reduced features (mobile phones), and sometimes devices that are between the two (e.g. tablets). The first layout in a Layout widget is the default cache profile and almost always targets the desktop experience. See the Creating Cache Profiles documentation to learn how to add other profile types to the Layout widget.

Known Quirks/Bugs

Since the Layout widget also uses the Code Editor, it inherits all of the quirks and bugs of that reusable component. There are also a few other issues to take note of:

Special Tokens

The special tokens/strings #edit, #start, #end, #profile, and @mw_ should not appear anywhere in the HTML for the layout but the appropriate locations. If these appear elsewhere, the parser can be thrown off and who knows what could happen. Also, keep @mw_ names simple and don't forget the end @ symbol.

The parser is rather simple in nature and assumes that the web designers and programmers can be trusted to not break things intentionally. It is best to not activate a layout until it is completely built. Layouts can be tested in the browser by going to 'widgets/bb_layout/layouts/YourLayout.html'.

Deactivating/Changing Layouts

When deactivating or changing a layout, the master widgets that no longer are relevant are detached. When changing the active layout, master widgets of the same name are attached if they already exist.

Master widgets usually contain widgets. To get at the widgets inside a master widget to attach them to a new layout, you have to delete the detached/orphaned master widget. What this does is orphan the widgets contained in the master widget thus allowing you to attach them elsewhere. Widgets are not considered orphaned until the parent master widget is permanently removed from the picture.

This approach is a little odd but it does allow for layouts to be swapped on the fly. Some website owners like to change the layout of the homepage for special occasions (e.g. various holidays).

Static Content

The Layout widget is designed solely for wireframe layouts. Wireframes do not change and therefore any content contained within is static. If you need dynamic content, first try to solve the problem using Javascript. If that won't work, place a master widget on the page using @mw_...@ and go from there with a widget.

Note that the Layout widget isn't necessarily the best solution to all problems involving layout. You may end up needing to do something entirely different where you build a custom widget that manages the layout for the site you are building. However, it is theoretically possible to build any website using the three default widgets - including the Layout widget.

© CubicleSoft