Skip to content

Developers Quick Start Guide

Introduction

Use this guide to learn how to update a simple Howlite component. We recommend completing the general quick start guide first to get familiar with basic concepts.

The scenario utilizes a sample component library Howlite and a demo site project Luna. For simplicity, we overrode the Title component included in the Howlite collection in advance and prepared the Luna Title component inside the demo project.

Your task is to update the Luna Title component and extend existing functionality and tests. See more details in the sections below.

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).

Part A: Prerequisites

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

Part B: Setup local environment

Clone Luna repository and build it.

git clone https://github.com/websight-io/starter.git
cd starter
./mvnw clean install -P e2e

Run docker environment.

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

Congratulations! Your local environment is ready. Open http://localhost:8080/ and log in using wsadmin/wsadmin credentials.

Part C: Changing component

Hint

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

Business requirement

Let's imagine the following scenario. Page owner wants to update the title of the new Grand Luxor Jewelry Collection.

The current title

The ask is to keep the collection name in one line and decrease the font size for the text Meet our. The expected result is presented below.

Expected result

Technical scope

You need to extend the Title component included in the Howlite to implement the above requirement. However, let's check the orginal component first to identify the scope of changes.

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

Title dialog properties

Enable Overline text option, move Meet our from Heading text to Overline text and submit changes.

Updated title

The result is close to the expectation, but the font size of the overline text is too small. You could prepare a new version of the Title component having a different font size for the overline text. However, this is not a flexible solution. An additional input field to define the font size for the overline text is a better option.

Info

For simplicity, we overrode the original component in advance and prepared the Luna Title. 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 the setting of the overline font size.

Firstly, you need to add a new field overlineSize in the model class LunaTitleComponent.java. Let's define a default size hl-title__heading--size-5 according to the received design too.

application/backend/src/main/java/pl/ds/luna/compoennts/models/LunaTitleComponent.java
package pl.ds.luna.components.models;

import javax.inject.Inject;
import org.apache.sling.api.resource.Resource;
import org.apache.sling.models.annotations.Default;
import org.apache.sling.models.annotations.Model;
import pl.ds.howlite.components.models.TitleComponent;

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

  @Inject
  @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 determining the font size as hl-title__heading--size-6.

<h6 class="hl-title__heading hl-title__heading--size-6" 
    data-testid="overline">${model.subtitle}</h6>
As you updated the model class, you can use its property now.

application/backend/src/main/resources/apps/luna/components/lunatitle/lunatitle.html
<h6 class="hl-title__heading ${model.overlineSize}" 
    data-testid="overline">${model.subtitle}</h6>

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. You have to override the dialog definition from Howlite. Create a new dialog directory and put .content.json file inside.

application/backend/src/main/resources/apps/luna/components/lunatitle/dialog/.content.json
{
  "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 overline field and uses heading size definition from Howlite, but with small size selected by default.

Install changes

Run the following command to install the changes on your local environment.

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

Part D: Functional tests

Run functional tests

We enhance WebSight CMS by adding new features, improving UX, and fixing bugs. Thus, we need confidence that implemented changes don't lead to any regression. We use Cypress for automated testing to ensure it. Moreover, this approach enables us to spend less time on manual testing and regression fixes. We can focus on developing new features and improvements as a result.

We prepared two sample functional tests for the Luna Title component. They are executed during maven build. You can run them using npm on your local environment too. However, you have to add a test content before. Use the following script to install it.

./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 them, they detect your changes for the Luna Title and fail. You should get the following results.

Running:  lunatitle.cy.ts                                                                 (1 of 1)


Luna Title component
  1) renders correctly in preview mode
  2) renders correctly in edit mode


0 passing (8s)
2 failing

1) Luna Title component
     renders correctly in preview mode:

    AssertionError: expected '<h6.hl-title__heading.hl-title__heading--size-5>' to have CSS property 'font-size' with the value '20px', but the value was '25.008px'
    + expected - actual

    -'25.008px'
    +'20px'

    ...

2) Luna Title component
     renders correctly in edit mode:

    Timed out retrying after 4000ms
    + expected - actual

    { 'sling:resourceType': 'luna/components/lunatitle',
       title: 'New heading',
       showSubtitle: 'true',
    -  overlineSize: 'hl-title__heading--size-5',
       subtitle: 'New overline text',
       'jcr:primaryType': 'nt:unstructured',
       headingLevel: 'h1',
       headingSize: 'hl-title__heading--size-2' }

When a functional test fails, you should check why. It is expected in this case, as you implemented the new requirements. Firstly, you updated the default font size of the overline (to ensure consistency with the design). Secondly, you added a new property to the dialog for the component. The tests recognized both changes, and you should adjust them as well. The following section presents how to complete it.

Hint

Even better is to start by changing a test, so it fails and then adjusting the implementation so that the test passes.

Update functional tests

As functional tests fail due to the changes, you should adjust them. They are placed in file tests/end-to-end/tests/lunatitle.cy.ts.

The first 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.

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

The second test validates the dialog for the component. Update the test to recognize the new input field.

    cy.request(
      '/content/luna-test/pages/LunaTitle/jcr:content/rootcontainer/maincontainer/pagesection/title.json'
    )
      .its('body')
      .should('deep.eq', {
        'sling:resourceType': 'luna/components/lunatitle',
        title: 'New heading',
        showSubtitle: 'true',
        overlineSize: 'hl-title__heading--size-5',
        subtitle: 'New overline text',
        'jcr:primaryType': 'nt:unstructured',
        headingLevel: 'h1',
        headingSize: 'hl-title__heading--size-2'
      });

Run functional tests again

Now, you can execute the functional tests again.

./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 get a report like the one below.

Running:  lunatitle.cy.ts                                                                 (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

Hint

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 check it too.

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

Find the Luna Title in the component tree on the left. Drag and drop the component on the page just below the orginal one.

Luna Title added

Edit properties of the Luna Title:

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

Luna Title Dialog Properites

Submit changes. The title should look like expected now. You can delete the original Title component to finalize the change.

Updated Luna Title

Part F: Clean-up

Stop the environment

After all, you can stop your environment.

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

Delete environment

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

sh environment/local/delete.sh

The next steps

You learned the foundation of components development for WebSight CMS. Now, we encourage you to explore more details on: