Settings reference guide
Contents
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
:
- asyncPropsExtenders#
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 (they are matched using matchRoutes. Instead of thecomponent
key you should provide anextend
method with signatureasyncItems => asyncItems
, so it receives a list of asyncConnect "prop" objects and returns a similar list. You can add new asyncConnected props as well as removing them, so you could, for example, have something like this to exclude 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 thefullobjects
flag, which fully serialized the immediate children of the context request. If your code depends on this behavior, set this flag totrue
in thesettings
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.
- contentIcons#
With this property you can configure Content Types icons. Those are visible in Contents view (ex "Folder contents"). The default ones are in config/ContentIcons.jsx and you can extend them in your project's config for custom content types using
settings.contentIcons
.In Volto projects, you can configure this for custom content types like:
import * as config from '@plone/volto/config'; import courseSVG from './icons/course.svg'; export const settings = { ...config.settings, contentIcons: { ...config.settings.contentIcons, Course: courseSVG, };
- contentMetadataTagsImageField#
The OpenGraph image that will represent this content item, will be used in the metadata HEAD tag as og:image for SEO purposes. Defaults to image. See the OpenGraph Protocol for more details.
- controlpanels#
Register a component as control panel.
Example configuration in
config.js
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.
- defaultBlockType#
The default block type in Volto is "text", which uses the current DraftJS-based implementation for the rich text editor. Future alternative rich text editors will need to use this setting and replace it with their block type. The block definition should also include the
blockHasValue
function, which is needed to activate the Block Chooser functionality. See this function signature in Blocks > Settings.- errorHandlers#
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, you could have a route like
/abc
which should be not rendered by Volto. This can be achieved by a rule in the reverse proxy (Apache or nginx for example) but, when navigating client side, you may have references to that route so Volto is handling that as an internal URL and fetching the content will break. You can disable that path inconfig.settings.externalRoutes
so it will be handled as an external link.config.settings.externalRoutes = [ { match: { path: '/news', exact: false, strict: false, }, url(payload) { return payload.location.pathname; }, }, ];
It can also be simplified as:
config.settings.externalRoutes = [ { match: "/news" }, { match: "/events" }, ];
- filterControlPanelsSchema#
A schema factory for a control panel. It is used internally, to tweak the schemas provided by the controlpanel endpoint, to make them fit for Volto.
- hasWorkingCopySupport#
This setting will enable working copy support in your site. You need to install the
plone.app.iterate
add-on in your Plone site in order to make it working.- initialReducersBlacklist#
The initial state passed from server to browser needs to be minimal in order to optimize the resultant html generated. This state gets stored in
window.__data
and received in 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.import * as config from '@plone/volto/config'; export const settings = { ...config.settings, initialReducersBlacklist: [ ...config.settings.initialReducersBlacklist, 'yourReducer', ] };
- lazyBundles#
A mapping of bundles to list of lazy library names. Create new bundles (or change the already provided
cms
bundle to be able to preload multiple lazy libraries (withpreloadLazyLibs
) or quickly load them withinjectLazyLibs
.- loadables#
A mapping of loadable libraries that can be injected into components using the
injectLazyLibs
HOC wrapper. See the Lazy loading page for more details.- maxResponseSize#
The library that we use to get files and images from the backend (superagent) has a response size limit of 200 mb, so if you want to get a file bigger than 200 mb from Plone, the SSR will throw an error.
You can edit this limit in the
settings
object setting a new value in bytes (for example, to set 500 mb you need to write 5000000000).Navigation levels depth used in the navigation endpoint calls. Increasing this is useful for implementing fat navigation menus. Defaults to
1
.- persistentReducers#
A list of reducer names that should use the browser's localstorage to persist their data.
- sentryOptions#
In Volto 16.0.0.alpha.45, Sentry integration was moved from core to the add-on
@plone-collective/volto-sentry
.See also
- storeExtenders#
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#
An object with functions used by the style wrapper helpers to convert style data to actual class names. You can customize the generated classname by registering fieldnames with names such as
<fieldname>:<converterName>
, where the converter is registered here.- workflowMapping#
It's an object that defines the mapping between workflow states/transitions and the color that should show in the change Workflow dropdown. This 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/transitions. It is 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 to.
Views settings#
They are exposed in config.views
:
- layoutViewsNamesMapping#
Plone's layout views are identified by a simple string. This object maps this string with a nice literal (in English as default). These view names are exposed in the
Display
component in the toolbar's more menu. The keys are the name of the Plone layout, and the values are the i18n stringid
: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'ssrc/index.js
: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#
A 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#
A list of ExpressJs middleware that can extend the built-in functionality of Volto's server. See the Express section for more details.
- extractScripts#
An object that allows you to configure the insertion of scripts on the page in some particular cases. For the moment it admits only one property:
errorPages
whose value is a Boolean.If
extractScripts.errorPages
istrue
, the JS will be inserted into the error page.