13. Customizing Volto Components

Volto chapter

Volto Logo

This chapter is about the React frontend Volto.

Solve the same tasks in Plone Classic in chapter Customizing Existing Templates

Get the code! (More info)

Code for the beginning of this chapter:

git checkout initial

Code for the end of this chapter:

git checkout overrides

In this part you will:

  • Find out how news items are displayed

  • Customize existing components

Topics covered:

  • Customize existing views with Component Shadowing

  • Content Type Views

  • Listing Views

  • Blocks

13.1. Component shadowing

We use a technique called component shadowing to override an existing Volto component with our local custom version, without having to modify Volto’s source code at all. You have to place the replacing component in the same original folder path inside the src/customizations folder.

Every time you add a file to the customizations folder or to the theme folder, you must restart Volto for changes to take effect. From that point on, the hot reloading should kick in and reload the page automatically.

Note

Component shadowing is very much like the good old Plone technique called “JBOT” (“just a bunch of templates”).

You can customize any module in Volto, including actions and reducers, not only components.

13.4. The News Item View

We want to show the date a News Item is published. This way visitors can see at a glance if they are looking at current or old news.

This information is not shown by default. So you will need to customize the way that is used to render News Items.

The Volto component to render a News Item is in omelette/src/components/theme/View/NewsItemView.jsx (remember chapter Volto Basics?).

/**
 * NewsItemView view component.
 * @module components/theme/View/NewsItemView
 */

import React from 'react';
import PropTypes from 'prop-types';
import { Container, Image } from 'semantic-ui-react';

import { flattenToAppURL, flattenHTMLToAppURL } from '@plone/volto/helpers';

/**
 * NewsItemView view component class.
 * @function NewsItemView
 * @params {object} content Content object.
 * @returns {string} Markup of the component.
 */
const NewsItemView = ({ content }) => (
  <Container className="view-wrapper">
    {content.title && (
      <h1 className="documentFirstHeading">
        {content.title}
        {content.subtitle && ` - ${content.subtitle}`}
      </h1>
    )}
    {content.description && (
      <p className="documentDescription">{content.description}</p>
    )}
    {content.image && (
      <Image
        className="documentImage"
        alt={content.title}
        title={content.title}
        src={
          content.image['content-type'] === 'image/svg+xml'
            ? flattenToAppURL(content.image.download)
            : flattenToAppURL(content.image.scales.mini.download)
        }
        floated="right"
      />
    )}
    {content.text && (
      <div
        dangerouslySetInnerHTML={{
          __html: flattenHTMLToAppURL(content.text.data),
        }}
      />
    )}
  </Container>
);

/**
 * Property types.
 * @property {Object} propTypes Property types.
 * @static
 */
NewsItemView.propTypes = {
  content: PropTypes.shape({
    title: PropTypes.string,
    description: PropTypes.string,
    text: PropTypes.shape({
      data: PropTypes.string,
    }),
  }).isRequired,
};

export default NewsItemView;

Note

  • content is passed to NewsItemView and represents the content item as it is seriaized by the restapi

  • The view displays various attributes of the News Item using content.title, content.description or content.text.data

  • You can inspect all data that content holds using the React Developer Tools for Firefox or Chrome:

    ../_images/volto_react_devtools.png

Copy that file into src/customizations/components/theme/View/NewsItemView.jsx.

After restarting Volto the new file is used when diplaying a News Item. To make sure your file is used add a small change before or after the text. If it shows up you’re good to go.

In you own projects you shoud always do a commit of the unchanged file and another commit after you changed the file. This way you will have a commit in your git-history with the change you made. You will thank yourself later for that clean diff!

To display the date add the following before the text:

<p>{content.created}</p>

This will render something like 2020-10-19T10:51:21. Not very user friendly. Let’s use one of many helpers available in React.

Import the library moment at the top of the file and use it to format the date in a readable format.

/**
 * NewsItemView view component.
 * @module components/theme/View/NewsItemView
 */

import React from 'react';
import PropTypes from 'prop-types';
import { Container, Image } from 'semantic-ui-react';
import moment from 'moment';

import { flattenToAppURL, flattenHTMLToAppURL } from '@plone/volto/helpers';

/**
 * NewsItemView view component class.
 * @function NewsItemView
 * @params {object} content Content object.
 * @returns {string} Markup of the component.
 */

const NewsItemView = ({ content }) => (
  <Container className="view-wrapper">
    {content.title && (
      <h1 className="documentFirstHeading">
        {content.title}
        {content.subtitle && ` - ${content.subtitle}`}
      </h1>
    )}
    {content.description && (
      <p className="documentDescription">{content.description}</p>
    )}
    {content.image && (
      <Image
        className="documentImage"
        alt={content.title}
        title={content.title}
        src={
          content.image['content-type'] === 'image/svg+xml'
            ? flattenToAppURL(content.image.download)
            : flattenToAppURL(content.image.scales.mini.download)
        }
        floated="right"
      />
    )}
    <p>{moment(content.created).format('ll')}</p>
    {content.text && (
      <div
        dangerouslySetInnerHTML={{
          __html: flattenHTMLToAppURL(content.text.data),
        }}
      />
    )}
  </Container>
);

/**
 * Property types.
 * @property {Object} propTypes Property types.
 * @static
 */
NewsItemView.propTypes = {
  content: PropTypes.shape({
    title: PropTypes.string,
    description: PropTypes.string,
    text: PropTypes.shape({
      data: PropTypes.string,
    }),
  }).isRequired,
};

export default NewsItemView;

The result should look like this:

A News Item with publishing date.

Now another issue appears. There are various dates associated with any content object:

  • The date the item is created: content.created

  • The date the item is last modified content.modified

  • The date the item is published content.effective

In fact you most likely want to show the date when the item was published. But while the item is not yet published that value is not yet set and you will get a error. So we’ll add some simple logic to use the effective-date if it exists and the creation-date as a fallback.

<p className="discreet">
  {(content.effective && moment(content.effective).format('ll')) ||
    moment(content.created).format('ll')}
</p>

13.5. The Summary View

The listing of News Items in http://localhost:3000/news does not show any dates as well.

Customize the Summary View component that exists in omelette/src/components/theme/View/SummaryView.jsx.

Copy that file to src/customizations/components/theme/View/SummaryView.jsx and add the following after the description:

<p className="discreet">
  {(item.effective && moment(item.effective).format('ll')) ||
    moment(item.created).format('ll')}
</p>

Don’t forget to add the import of moment: import moment from 'moment'; at the top.

Note how the component iterates over the variable items of content with {content.items.map((item) => (...)}. Here item is the item in the Folder or Collection where this component is used.

13.6. The Listing Block

When you edited the frontpage in Default content types you may have added a Listing block to the frontpage. If not do so now.

You will see that the listing block does not display the date as well.

Copy omelette/src/components/manage/Blocks/Listing/DefaultTemplate.jsx to src/customizations/components/manage/Blocks/Listing/DefaultTemplate.jsx and add the dates as you did with the Summary View.

import React from 'react';
import PropTypes from 'prop-types';
import { ConditionalLink } from '@plone/volto/components';
import { flattenToAppURL } from '@plone/volto/helpers';
import { settings } from '~/config';
import moment from 'moment';

import DefaultImageSVG from '@plone/volto/components/manage/Blocks/Listing/default-image.svg';
import { isInternalURL } from '@plone/volto/helpers/Url/Url';

const DefaultTemplate = ({ items, linkMore, isEditMode }) => {
  let link = null;
  let href = linkMore?.href || '';

  if (isInternalURL(href)) {
    link = (
      <ConditionalLink to={flattenToAppURL(href)} condition={!isEditMode}>
        {linkMore?.title || href}
      </ConditionalLink>
    );
  } else if (href) {
    link = <a href={href}>{linkMore?.title || href}</a>;
  }

  return (
    <>
      <div className="items">
        {items.map((item) => (
          <div className="listing-item" key={item['@id']}>
            <ConditionalLink
              to={flattenToAppURL(item['@id'])}
              condition={!isEditMode}
            >
              {!item[settings.listingPreviewImageField] && (
                <img src={DefaultImageSVG} alt="" />
              )}
              {item[settings.listingPreviewImageField] && (
                <img
                  src={flattenToAppURL(
                    item[settings.listingPreviewImageField].scales.preview
                      .download,
                  )}
                  alt={item.title}
                />
              )}
              <div className="listing-body">
                <h3>{item.title ? item.title : item.id}</h3>
                <p>{item.description}</p>
                <span className="discreet">
                  {(item.effective && moment(item.effective).format('ll')) ||
                    moment(item.created).format('ll')}
                </span>
              </div>
            </ConditionalLink>
          </div>
        ))}
      </div>

      {link && <div className="footer">{link}</div>}
    </>
  );
};

DefaultTemplate.propTypes = {
  items: PropTypes.arrayOf(PropTypes.any).isRequired,
  linkMore: PropTypes.any,
  isEditMode: PropTypes.bool,
};

export default DefaultTemplate;

The result should look like this:

The customized Listing Block.

13.7. Localization

The result is fine if you have an english-speaking website but for other locales you want to configure moment to use your locale. You could set it by hand with moment.locale('fr'); (for french) but the code for this application should work with any language.

NewsItemView contains no code but directly returns the container. You need to make a small change to allow setting the locale here. Wrap the Container with {} and return the container. Put the locale-setting before it.

/**
 * NewsItemView view component.
 * @module components/theme/View/NewsItemView
 */

import React from 'react';
import PropTypes from 'prop-types';
import { Container, Image } from 'semantic-ui-react';
import moment from 'moment';
import { useIntl } from 'react-intl';

import { flattenToAppURL, flattenHTMLToAppURL } from '@plone/volto/helpers';

/**
 * NewsItemView view component class.
 * @function NewsItemView
 * @params {object} content Content object.
 * @returns {string} Markup of the component.
 */

const NewsItemView = ({ content }) => {
  const intl = useIntl();
  moment.locale(intl.locale);

  return (
    <Container className="view-wrapper">
      {content.title && (
        <h1 className="documentFirstHeading">
          {content.title}
          {content.subtitle && ` - ${content.subtitle}`}
        </h1>
      )}
      {content.description && (
        <p className="documentDescription">{content.description}</p>
      )}
      {content.image && (
        <Image
          className="documentImage"
          alt={content.title}
          title={content.title}
          src={
            content.image['content-type'] === 'image/svg+xml'
              ? flattenToAppURL(content.image.download)
              : flattenToAppURL(content.image.scales.mini.download)
          }
          floated="right"
        />
      )}
      <p className="discreet">
        {(content.effective && moment(content.effective).format('lll')) ||
          moment(content.created).format('lll')}
      </p>
      {content.text && (
        <div
          dangerouslySetInnerHTML={{
            __html: flattenHTMLToAppURL(content.text.data),
          }}
        />
      )}
    </Container>
  );
};

/**
 * Property types.
 * @property {Object} propTypes Property types.
 * @static
 */
NewsItemView.propTypes = {
  content: PropTypes.shape({
    title: PropTypes.string,
    description: PropTypes.string,
    text: PropTypes.shape({
      data: PropTypes.string,
    }),
  }).isRequired,
};

export default NewsItemView;

You can now do the same changes for the Summary View and the Listing Block. The Listing Block alread has some code in it so you would not need to wrap it in {} and add the return () statement.

13.8. Summary

  • Component shadowing allows you to modify, extend and customize all modules in Volto.

  • It is a powerful feature for making changes without the need for complex configuration or maintaining a fork of the code.

  • You need to restart Volte when you add a new override.

See also