Adding an Option to a Widget

Adding an Option to a Widget

As mentioned in the introduction to the Scrivito Example Application, all widget classes are defined in the files contained in subdirectories of the “src/Widgets” directory of your app’s repository. To demonstrate how easy it is to extend widgets, let’s give editors the option to change the background color of headlines.

In the Example App, the HeadlineWidget model class is defined as follows:

The Example App uses Bootstrap for styling. We’re going to stick to the set of colors provided by Bootstrap and offer them to editors as headline background color options.

As you can see from the HeadlineWidget definition above, there are already two attributes for letting editors select one of several values, the level and style attributes. They are attributes of the enum type which enables selecting a single value, or none (as opposed to the multienum type for selecting several values).

Adding functionality or styling options to a widget or page class involves three steps: adding the attribute, making it editable, and rendering its value.

Add the attribute

We’ll call the new attribute bgColor and insert it directly below headline:

Note that we’ve removed the bg- prefix from the color names above, not just to make the attribute definition a bit shorter, but also to later be able to show you the trick for adding a string constant at rendering time.

Make the attribute editable

All that needs to be done to make the new attribute accessible on the properties dialog of headline widgets, is to provide a specification for it in the provideEditingConfig call for the HeadlineWidget class. We’ve inserted the specification right at the top of the attributes object:

Don’t forget to also add the new attribute to the properties list like shown above. This list defines the attributes to show up on the “General” tab of the properties dialog of the actual widgets.

Providing display titles for enum attribute values

You can provide display titles for each enum value to make them more editor friendly. The style attribute configuration, for example, maps its values “h1” through “h6” to “Heading *” titles:

Initializing attributes

Furthermore, you can initialize attributes on creation of a widget (or page). For this, the initialContent key is available in Scrivito.provideEditingConfig. Use it as follows to set the bgColor value to primary in the moment a new headline widget is added to a page:

Opening the properties dialog of a headline widget now reveals the new attribute and lets you select a background color.

However, closing the dialog after chosing a color doesn’t have any effect. So, let’s render the attribute value as a style.

Render the attribute value

All rendering of widgets and pages is done by a React component that has been attached to the widget or page class using a call to provideComponent. For the Headline widget (and many other widgets) the main task of the component is to collect the CSS class names from the attribute values and use them as the className prop value in a call to Scrivito.ContentTag, which renders the actual content (taken from another attribute, headline, in this case).

Now, let’s add the background color class to the classNames array. This only needs to be done if a color has been selected for the headline background, and, if so, the “bg-” prefix needs to be restored, too:

After inserting the above lines of code before the return statement and saving the file, the background color becomes visible immediately after selecting it on the properties dialog.

That’s it! You’ve customized a Scrivito widget by adding an attribute to the model, extending the properties dialog configuration, and rendering the attribute value!