# Core widgets
Apostrophe comes with some content widgets you can use in areas right away. See below for their descriptions and options.
Common name/label | Widget reference | What is it? |
---|---|---|
Rich text | @apostrophecms/rich-text | A space to enter text and allow formatting (e.g., bolding, links) |
Image | @apostrophecms/image | A single image supporting alt text and responsive behavior |
Video | @apostrophecms/video | Embed a video from most video hosts by entering its URL |
Raw HTML | @apostrophecms/html | Allow entering HTML directly (see security notes below) |
# Rich text widget
The rich text widget provides a space for entering and editing formatted text. Editors can update its content directly in-context.
There are many text formatting features that you can configure for rich text widgets. These editor options are configured in two widget options: toolbar
and styles
. Add these to the widget configuration object when adding an area field.
// modules/@apostrophecms/home-page/index.js
// In area field configuration options
widgets: {
'@apostrophecms/rich-text': {
// 👇 Toolbar configuration
toolbar: ['styles', 'bold', 'italic'],
// 👇 Styles configuration
styles: [
{
tag: 'p',
label: 'Paragraph (P)'
},
{
tag: 'h2',
label: 'Heading 2 (H2)'
}
]
}
}
# Configuring the toolbar
To add formatting tools to the rich text toolbar, add their names to the toolbar
array. The available formatting options include:
Tool name | What is it? |
---|---|
'styles' | A list of text styles, allowing different HTML tags and CSS classes (see "Configuring text styles" below) |
'bold' | Bold text |
'italic' | Italicize text |
'strike' | Strikethrough text |
'link' | Add a link |
'horizontalRule' | Add a visual horizontal rule |
'bulletList' | Bulleted list |
'orderedList' | Numbered list |
'blockquote' | Block quote |
'codeBlock' | Code block |
'alignLeft' | Text Align Left |
'alignCenter' | Text Align Center |
'alignRight' | Text Align Right |
'alignJustify' | Text Align Justify |
'undo' | Undo the last change |
'redo' | Redo the last undone change |
'|' | Add a visual separator to the toolbar (not a formatting action) |
# Configuring text styles
When you add the 'styles'
formatting tool, you can configure an array of text styles. These must include an HTML tag and a label for the menu interface. They may also include a CSS class.
A single style including class might look like:
{
label: 'Centered heading',
tag: 'h2',
class: 'centered'
}
You can use the same tag in several styles with various CSS classes.
NOTE
Including a class with a style will not automatically apply any styles. You still need to write your own CSS for the class.
# Default rich text configuration
{
toolbar: [
'styles',
'bold',
'italic',
'strike',
'link',
'bulletList',
'orderedList',
'blockquote'
],
styles: [
{
tag: 'p',
label: 'Paragraph (P)'
},
{
tag: 'h2',
label: 'Heading 2 (H2)'
},
{
tag: 'h3',
label: 'Heading 3 (H3)'
},
{
tag: 'h4',
label: 'Heading 4 (H4)'
}
]
},
You can configure only one of the two sections (toolbar
or styles
), and use the default configuration for the other.
You can also set your own default rich text options. Avoid adding the same options repeatedly by configuring configure these options on the @apostrophecms/rich-text-widget
module.
// modules/@apostrophecms/rich-text-widget/index.js
module.exports = {
options: {
defaultOptions: {
toolbar: [
// Your default formatting tools
],
styles: [
// Your own default styles
]
}
}
}
# Image widget
The image widget supports displaying a single image including its alt text. It also uses the image variants that Apostrophe generates to responsively load image files based on the active viewport width.
// modules/@apostrophecms/home-page/index.js
// In area field configuration options
widgets: {
'@apostrophecms/image': {}
}
# Specifying a minimum size
You can specify a minimum size for any image widget:
// modules/@apostrophecms/home-page/index.js
// In area field configuration options
widgets: {
'@apostrophecms/image': {
minSize: [ 1000, 600 ]
}
}
This widget won't allow the editor to select any image under 1000 pixels wide, or under 600 pixels tall. In addition, editors won't be able to crop the image smaller than that after selecting it for that particular widget.
# Specifying an aspect ratio
You can specify a minimum size for any image widget:
// modules/@apostrophecms/home-page/index.js
// In area field configuration options
widgets: {
'@apostrophecms/image': {
aspectRatio: [ 3, 2 ]
}
}
In some designs, especially slideshow experiences involving multiple images, allowing images with different aspect ratios just doesn't look good. For these cases, you can set an appropriate aspect ratio.
When you set an aspect ratio, editors can still select differently shaped images. However, if they save that selection without manually cropping it, the image is automatically cropped to match the ratio you set. If the editor does choose to manually crop it, the cropping interface ensures the aspect ratio you chose remains in effect.
# Taking advantage of the "focal point" feature
A fixed ratio for all devices doesn't work for all designs. If your responsive design features custom CSS with different ratios at different breakpoints, consider encouraging editors to use the focal point feature as an alternative to setting minSize
. The image widget emits CSS that biases the browser toward ensuring that the editor's chosen focal point remains visible, regardless of device.
# Customizing responsive image sizes
The image widget's default srcset
attribute for responsive behavior assumes the image is roughly the same width as the viewport. This will help reduce download times even if the display size is smaller, but you can make responsive loading more accurate by providing the sizes
attribute (opens new window) value.
This configuration is applied as a template option. In the template's area
tag, include a sizes
context option for the image widget. The option value should be the actual HTML attribute value.
{% area data.page, 'main' with {
'@apostrophecms/image': {
sizes: '(min-width: 600px) 45vw, (min-width: 1140px) 530px'
}
} %}
See below for the image variant sizes that Apostrophe generates by default.
# Specifying the fallback size
Most browsers will use the responsive srcset
attribute to find the right image file to display. Older browsers may need the static src
attribute value. By default Apostrophe uses the full
image variant, no larger than 1140px
by 1140px, for the src
value.
You can change this in the area field widget options, using another image size name.
// modules/@apostrophecms/home-page/index.js
// In area field configuration options
widgets: {
'@apostrophecms/image': {
size: 'one-half'
}
}
The sizes available by default are:
Name | Maximum width | Maximum height |
---|---|---|
max | 1600px | 1600px |
full | 1140px | 1140px |
two-thirds | 760px | 760px |
one-half | 570px | 700px |
one-third | 380px | 700px |
one-sixth | 190px | 350px |
The final image size name is original
, which delivers the original image file. This should be used carefully since it could be very large and slow to download.
# Video widget
The core video widget accepts a video URL and fetches the embed code to display it. Most major video hosts are supported by default.
# HTML widget
Or: How to get access to the editing interface when embedded HTML breaks it.
The HTML widget allows content editors to embed raw HTML directly into a template. This can be helpful if they may need to add third-party features (e.g., sign-up forms). This can also be very dangerous since there are no limits to what they can add. Bad JavaScript in embedded HTML can break the user interface, making it impossible to remove the bad code.
Think carefully before providing this widget option to editors and make them aware of the risks.
There is a safety mechanism in case things do go wrong. If embedded HTML breaks the Apostrophe interface, append the query parameter safemode=1
to the end of the URL. The HTML widget will not render its contents and editors will be able to edit it to remove or fix the embed.
https://example.net/broken-page?safemode=1
To do that, access the page with ?safemode=1
at the end of the URL. Then you will be able to edit the widget and remove the offending content.
# Setting a CSS class on core widgets
There are two options to set classes on core widgets. You can add a className
option to either the widget module or the widget options in an area field. That value will be added to the outer-most HTML element in core widget templates. If both are set, the className
property on the area configuration will be used.
Configuring on the module widget level:
// app.js
require('apostrophe') {
modules: {
'@apostrophecms/video-widget': {
options: {
className: 'project-video-class'
}
}
}
};
Configuring on the area field widget options:
// modules/@apostrophecms/home-page/index.js
module.exports = {
fields: {
add: {
main: {
type: 'area',
options: {
widgets: {
'@apostrophecms/video': {
className: 'area-video-class'
}
}
}
}
},
// ...
}
};