The properties dialog is where content editors can fine tune the appearance of a widget or page, from alignment and font sizes to colors and borders, etc.

Making options available in a properties dialog typically comes down to adding the corresponding attribute to the editing configuration of the object or widget class. This is pretty straightforward as Scrivito does the rest: it renders the required editing controls for that attribute in the properties view.

However, editing object and widget properties can become cumbersome when there are many options to choose from. Also, for some options it can be tough to determine their effect without switching between the properties dialog and the webpage.

The good news is that the properties view is customizable. You can replace the built-in editing controls with your own for a more intuitive or visually appealing workflow. This can be achieved by providing a Scrivito extension, a component to be used for displaying the contents of a tab on a properties dialog.

In this tutorial, we are going to show you how to use a Scrivito extension to render the values of enum and multienum attributes in a more sophisticated way. To illustrate the possibilities available, we will add clipping options to the Example App’s image widget. Clipping will be done by means of the clip-path CSS property, and a preview of each of the shapes offered will be visible on the properties tab we are going to provide.

So this is sort of a two-in-one tutorial. :)

First of all, we need to enable editors to choose the desired clipping shape of an image. For this, we are going to add an enum attribute to the image widget’s class definition. We named it clipShape and set its values to what we thought would make their meaning clear. Here’s our addition to the widget’s attributes definition:

The editing configuration of a widget (or object) class lets you define propertiesGroups. A property group definition includes a title and, usually, a selection of properties (attributes) to be made editable on a dedicated tab in the properties dialog. As an alternative to the properties, a custom React component for rendering the tab’s content can be specified.

A component is exactly what we need here, but before implementing it (we named it ImageShapePicker), let’s make it available as a tab in the properties of image widgets. In the editing configuration, we’ve inserted it directly underneath the properties (which are rendered, as usual, on the default ”General” tab). Our propertiesGroups array consists of exactly one element that declares a tab titled ”Shape”:

From the component key above you can see that the editing interface provides us with the widget concerned, and that it’s handed down to the component, along with the names and titles of the shapes it is meant to make available for selection.

For the editors’ convenience, the ImageShapePicker component renders previews of the image concerned, applying the available shapes. It renders them as elements of an unordered list, and highlights the element representing the currently selected shape. The CSS for generating a specific shape is looked up using the imageStyle function we are going to provide below. Every element is equipped with an event handler for detecting if the selection was changed and then updating the widget’s clipShape attribute.

Here are the CSS classes the ImageShapePicker component uses for itself, not for applying the shapes:

As mentioned above, the value of the style tag attribute used to apply the shape is set by calling a function, imageStyle. To this function, the name of the clipShape whose style is needed is passed. We’ve placed this function in a dedicated file:

As you can see, the imageStyle function uses the passed-in clipShape attribute value to look up the corresponding clipping path which is then assigned to the clipPath style property. clipPath is React’s spelling of the clip-path CSS property (note that browser support is limited).

Voilà! You could start your app right now to see the clipping options come to life on an image widget’s properties view.

At this point, the image displayed on a page is ignorant towards the clipping we want to have applied. To remedy this, we need to pass the style with our computed clipPath property to the Scrivito.ImageTag component that renders the image:

Once again the imageStyle function is used to set the value of the style prop which, in our case, is made up of nothing more than the clip-path associated with the current clipShape attribute value.

You’ve significantly improved the way in which an enum attribute is presented to editors on a widget’s properties view! This alone is already great, but on top you’ve applied a clip path to an image, extending your toolbox for creating impressive web pages. Congratulations!

There’s a fantastic “CSS clip-path maker” we highly recommend trying out, Clippy. If you would like to dig deeper, we found Clipping and Masking in CSS to be an excellent read.