There are many use cases for overlaying an image with another one: magnifying an area, showing a person’s avatar, or highlighting some detail. Your imagination is the limit.

In this brief tutorial, we are going to show you how to have an image widget render an additional image on top of the actual one. The additional image’s width, border offset, and border radius will be specifiable, allowing you to position the overlay flexibly within the bounds of the image underneath. To achieve this, we are going to use a couple of Bootstrap classes in conjunction with quite a few inline styles to not have to define a multitude of additional CSS classes, which would have blown up this tutorial.

Once more, the Scrivito Example App serves us as a starting point. Widgets are represented as directories in the “src/Widgets” directory, so just create one named OverlayImageWidget and add the files for the class definition, the editing configuration, and the component to it. We’re providing the contents of these files below and will explain how they work.

A widget’s class declares the attributes it uses. In our case, we need two reference attributes for the images, image and overlayImage, plus one each for the various configurable overlay styles, e.g. alignment:

Note that all numerical values are given in percent, not in pixels, as we want the rendered result to be responsive.

As you might have gathered from other tutorials or the SDK’s API documentation, Scrivito comes with helper React components such as Scrivito.ImageTag for rendering attributes and making them editable in place. In other words: Only attributes that cannot be changed directly on a page need to be configured for editing them via the properties dialog. In the case of our OverlayImageWidget, this applies to the style attributes.

All of the attributes the above configuration makes editable are of the enum type, meaning that zero or exactly one value can be selected from a predefined set. We’ve already defined the values of each attribute in the widget class definition; the editing configuration maps those values to strings (title) to be displayed for them on the properties dialog. Additionally, two attributes (alignment and width) are given initial values, which will be set for every new OverlayImageWidget placed onto a page.

A widget component’s task is to render widget instances based on their respective attributes. Our OverlayImageWidget component renders its two images as child elements of a <div> container with relative positioning. The overlay is positioned absolutely, meaning that its dimensions etc. refer to the container.

As you can see, the component first fetches the overlay’s styles, and initializes the style tag attribute passed to the overlay image further down. After assigning the various other parameters to style, the <div> container with its two child images is rendered using Scrivito.ImageTag.

You now have a widget for displaying an image that is overlaid by another one which is adjustable in size, shape, and position. To make this widget even more versatile, you could:

• Provide finer grained percentages.
  
• Make the overlay’s border color, width, and style configurable as well.
  
• Provide separate horizontal and vertical offsets.
  

Have fun!