Content Layouts

LiveWhale CMS 2.0+ adds new tools for managing the page editing experience.

Sometimes you want to allow editors to insert design elements onto a page without either coding them into the page template or making them each as separate widgets. This new tool, Content Layouts, allows you to define editable layouts that can be placed on any page.

Creating a content layout

For each content layout you want to add to your site, upload to /_ingredients/templates/wysiwyg:

/_ingredients/templates/wysiwyg/wysiwyg.my-template.xml
an .xml file that contains the markup for your layout, described below

/_ingredients/templates/wysiwyg/wysiwyg.my-template.png
and a .png screenshot of the element that editors will see as a Preview (optional)

Content layout syntax guide

Basic Template

The basic structure of /_ingredients/templates/wysiwyg/wysiwyg.my-template.xml is:

1
2
3
4
5
6
7
<widget type="template">
<title>My Content Layout</title>
<description>Short description of this layout.</description>
<content>
HTML markup goes here.
</content>
</widget>

Inside <content>, a number of special markup elements are supported.

Editable and non-editable areas

We use the TinyMCE Noneditable plugin to allow editable and non-editable regions within a content layout. By default, every element is editable unless it or one of its parents contains class="mceNonEditable"

1
<div class="mceNonEditable">This text can't be edited.</div>
1
2
3
4
<div class="mceNonEditable">
This text can't be edited.
<div class="mceEditable">This text can be edited.</div>
</div>

Best practice: Put class="mceNonEditable" on the outermost element of your content layout, and then only add class="mceEditable" to children that you want editors to be able to type into.

Suggestion: Use class="mceEditable" on block-level elements like <div>, don’t put it directly on header or paragraph elements. Sometimes when editors are typing or hitting return, the current header/paragraph can get duplicated.

Layout blocks

A layout block is a repeatable design element that you want editors to be able to add/remove/rearrange instances of within a single content layout. For instance, in a grid design, your layout block might be a single grid element, so editors can add/delete them as they work.

1
<div class="lw_layout_block">This markup can be duplicated.</div>

When editing a page, these blocks will get + (duplicate) and x (delete) buttons added to them, as well as arrow buttons for rearranging the order.

1
2
3
4
<div class="two-column-grid">
<div class="column lw_layout_block"><!-- etc --></div>
<div class="column lw_layout_block"><!-- etc --></div>
</div>

Note: In order for the duplicate and delete buttons to work as expected, the lw_layout_block class cannot be attached to the outermost element of your markup.

1
2
3
4
5
6
7
8
9
10
11
12
13
<!-- Incorrect: .lw_layout_block on the outermost element will cause unexpected behavior -->
<div class="lw_layout_block mceNonEditable row">
<div class="mceEditable column">Column 1</div>
<div class="mceEditable column">Column 2</div>
</div>

<!-- Correct: .lw_layout_block has a container around it -->
<div class="mceNonEditable">
<div class="lw_layout_block row">
<div class="mceEditable column">Column 1</div>
<div class="mceEditable column">Column 2</div>
</div>
</div>

Currently class="lw_layout_block" is only supported on the <div> HTML element.

Inside a content layout or layout block, you can add data-lw-placeholder to dictate paragraphs, headers, or links that will appear empty on the front-end but will receive placeholder text when editing.

Use data-lw-placeholder="true" for a default “Add text” placeholder.
Use data-lw-placeholder="Add program description" to define custom placeholder text.

1
2
<h3 data-lw-placeholder="true"/>
<p data-lw-placeholder="true"/>

The placeholder attribute also works on links. When an editor clicks the placeholder, the Add Link window will pop up.

1
<a class="my-custom-button" data-lw-placeholder="true"/>

Placeholder images

To add a placeholder image to a content layout, use the following syntax, defining the width and height of the image you want. When an editor clicks the placeholder, the Add Image window will pop up, and the image size/cropping tools will be locked to the dimensions defined in the template:

1
<div class="lw_layout_image" data-width="400" data-height="300"/>

Putting it all together

Here’s a complete example that combines all of the above tools to code a three-column content layout. All of the cta classes are examples that you could replace with your own theme classes.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
<widget type="template">
<title>Graphic Call to Action</title>
<description>This layout displays three columns with graphic, header, and text.</description>
<content>
<div class="cta-wrapper mceNonEditable">

<div class="cta lw_layout_block">
<div class="cta-image mceEditable">
<div class="lw_layout_image" data-width="300" data-height="300"/>
</div>
<div class="cta-header mceEditable">
<h4 data-lw-placeholder="Add marketing headline"/>
</div>
<div class="cta-body mceEditable">
<p data-lw-placeholder="true"/>
<a class="cta-button" data-lw-placeholder="true"/>
</div>
</div>

<div class="cta lw_layout_block">
<div class="cta-image mceEditable">
<div class="lw_layout_image" data-width="300" data-height="300"/>
</div>
<div class="cta-header mceEditable">
<h4 data-lw-placeholder="Add marketing headline"/>
</div>
<div class="cta-body mceEditable">
<p data-lw-placeholder="true"/>
<a class="cta-button" data-lw-placeholder="true"/>
</div>
</div>

<div class="cta lw_layout_block">
<div class="cta-image mceEditable">
<div class="lw_layout_image" data-width="300" data-height="300"/>
</div>
<div class="cta-header mceEditable">
<h4 data-lw-placeholder="Add marketing headline"/>
</div>
<div class="cta-body mceEditable">
<p data-lw-placeholder="true"/>
<a class="cta-button" data-lw-placeholder="true"/>
</div>
</div>

</div>
</content>
</widget>