If an existing CKEditor plugin isn't available that meets your needs, another alternative that may be suitable is to create a custom button.
What can custom buttons do?
Custom buttons allow you to create blocks of HTML that are inserted by clicking a button on the editor toolbar. The blocks you create can accept content that users can enter.
Custom buttons don't have the capabilities of a full CKEditor plugin - they can't be dynamic or use Javascript, for example. But for formatting text the user enters, a custom button may be the best choice.
Note: although custom buttons tend to be simple, we recommend you have knowledge of HTML, or seek assistance from our peer-to-peer forums.
Creating a custom button
To create a custom button, navigate to Customization -> Editor -> Toolbars. Click the Add Button button in the header, and then the Custom tab. The form you see has the following fields:
-
Button title
The title seen by users when they hover over the button in the editor -
Icon
A small image file that will act at the button icon on the editor. For retina support, upload an icon twice as big as you'd like it to display; it will be resized down by the browser and therefore show high-res. -
Type
Three types of content are supported, and they roughly mimic the three types of element display in HTML:- Inline - used when the inserted HTML exists somewhere in a line of text. Does not create a new line for the content.
- Single line block - designed for single lines (e.g. headers), and puts the block on a new line
- Block - used for multiple lines, and puts the block on a new line
-
Use option
A custom button can optionally accept a value from the user (aside from what they can type as normal inside the block itself). This option will appear as a popup dialog when the user clicks the button in the editor, and the value they enter is passed into the block when it is rendered. With this field enabled, you'll see an additional setting: -
Option label
The text shown to the user requesting a value for the option. -
HTML
The actual HTML the button will render in the editor when used. Generally, any HTML is supported but it must be valid. Within this HTML, a couple of special tags can be used:-
{option}
If the option is used, this tag is replaced with the value the user entered, as-is. -
{content}
If your button will allow the user to type within the generated HTML, insert this tag where the user should be able to type.
-
{option}
Click the Save button to create the button. Your icon will be shown on the Buttons Not On Editor toolbar, and from here you can drag it to your live toolbars and configure it as normal.
Using custom styles
We don't recommend using inline styles in your HTML, because it will be almost impossible for you to update later (posts are built at save-time, not display-time, so if you update a custom button, old posts won't reflect those changes).
Instead, we suggest using classnames, and adding styles for those classnames in your custom.css theme file. This way, you can update the styles later, and old posts will also reflect the changes.
An example
Within this documentation we have tip boxes like this:
This is a tip
This is a custom editor button we've created that is available to staff. Here's the configuration we used to create this button:
-
Button title
Tip -
Icon
-
Type
Block -
Use option
No -
HTML
<div class='docsBox docsBox_tip'> <div class='docsBox_header'>Tip</div> <div class='docsBox_body'> <div class='ipsType_richText ipsType_break ipsContained'> {content} </div> </div> </div>
We then add these styles to our custom.css CSS file:
.docsBox_header {
padding: 5px 10px;
color: #fff;
font-weight: 500;
font-size: 15px;
}
.docsBox_body {
padding: 10px;
font-size: 13px;
line-height: 1.4;
}
.docsBox_tip .docsBox_header {
background: #2E7D32;
}
.docsBox_tip .docsBox_body {
background: #E8F5E9;
}
.docsBox_tip .docsBox_body .ipsType_richText {
color: #1B5E20;
}
Report Guide