Reusing Components in SpringBot

Components are the most basic building block of an user interface in an application. Conceptually, a component can be composable (includes other components) or atomic (a UI element such as a button).

In Angular, a component contains a selector, template and other properties which specifies the metadata required to process the component.

Components, by nature, are reusable throughout the application once they are built. This increases development speed as well as maintainability throughout the codebase as any changes only need to be made in one place — the component itself.

This also allows ease of adding or removing components in various places as a component may have been defined previously. This further enables developers to eliminate unneccessary duplication in the codebase.

In the third generation bots, components are defined in accordance to our standards. These standards define components and their behaviours in generic terms which can be implemented in any framework, which in this case is Angular.

These components can be found in the following places:

• clientside/src/app/pages: pages defined in the UI diagram
• clientside/src/app/lib/components: common components used throughout the application
• clientside/src/app/tiles: custom tiles used throughout the application

Following Angular’s way of defining components, the above directories define each component with a *.ts, *.html and *.scss files.

The *.html file of each component is the DOM structure and view of the component. It is what the component will look like when displayed on the front-end. It is recommended to follow the standards when you want to modify or build a component.

The *.ts folder contains all the component’s logic, features and properties.

Unlike the html and ts files, it is highly recommended that do not make changes in the *.scss files. These changes should be made outside the components folder and in the base scss folder instead, which is further explained in the Introduction to Harmony article.

A great component example is the button component which is found in clientside/src/app/lib/components/button.
The file button.component.ts contains multiple properties such as IconPosition,
ButtonSize, ButtonAccentColour, ButtonStyle and any additional classes that can be applied in the protected regions.

Implementation

Task: Reuse the button component in the login tile, where it will clear text inside the username and password fields. It serves as a simple example of how to component reuse.

You will be required to interact with the following files:

login.tile.component.html

First, we need to create a new button in the HTML file:

1. Locate login.tile.component.html at clientside/src/app/lib/tiles/login/login/login.tile.component.html.
2. Locate the protected region: ``
3. Turn on the protected region by replacing off begin with on begin.

4. Add the following code below the line:

    <button cb-button (click)="clear($event)">Clear</button>
   

5. Your HTML file should now look like this:

    ...
        </cb-textfield>
        <button cb-button [type]="'submit'" [isDisabled]="!loginForm.valid">Login</button>
    </form>
   
   
    <button cb-button (click)="clear($event)">Clear</button>
   

The added line of code simply defines a new button that, when clicked, will trigger a method called clear inside the accompanying *.ts file. In this case, that the *.ts file is login.tile.component.ts. The variable $event is an event object created and passed on by Angular. More details on $event can be found in the Angular user input guide.

If we were to run the client-side now and test our new button, nothing would happen. That’s because we first need to define the button functionality.

login.tile.component.ts

We now need to create a callback method for our button.

1. Locate login.component.ts at clientside/src/app/lib/tiles/login/login/login.component.ts.
2. Locate the protected region: // % protected region % [Add any additional class methods here] off begin
3. Turn on the protected region by replacing off begin with on begin.

4. Add the following code below the line:

    /**
     * Clear out the current login form.
     */
    clear($event) {
        $event.preventDefault();
        this.loginForm.reset();
    }
   

5. Your file should now look like this:

    ...
   
    // % protected region % [Add any additional class methods here] on begin
    /**
     * Clear out the current login form.
     */
    clear($event) {
        $event.preventDefault();
        this.loginForm.reset();
    }
    // % protected region % [Add any additional class methods here] end
   
    ...
   

Here we make use of the $event object to stop the button click from submitting the login form, which is the default behaviour of Angular.

Now that we have modified the appropriate files, you can run Angular and test out the new functionality.

The page should look something like this:

Try typing something into the text fields and click Clear. The text will now be cleared.
For more information on how to define your own components, check out the Angular website.

Component Configuration

Our button works fine, but is a bit plain. Let’s configure our button’s style to make it stand out.

1. Open login.tile.component.html and locate where we defined our button.
2. Add [buttonStyle]="buttonStyle.OUTLINE" to the button’s attributes.

3. Your button should now look like this:

    <button cb-button [type]="'button'" (click)="clear($event)" [buttonStyle]="buttonStyle.OUTLINE">Clear</button>
   

4. Open login.component.ts and locate the additional imports protected region: // % protected region % [Add any additional imports here] off begin
5. Turn on the protected region by replacing off begin with on begin

6. Add the following line in the protected region

    import {ButtonStyle} from '../../../components/button/button.component';
   

7. Locate the additional class fields protected region: // % protected region % [Add any additional class fields here] off begin
8. Turn on the protected region by replacing off begin with on begin

9. Add the following line in the protected region

    buttonStyle = ButtonStyle;
   

   This step is required as Angular has some enumeration limitations. You cannot refer to an enumeration directly from the template. Instead, you need to refer to a class field, in this case buttonStyle, of type ButtonStyle, which is an enumeration containing different button styles. In Angular this is referred to as Property Binding.

Your Angular server will now refresh upon saving, and your login page should now look something like this:

Component Documentation

To ease development, SpringBot also writes CompoDoc by default, which is the equivalent of JavaDoc in Java. CompoDoc exposes components and other classes throughout the application so you can search for the component that best suits your need.

In order to write CompoDoc, simply:

1. Open a terminal and navigate to clientside.
2. Type in yarn add @compodoc/compodoc and run it.
3. Angular will now write out CompoDoc that can be accessed at clientside/documentation/index.html.

Solution

Have a look at the reusing-components branch to see the code solution.