As mentioned in the introduction to Interface Builder apps, 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.

The HeadlineWidget model class may be defined as follows:

Every app based on the Interface Builder 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).

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.

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:

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:

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.

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!