Editable Regions enable you to visually edit content in your source HTML in place on your output HTML.
Editable Regions are HTML elements that you define as editable. Define broad sections to provide flexibility, or define separate regions to retain fine control over images and text elements. Editable Regions display yellow borders in the Visual Editorto indicate areas that can be updated.
Depending on the element an editable is applied to, editors see different options in the editor. There are four types available for editing content in place:
To define an Editable Region:
class="editable"
to the HTML element, or append editable
to class
if the attribute is already definedJavaScript is supported the Visual Editor. However, HTML rendered with JavaScript on page load is not editable.
Editable Regions are configured with text
, block
and content
keys inside the _editables
configuration, or with the data-cms-options
attribute on an element.
_editables:
text:
italic: true
block:
format: p h3
undo: true
redo: true
content:
blockquote: true
bold: true
format: p h1 h2 h3 h4 h5 h6 pre address div
italic: true
strike: true
subscript: true
superscript: true
underline: true
bulletedlist: true
indent: true
numberedlist: true
outdent: true
code: true
embed: true
horizontalrule: true
image: true
table: true
undo: true
redo: true
removeformat: true
copyformatting: true
styles: /css/editor.css
left: align-left
center: align-center
right: align-right
justify: align-justify
image_size_attributes: true
{
"_editables": {
"text": {
"italic": true
},
"block": {
"format": "p h3",
"undo": true,
"redo": true
},
"content": {
"blockquote": true,
"bold": true,
"format": "p h1 h2 h3 h4 h5 h6 pre address div",
"italic": true,
"strike": true,
"subscript": true,
"superscript": true,
"underline": true,
"bulletedlist": true,
"indent": true,
"numberedlist": true,
"outdent": true,
"code": true,
"embed": true,
"horizontalrule": true,
"image": true,
"table": true,
"undo": true,
"redo": true,
"removeformat": true,
"copyformatting": true,
"styles": "/css/editor.css",
"left": "align-left",
"center": "align-center",
"right": "align-right",
"justify": "align-justify"
}
}
}
module.exports = {
_editables: {
text: {
italic: true
},
block: {
format: 'p h3',
undo: true,
redo: true
},
content: {
blockquote: true,
bold: true,
format: 'p h1 h2 h3 h4 h5 h6 pre address div',
italic: true,
strike: true,
subscript: true,
superscript: true,
underline: true,
bulletedlist: true,
indent: true,
numberedlist: true,
outdent: true,
code: true,
embed: true,
horizontalrule: true,
image: true,
table: true,
undo: true,
redo: true,
removeformat: true,
copyformatting: true,
styles: '/css/editor.css',
left: 'align-left',
center: 'align-center',
right: 'align-right',
justify: 'align-justify'
}
}
};
Although this is example sets the options globally, you can set this on different scopes in the configuration cascade.
<p data-cms-options='{"bold": true, "italic": true}'
class="editable"></p>
Options for base text formatting.
blockquote
- Boolean
Enables a control to wrap blocks of text in block quotes (unavailable for _editables.text
).
bold
- Boolean
Enables a control to set selected text to bold.
format
- String
Enables a drop down menu for structured text. Has options for p
, h1
, h2
, h3
, h4
, h5
, h6
, pre
, address
, and div
. Set as space separated options, e.g. format: p h1 h2
(unavailable for _editables.text
).
italic
- Boolean
Enables a control to italicize selected text.
strike
- Boolean
Enables a control to strike selected text.
subscript
- Boolean
Enables a control to set selected text to subscript.
superscript
- Boolean
Enables a control to set selected text to superscript.
underline
- Boolean
Enables a control to underline selected text.
link
- Boolean
Enables a control to create hyperlinks around selected text.
Options for managing text in lists and nested lists.
bulletedlist
- Boolean
Enables a control to insert an unordered list, or to convert selected blocks of text into a unordered list (unavailable for _editables.text
).
indent
- Boolean
Enables a control to increase indentation for numbered and unordered lists (unavailable for _editables.text
).
numberedlist
- Boolean
Enables a control to insert a numbered list, or to convert selected blocks of text into a numbered list (unavailable for _editables.text
).
outdent
- Boolean
Enables a control to reduce indentation for numbered and unordered lists (unavailable for _editables.text
).
Options for adding media and full-width content elements.
code
- Boolean
Enables a control to set selected text to inline code, and unselected blocks of text to code blocks (unavailable for _editables.text
).
embed
- Boolean
Enables a control to insert a region of raw HTML, including YouTube, Vimeo, Tweets, and other media. Embedded content is sanitized to mitigate XSS risks, which includes removing style
tags. Embeds containing script
tags are not loaded in the editor (unavailable for _editables.text
).
horizontalrule
- Boolean
Enables a control to insert a horizontal rule (unavailable for _editables.text
).
image
- Boolean
Enables a control to insert an image. The image can be uploaded, existing or an external link (unavailable for _editables.text
).
table
- Boolean
Enables a control to insert a table. Further options for table cells are available in the context menu for cells within the editor (unavailable for _editables.text
).
Options for images when enabled.
image_size_attributes
- Boolean
Instructs the editor to save width
and height
on the image elements added to this editable. This can prevent pop-in as a page loads. Defaults to true
.
width
- Integer
Defines the width of the bounding box used in the resizing process defined with resize_style
.
height
- Integer
Defines the height of the bounding box used in the resizing process defined with resize_style
.
resize_style
- String
Sets how uploaded image files are resized with a bounding box defined by width
and height
prior to upload. Defaults to contain
. Must be contain
, cover
or stretch
:
cover
keeps aspect ratio and ensures the image covers the bounding boxcontain
keeps aspect ratio and ensures the image fits inside the bounding boxstretch
ignores aspect ratio and resizes the image to the bounding boxHas no effect when selecting existing images, or if width
and height
are not set.
mime_type
- String
Sets what format the image is converted to prior to upload. The extension of the file is updated to match. Defaults to keeping the mime type of the uploaded file. Must be one of image/jpeg
or image/png
.
expandable
- Boolean
Controls whether or not images can be upscaled to fit the bounding box during resize prior to upload. Defaults to false
. Has no effect if files are not resized.
correct_orientation
- Boolean
Controls whether or not the JPEG headers defining how an image should be rotated before being displayed is baked into the image prior to upload. Defaults to true
.
Options for editor actions when editing and formatting content.
undo
- Boolean
Enables a control to undo recent edits. Undo is always enabled through standard OS-specific keyboard shortcuts.
redo
- Boolean
Enables a control to redo recent edits undone with undo
. Redo is always enabled through standard OS-specific keyboard shortcuts.
removeformat
- Boolean
Enables the control to remove formatting from text. Applies to formatting from bold
, italic
, underline
, strike
, subscript
, and superscript
. Does not remove other styles or formatting.
copyformatting
- Boolean
Enables a control to copy formatting from text to other text. Only applies to formatting from bold
, italic
, underline
, strike
, subscript
, and superscript
. Does not copy other styles or formatting.
Add predefined styles in plain CSS for your clients and team members to use in the Visual Editor and Content Editor.
styles
- String
Enables a drop down menu for editors to style selected text or blocks or text. Styles are the combination of an element and class name. The value for this option is the path (either source or build output) to the CSS file containing the styles (unavailable for _editables.text
).
left
- String
Enables a control to left align text by toggling a class name for a block of text. The value is the class name the editor should add to align the text. The styles for this class need to be listed in the styles
file to take effect outside of the Visual Editor (unavailable for _editables.text
).
center
- String
Enables a control to center align text by toggling a class name for a block of text. The value is the class name the editor should add to align the text. The styles for this class need to be listed in the styles
file to take effect outside of the Visual Editor (unavailable for _editables.text
).
right
- String
Enables a control to right align text by toggling a class name for a block of text. The value is the class name the editor should add to align the text. The styles for this class need to be listed in the styles
file to take effect outside of the Visual Editor (unavailable for _editables.text
).
justify
- String
Enables a control to justify text by toggling a class name for a block of text. The value is the class name the editor should add to justify the text. The styles for this class need to be listed in the styles
file to take effect outside of the Visual Editor (unavailable for _editables.text
).
The styles
CSS file can be either a source or output file. The source CSS file is used if both exist. In either case, it must contain plain CSS.
Selectors must specify an element and one class in order to be included in the styles drop down. Styles with incompatible selectors are applied to the editor, but not shown as options.
The alignment classes for left
, right
, center
and justify
must be defined in the styles
CSS file to give the editor access to those styles.
/* Can be applied to blocks of content */
p.callout {
margin: 10px;
border: 1px solid #f5f5f5;
background-color: #eee;
}
/* Can be applied to inline content */
span.big-blue-text {
font-size: 2rem;
color: blue;
}
/* Applied to content, excluded from style dropdown */
h2 {
font-family: cursive;
}
/* Applied to content, excluded from style dropdown */
.align-left { text-align: left; }
.align-center { text-align: center; }
.align-right { text-align: right; }
.align-justify { text-align: justify; }
Custom styles in the Visual Editor require the same styles on your live site. If you don’t have the same styles on your live site, the class will be there but it won’t change the styling.