Settings reference guide#
This is a summary of all the configuration options and what they control.
Note
This list is still incomplete, contributions are welcomed!
Main settings#
They are exposed in config.settings.
additionalToolbarComponents#
The additionalToolbarComponents setting adds additional toolbar menus.
The menu body component needs to be added to the on-demand loaded components, as shown in the following example.
config.settings.additionalToolbarComponents = {
bookmarksMenu: {
component: BookmarksEditorComponent,
wrapper: null,
},
};
Then add the plug, as shown.
<Plug pluggable="main.toolbar.bottom" id="bookmarks-menu">
{({ onClickHandler }) => {
return (
<button
className="show-bookmarks"
aria-label={intl.formatMessage(messages.label_showbookmarksmenu)}
onClick={(e) => onClickHandler(e, 'bookmarksMenu')}
tabIndex={0}
id="toolbar-show-bookmarks"
>
<Icon
name={bookSVG}
size="30px"
title={intl.formatMessage(messages.label_showbookmarksmenu)}
/>
</button>
);
}}
</Plug>
apiExpanders#
You can configure the API expanders in Volto using settings.apiExpanders, as in the following example.
import { GET_CONTENT } from '@plone/volto/constants/ActionTypes';
export default function applyConfig (config) {
config.settings.apiExpanders = [
...config.settings.apiExpanders,
{
match: '',
GET_CONTENT: ['mycustomexpander'],
},
{
match: '/de',
GET_CONTENT: ['myothercustomexpander'],
},
{
match: '/de',
GET_CONTENT: ['navigation'],
querystring: {
'expand.navigation.depth': 3,
},
}
];
return config;
}
If you want Volto to make only a single request, combining all the expanders in it, then configure apiExpanders as shown.
config.settings.apiExpanders = [
{
match: '',
GET_CONTENT: ['breadcrumbs', 'navigation', 'actions', 'types'],
},
];
config accepts a list of matchers to filter by request path and action type for maximum flexibility.
It also accepts a querystring object that allows to configure the expanders via querystring parameters, for example, the navigation expander.
The querystring object accepts a querystring object or a function that returns a querystring object.
The function receives the current config and the current evaluated querystring as parameters, so you can use it to pass dynamic values to the querystring.
export default function applyConfig (config) {
config.settings.apiExpanders = [
...config.settings.apiExpanders,
{
match: '',
GET_CONTENT: ['mycustomexpander'],
},
{
match: '/de',
GET_CONTENT: ['myothercustomexpander'],
},
{
match: '/de',
GET_CONTENT: ['navigation'],
querystring: (config, querystring) => ({
'expand.navigation.depth': config.settings.navDepth,
}),
}
];
return config;
}
This is used to pass current—as in resultant, in place—configuration options to the querystring object.
asyncPropsExtenders#
asyncPropsExtenders is a per-route customizable asyncConnect action dispatcher.
These enable proper server-side rendering of content that depends on additional async props coming from backend calls.
It is a list of route-like configuration objects, which are matched using
matchRoutes.
Instead of the component key, you should provide an extend method with signature asyncItems => asyncItems.
Thus, it receives a list of asyncConnect "prop" objects, and returns a similar list.
You can add new asyncConnected props, as well as remove them.
The following example demonstrates this, excluding the breadcrumbs from being requested.
config.settings.asyncPropsExtenders = [
...config.settings.asyncPropsExtenders,
{
path: '/',
extend: (dispatchActions) => dispatchActions.filter(asyncAction=> asyncAction.key !== 'breadcrumb')
}
]
bbb_getContentFetchesFullobjects#
Before Volto 10, the main content-grabbing request, triggered as a result of getContent action, always used the fullobjects flag, which fully serialized the immediate children of the context request.
If your code depends on this behavior, set the bbb_getContentFetchesFullobjects flag to true in the settings object.
Note
You should probably refactor your code to avoid depending on this behavior. It can cause performance issues when you have large children, for example, content with lots of text, and you need to batch requests anyway, if you want to be sure to display all the children.
blockSettingsTabFieldsetsInitialStateOpen#
blockSettingsTabFieldsetsInitialStateOpen is a boolean, and is true by default.
The fieldsets in the blocks settings tab start as non-collapsed or opened by default.
To collapse or close them, set blockSettingsTabFieldsetsInitialStateOpen to false.
contentIcons#
The contentIcons property configures content types icons.
Those are visible in the contents view, such as "Folder contents".
The default ones are in config/ContentIcons.jsx.
You can extend them in your project's configuration for custom content types using settings.contentIcons.
In Volto projects, you can configure this for custom content types as shown in the following example.
import * as config from '@plone/volto/config';
import courseSVG from './icons/course.svg';
export const settings = {
...config.settings,
contentIcons: {
...config.settings.contentIcons,
Course: courseSVG,
}
};
controlpanels#
The controlpanels setting registers a component as a control panel.
The following is an example configuration in the config.js file of your project or add-on:
config.settings.controlpanels = [
...config.settings.controlpanels,
{
'@id': '/manage-myaddon-subscriptions',
group: 'Add-on Configuration',
title: 'Breaking News Manage Subscriptions',
},
];
config.addonRoutes = [
...config.addonRoutes,
{
path: '/controlpanel/manage-myaddon-subscriptions',
component: ManageSubscriptions,
},
];
The group can be one of the default groups General, Content, Security, Add-on Configuration, Users and Groups, or a custom group.
cssLayers#
To use CSS layers when styling Volto, you can define and apply them at the very top level of the page, where they appear in the <head> tag.
By using the cssLayers configuration, you can pass the layer list definition as an array, as shown in the following example
config.settings.cssLayers = ['reset', 'plone-components', 'layout', 'addons', 'theme'];
defaultBlockType#
defaultBlockType is the name of the default block type used when a new block is added.
The default value of this setting is slate, which uses the current Slate-based implementation for the rich text editor.
If you change this to a different type of block, make sure the block configuration includes the blockHasValue function.
defaultLanguage#
defaultLanguage sets the default language of the site.
Removed in version Volto: 19
This setting was removed in Volto 19. Instead, the default language is loaded from the backend.
See also
errorHandlers#
errorHandlers is a list of error handlers that will be called when there is an unhandled exception.
Each error handler is a function that receives a single argument, the error object.
externalRoutes#
If another application is published under the same top domain as Volto, externalRoutes lets you configure a route such as /abc which should be not rendered by Volto.
This could be achieved by a rule in the reverse proxy, such as Apache or nginx, but when navigating client side, you may have references to that route.
Volto handles that as an internal URL, and fetching the content will break.
You can disable that path in config.settings.externalRoutes so it will be handled as an external link, as shown in the following example.
config.settings.externalRoutes = [
{
match: {
path: '/news',
exact: false,
strict: false,
},
url(payload) {
return payload.location.pathname;
},
},
];
The foregoing example can be simplified as shown.
config.settings.externalRoutes = [
{ match: "/news" },
{ match: "/events" },
];
filterControlPanelsSchema#
filterControlPanelsSchema is a schema factory for a control panel.
It is used internally, to tweak the schemas provided by the @controlpanels endpoint, making them fit for Volto.
It uses the unwantedControlPanelsFields setting.
hasWorkingCopySupport#
Removed in version Volto: 18.8.0
This setting is unnecessary since Volto 18.8.0.
Working copy support is now based on whether the plone.app.iterate add-on is installed in the backend.
For Plone sites using a Volto version prior to 18.8.0, the hasWorkingCopySupport setting enables working copy support.
See also
See Working copy support for configuration.
initialReducersBlacklist#
The initial state passed from server to browser needs to be minimal to optimize the resultant generated HTML.
This state gets stored in window.__data and received in the client.
You can blacklist a few reducers that you don't want to be part of window.__data, thus decreasing the initial HTML size for performance gains by setting initialReducersBlacklist.
import * as config from '@plone/volto/config';
export const settings = {
...config.settings,
initialReducersBlacklist: [
...config.settings.initialReducersBlacklist,
'yourReducer',
]
};
isMultilingual#
If isMultilingual is true, then features for translating content to multiple languages are available.
Its default value is false.
Removed in version Volto: 19
This setting was removed in Volto 19. Instead, Volto checks whether the backend has multilingual features enabled.
See also
lazyBundles#
lazyBundles is a mapping of bundles to a list of lazy library names.
Create new bundles, or change the already provided cms bundle, to preload multiple lazy libraries with preloadLazyLibs or quickly load them with injectLazyLibs.
loadables#
loadables is a mapping of loadable libraries that can be injected into components using the injectLazyLibs HOC wrapper.
See the Lazy loading page for more details.
maxFileUploadSize#
maxFileUploadSize is the maximum allowed size of file uploads in bytes.
The default is null, meaning no limit is enforced by Volto.
maxResponseSize#
The library that Volto uses to get files and images from the backend called superagent has a response size limit of 200Mb. If you want to get a file bigger than 200Mb from Plone, the SSR will throw an error.
You can edit this limit in the settings object setting a new value for maxResponseSize in bytes.
For example, to set 500Mb, write 5000000000.
okRoute#
The okRoute setting in Volto provides an /ok URL where it responds with a text/plain ok response, with an HTTP 200 status code, to signal third party health check services that the Volto process is running correctly.
Using the okRoute setting, you can modify this URL and configure it to respond with another URL.
The provided default URL matches the existing Plone Classic UI URL.
config.settings.okRoute = '/site-is-ok'
persistentReducers#
persistentReducers is a list of reducer names that should use the browser's local storage to persist their data.
querystringSearchGet#
Volto uses HTTP POST requests to query the @querystring-search endpoint.
This can create a lot of traffic between Volto and the backend, and can also create a lot of cache misses.
By setting the querystringSearchGet configuration to true, the endpoint queries will be executed as HTTP GET requests.
Thus, any proxy cache between Volto and the backend may cache those queries, improving your site performance.
Please be aware that this could break some other functionality in your site, or some of your queries may break, when they contain more than 2000 characters. See an explanation of character limits in URLs. Please test this setting properly before enabling in a production site.
sentryOptions#
In Volto 16.0.0.alpha.45, Sentry integration via sentryOptions was moved from core to the add-on @plone-collective/volto-sentry.
See also
siteTitleFormat#
The siteTitleFormat setting in Volto lets you modify how the site title is built.
By default, the site title only includes the title of the current page.
By modifying the siteTitleFormat configuration setting, you can decide whether to use the title of the navigation root, either the site root or the language root folder, as the second part of the title.
You can also choose the separator character between the current page title and the site title, as shown in the following example.
siteTitleFormat: {
includeSiteTitle: true,
titleAndSiteTitleSeparator: '-',
}
storeExtenders#
storeExtenders is a list of callables with signature (middlewaresList) => middlewaresList.
These callables receive the whole stack of middlewares used in Volto and they can add new middleware or tweak this list.
styleClassNameConverters#
styleClassNameConverters is an object with functions used by the style wrapper helpers to convert style data to actual class names.
You can customize the generated class name by registering field names with names, such as <fieldname>:<converterName>, where the converter is registered here.
styleClassNameExtenders#
styleClassNameExtenders is an array containing functions that extend how the StyleWrapper builds a list of styles.
These functions have the signature ({ block, content, data, classNames }) => classNames.
The following examples show useful functions. For simplicity, they're compacted into one extender.
import { getPreviousNextBlock } from '@plone/volto/helpers';
config.settings.styleClassNameExtenders = [
({ block, content, data, classNames }) => {
let styles = [];
const [previousBlock, nextBlock] = getPreviousNextBlock({
content,
block,
});
// Inject a class depending of which type is the next block
if (nextBlock?.['@type']) {
styles.push(`next--is--${nextBlock['@type']}`);
}
// Inject a class depending if previous is the same type of block
if (data?.['@type'] === previousBlock?.['@type']) {
styles.push('previous--is--same--block-type');
}
// Inject a class depending if next is the same type of block
if (data?.['@type'] === nextBlock?.['@type']) {
styles.push('next--is--same--block-type');
}
// Inject a class depending if it's the first of block type
if (data?.['@type'] !== previousBlock?.['@type']) {
styles.push('is--first--of--block-type');
}
// Inject a class depending if it's the last of block type
if (data?.['@type'] !== nextBlock?.['@type']) {
styles.push('is--last--of--block-type');
}
// Given a StyleWrapper defined `backgroundColor` style
const previousColor =
previousBlock?.styles?.backgroundColor ?? 'transparent';
const currentColor = data?.styles?.backgroundColor ?? 'transparent';
const nextColor = nextBlock?.styles?.backgroundColor ?? 'transparent';
// Inject a class depending if the previous block has the same `backgroundColor`
if (currentColor === previousColor) {
styles.push('previous--has--same--backgroundColor');
} else if (currentColor !== previousColor) {
styles.push('previous--has--different--backgroundColor');
}
// Inject a class depending if the next block has the same `backgroundColor`
if (currentColor === nextColor) {
styles.push('next--has--same--backgroundColor');
} else if (currentColor !== nextColor) {
styles.push('next--has--different--backgroundColor');
}
return [...classNames, ...styles];
},
];
supportedLanguages#
supportedLanguages is a list of locales which are included in the bundled code.
unwantedControlPanelsFields#
unwantedControlPanelsFields is the control panel fields that are not used in Volto.
It is used internally by the filterControlPanelsSchema function.
workflowMapping#
workflowMapping is an object that defines the mapping between workflow states or transitions and the color that should show in the change workflow select menu.
The following code is the default.
export const workflowMapping = {
published: { value: 'published', color: '#007bc1' },
publish: { value: 'publish', color: '#007bc1' },
private: { value: 'private', color: '#ed4033' },
pending: { value: 'pending', color: '#f6a808' },
send_back: { value: 'private', color: '#ed4033' },
retract: { value: 'private', color: '#ed4033' },
reject: { value: 'private', color: '#ed4033' },
submit: { value: 'review', color: '#f4e037' },
};
It's meant to be extended with your own workflows or transitions. It's recommended to assign the same color to the transition as the destination state, so the user can have the visual hint to which state are they transitioning.
Views settings#
The view settings are exposed in config.views, as described in the following setting.
layoutViewsNamesMapping#
Plone's layout views are identified by a simple string.
The layoutViewsNamesMapping object maps this string with a nice literal, in English by default.
These view names are exposed in the Display component in the toolbar's more menu.
The keys of layoutViewsNamesMapping are the name of the Plone layout, and the values are the i18n string id, as shown in the following example.
export const layoutViewsNamesMapping = {
album_view: 'Album view',
event_listing: 'Event listing',
full_view: 'All content',
listing_view: 'Listing view',
summary_view: 'Summary view',
tabular_view: 'Tabular view',
layout_view: 'Mosaic layout',
document_view: 'Document view',
folder_listing: 'Folder listing',
newsitem_view: 'News item view',
link_redirect_view: 'Link redirect view',
file_view: 'File view',
image_view: 'Image view',
event_view: 'Event view',
view: 'Default view',
};
You can customize this object to add or modify the existing entries.
They are i18n aware, so you can add the corresponding i18n message in your project's src/config.js or your add-on's src/index.js, as shown in the following example.
import { defineMessages } from 'react-intl';
defineMessages({
album_view: {
id: 'Album view',
defaultMessage: 'Album view',
},
})
Server-specific serverConfig#
Settings that are relevant to the Express-powered Volto SSR server are stored
in the config.settings.serverConfig object.
criticalCssPath#
criticalCssPath is path relative to the project root that points to an optional CSS file.
If this file exists, it is loaded, and its content is embedded inline into the
generated HTML.
By default this path is public/critical.css.
See the critical.css (above the fold) optimizations section for more details.
expressMiddleware#
expressMiddleware is a list of Express.js middleware that can extend the built-in functionality of Volto's server.
See the Express section for more details.