Skip to content

Developers quick start guide


This guide explains how to update a simple Howlite component. Before you complete this guide, we recommend completing the basic quick start guide first so that you understand basic WebSight CMS concepts.

For demonstration purposes, this guide uses a sample component library, Howlite, and a demo site project, Luna. For the sake of simplicity, we overrode the Title component included in the Howlite collection in advance and preconfigured the Luna Title component inside the demo project.

Your task in completing this guide is to update the Luna Title component and extend existing functionality and tests. The sections below explain more detail.

Important notice

All scripts presented below are designed for Linux-based platforms. If you are a Windows user, please install and configure Windows Subsystem for Linux (WSL) to use this guide.

Part A: Prerequisites

  1. Install AdoptOpenJDK 17 with 'x64/aarch64' architecture (on macOS use brew install openjdk@17):
  2. Install Node.js and NPM
  3. Install Docker Desktop.
  4. Install Git

Part B: Setup local environment

First, clone the Luna repository and build it within your local environment using the following commands:

git clone
cd starter
./mvnw clean install -P e2e-functional

Then, start a Docker environment.

docker compose -f environment/local/docker-compose.yml up -d

Congratulations! Your local environment is now ready. To view it, open http://localhost:8080/ in a Web browser and log in using the credentials wsadmin/wsadmin.

Part C: Changing component


If you need help navigating inside WebSight, see the basic getting started guide for details.

Business requirement

Let's imagine the following scenario: A page owner wants you to update the title of the page that describes the company's new Grand Luxor Jewelry Collection.

The current title

To fulfill this request, you are asked to keep the collection name on one line and decrease the font size for the text Meet our. The expected result is presented below.

Expected result

Technical scope

To do this, you need to extend the Title component included in the Howlite library. Before doing that, let's check the orginal component first to identify the scope of changes.

Run WebSight, open the Luna space and edit the home page. Find the Title component that contains the text Meet our New Grand Luxor Jewelry Collection and edit its properties on the sidepanel.

Title panel properties

Enable the Overline text option, move Meet our from Heading text to Overline text.

Updated title

As you can see, the result comes close to meeting the expectation, but the font size of the overline text is too small. You could prepare a new version of the Title component with a different font size for the overline text. However, this is not a flexible solution. Creating an additional input field to define the font size for the overline text is a better option.


For simplicity, we overrode the original component in advance and prepared the Luna Title component. It is a part of the demo site project, but it is just a placeholder. It works exactly as the Title. The following sections guide you on how to implement the change.

Component update

Your task is to enable setup of the overline font size.

To start, first you need to add a new field, overlineSize, to the model class Let's define a default size hl-title__heading--size-5 according to the received design as well. The following Java code will do this:

package pl.ds.luna.components.models;

import javax.inject.Inject;
import pl.ds.howlite.components.models.TitleComponent;

@Model(adaptables = Resource.class)
public class LunaTitleComponent extends TitleComponent {

  @Default(values = {"hl-title__heading--size-5"})
  private String overlineSize;

  public String getOverlineSize(){
    return overlineSize;


Next, you need to update the component HTML template. The original one defines the CSS class that determines the font size as hl-title__heading--size-6.

<h6 class="hl-title__heading hl-title__heading--size-6" 
Because you updated the model class, you can use its property now.

<h6 class="hl-title__heading ${model.overlineSize}" 

The last step is to add the field to the dialog used by authors. They need it to define component properties in the page editor. To enable this, you have to override the dialog definition from Howlite. Do so by creating a new dialog directory and put .content.json file inside.

  "tabs": {
    "generalTab": {
      "container": {
        "overlineSize": {
          "sling:resourceType": "wcm/dialogs/components/include",
          "sling:orderBefore": "overline",
          "path": "/libs/howlite/components/common/headingsize",
          "include": {
            "sling:resourceSuperType": "/libs/howlite/components/common/headingsize",
            "label": "Overline size",
            "name": "overlineSize",
            "description": "Changes font size",
            "s": {
              "selected": true
            "m": {
              "selected": false

The above definition specifies the new overlineSize field. It is placed before the overline field and uses a heading size definition from Howlite, but with small size selected by default.

Apply changes

Run the following command to apply the changes to your local environment.

./mvnw -f application/backend/pom.xml clean install -P autoInstallBundle

Part D: Functional tests

Run functional tests

We continuously improve WebSight CMS by adding new features, improving the UX, and fixing bugs. Thus, we need confidence that changes don't lead to any regression on websites. To provide this confidence, we use Cypress to enable automated testing of components. This approach enables us to spend less time on manual testing and regression fixes. We can focus on developing new features and improvements instead.

To demonstrate automated functional testing, we prepared two sample functional tests for the Luna Title component. They are executed during the Maven build process. You can run them using npm on your local environment as well. However, you have to add test content before running the tests. Use the following script to set this up:

./mvnw -f tests/content/pom.xml clean install -P autoInstallPackage

Now, you can run the tests using the following command:

npm run-script test --prefix tests/end-to-end

If you execute the tests, they will detect your changes for the Luna Title and fail. You should get the following results:

Running:                                                                 (1 of 1)

  Luna Title component
    1) renders correctly in preview mode
    ✓ renders correctly in edit mode (3529ms)

  1 passing (14s)
  1 failing

  1) Luna Title component
       renders correctly in preview mode:

      Timed out retrying after 10000ms
      + expected - actual


When a functional test fails, you should check why. It is expected in this case, as you implemented new requirements. You updated the default font size of the overline component (to ensure consistency with the design). The tests recognized the change, and you should adjust them as well. The following section explains how to do so.


A best practice is to start by changing a test so that it fails until you've made desired changes. Then, apply your changes so that the test passes.

Update functional tests

When functional tests fail due to changes, you should adjust them. They are placed in file tests/end-to-end/tests/

The test checks the font size for the overline text. There are two component instances validated. Thus, you need to update assertions for both of them as follows.

      .should('have.css', "font-size", "25.008px")
      .should('have.text', 'Additional overline text filled')
      .should('have.css', "font-size", "25.008px")
      .should('have.text', 'Resized to 6 cols on L breakpoint')

Run functional tests again

Now, you can execute the updated functional tests:

./mvnw -f tests/content/pom.xml clean install -P autoInstallPackage
npm run-script test --prefix tests/end-to-end

Both tests should pass this time. You should receive a report like the one below.

Running:                                                                 (1 of 1)

Luna Title component
  ✓ renders correctly in preview mode (1030ms)
  ✓ renders correctly in edit mode (2774ms)

2 passing (4s)

Congratulations! You updated the component, and it passed tests.

Part E: Use the new component


If you need help to navigate inside WebSight, see the general getting started for details.

The page owner can use the updated component now. Let's verify by checking it out in the admin interface.

Switch to WebSight CMS, open the Luna space, and edit the home page. Find the Title with text Meet our New Grand Luxor Jewelry Collection.

Then, find the Luna Title in the component tree on the left. Drag and drop the component on the page just below the original one.

Luna Title added

Edit properties of the Luna Title on the side panel:

  1. set Heading level to H2
  2. set Heading size to XL
  3. set Heading text to New Grand Luxor Jewelry Collection
  4. enable overline text
  5. set Overline size to L
  6. set Overline text to Meet our

Luna Title Panel Properites

The title should appear as expected now. You can delete the original Title component to finalize the change.

Updated Luna Title

Part F: Clean-up

Stop the environment

After completing this guide, you can stop your local environment using Docker:

docker compose -f environment/local/docker-compose.yml down

The environment will still exist but will no longer be running.

Delete environment

If you don't need your environment anymore, you can delete it permanently using a script.

sh environment/local/

Next steps

This guide walked through the essentials of developing components for WebSight CMS. As a next step, we encourage you to explore additional details about the following: