Halstack HAL Angular Components

Halstack HAL angular Components is an npm library of reusable Angular components. It brings together two different responsibilities:

• Consuming Hal REST API's implementing following the DXC API Guidelines

• Rendering these API resources as UI components that are compliant with the DXC UX Guidelines

We have other libraries that will help you handling these responsibilities individually (Halstack Client / Halstack Angular CDK ). Halstack HAL Angular Components uses them under the hood, but it's a higher level abstraction that puts both responsibilities together using the most common association patterns.

For example, collection resources are often associated with tables, and there are a lot of semantics in the standards described by the DXC API guidelines for collections (sorting, paginating...) that could be associated with UI interactions (clicking a table header for sorting, clicking pages for paginating)

Usage

Halstack HAL Angular Components is distributed as an npm library. In order to use it in an existing project, you must install it first:

npm install @dxc-technology/halstack-angular-hal

The library provides the following components and functions to be used in your Angular application:

Components

• HAL Autocomplete

• HAL Table

Service Facade

• HAL Resource Service

HAL Autocomplete Component

HAL Autocomplete Usage

import { DxcAutocompleteHalModule, DxcAutocompleteHalComponent } from '@dxc-technology/halstack-angular-hal';

@NgModule({
  declarations: [
    DxcAutocompleteHalComponent
  ],
  imports: [
    DxcAutocompleteHalModule
  ],
  providers: [],
  entryComponents: []

HAL Autocomplete Props

Name	Default	Description
halUrl: string		The URL of the collection from which we will get a list of items that will contain the value we are looking for. Required
headers: Object		Contains the http headers to be sent along with the http requests to the collectionUrl. Optional
asyncHeadersHandler: ()=>Observable		Async function that will be executed right before every http request in order to retrieve dynamic headers. It must return an observable that resolves into an object with the keys and values of the headers. These headers will be merged with the ones indicated in the headers prop. Optional
propertyName: string		Name of the property to be used for filtering the data. Required
rel: string		Name of the rel of the method that is going to be executed to receive the options for the autocomplete. Required

|

In addition to these component-specific properties you will also have all the properties of the Text field component that can be found on its site.

HAL Autocomplete Example

HTML file

<dxc-autocomplete-hal
  label="HalAutocomplete example"
  halUrl="http://..."
  propertyName="prospect-full-name"
></dxc-autocomplete-hal>

HAL Table Component

HAL Table Usage

import { DxcHalTableModule, DxcHalTableComponent } from '@dxc-technology/halstack-angular-hal';

@NgModule({
  declarations: [
    DxcTableComponent
  ],
  imports: [
    DxcTableModule
  ],
  providers: [],
  entryComponents: []

HAL Table Props

Name	Default	Description
halUrl: string		The URL of the collection resource to be used for the table. Required
headers: Object		Contains the http headers to be sent along with the http requests to the collectionUrl. Optional
itemsPerPage: number	5	The amount of items to be displayed per page. Will be used to calculate the _start and _num query parameters that will be sent to the collection for pagination. Optional

In addition to these component-specific properties you will also have all the properties of the Table component that can be found on its site.

HAL Table Directives

Directives are used to add functionality and new syntax into HTML components. The following directives are customized and you can use them on this component.

Name	Default	Description
dxcColumnDef: string		Column definition. Required
dxcCellDef: Iterable<string>		Cell definition. It selects the value from the array. Required
sortable: Object	isSortable:false propertyName:''	An array of objects representing if the column is going to be sorted and the key value. isSortable: boolean value if it is sorteable. propertyName: string with the key from the array of objects. Optional

HAL Table Example

HTML file

As you know, angular provides a view component which is more o less similar to dom element. In this view component, angular provides a container element and in this hal table component is going to be defined inside as a column of the dxc hal table. These columns has the property name defined in the dxcColumnDef directive in the ng-container component.

Inside of each column container, in a td html element has to be defined the element variable to reach the item value of a hal resource element as it's seen in the next example *dxcCellDef="let item".

<dxc-hal-table halUrl="http://..." headers="" itemsPerPage="4">
  <ng-container
    dxcColumnDef="User"
    [sortable]="{ isSortable: true, propertyName: 'prospect-full-name' }"
  >
    <td *dxcCellDef="let item">
      <dxc-button [label]="item['prospect-full-name']"> </dxc-button>
    </td>
  </ng-container>

  <ng-container
    dxcColumnDef="Date"
    [sortable]="{ isSortable: true, propertyName: 'prospect-update-date' }"
  >
    <td *dxcCellDef="let element">
      <dxc-tag [label]="element['prospect-update-date']"> </dxc-tag>
    </td>
  </ng-container>

  <ng-container dxcColumnDef="Email">
    <td *dxcCellDef="let element">{{ element["prospect-distributor-id"] }}</td>
  </ng-container>
</dxc-hal-table>

HAL Resource Service

HAL Resource Service Usage

import { HalResourceService } from from '@dxc-technology/halstack-angular-hal'

HAL Resource Service Parameters

Name	Default	Description
url: string		The URL of the resource. Required
headers: HttpHeaders		Contains the http headers to be sent long with the http requests to the url indicated in the url prop. Optional

Reactive Programming Usage

The object facade service class has the following properties:

Name	Description
resource: BehaviorSubject<any>	A Halstack Client's HalResource instance of the resource behind the url parameter. It will be null until the resource is fetched. It will be automatically refreshed if the execution of an interaction handler responds with an instance of the same resource.
items: BehaviorSubject<any>	Items returned by the URL parameter.
totalItems: BehaviorSubject<number>	Total number of items.
fetchStatus: 'idle' | 'fetching' | 'resolved' | 'rejected' | 'interaction'	The status of the http request to the url parameter. 'idle' before the request is triggered 'fetching' after the request is triggered and the before we get a response. 'resolved' after getting a successful response. Only if it contains a HAL resource. 'rejected' after getting an error response. Or if response doesn't contain a HAL resource. 'interaction' during the execution of an interaction handler.
requestError: string	The error message in case the request gets rejected. It will be null before getting the response or if the response is successful and contains a HAL resource.
getCollectionHandlers: Function	This is a function containing all collection interactions (_options.links) are available in the HAL collection resource. Each entry has the rel of the interaction as a key. Executing one of these functions will: Make the http request associated to the given interaction.
getHandlers: Function	This is a function containing interactions (_options.links) are available in the HAL resource. Each entry has the rel of the interaction as a key. Executing one of these functions will: Make the http request associated to the given interaction.
fetchResource: Function	This is the main function to fetch for items using the injected instance and the given URL. It can have a body parameter which is an object containing query params for the URL.
executeItemsHandler: Function	This is a function used when the resource is a collection. It needs the rel of the iteration as handlerName parameter.
getHandler: Function	This is a function used when the resource is not a collection. It needs the rel of the iteration as handlerName parameter.
executeHandler: Function	This is a function used when the resource is not a collection. Besides, you can execute it passing a payload or additionals headers as parameters.

Example

@Component({
  selector: 'app',
  templateUrl: './app-component.component.html',
  styleUrls: ['./app-component.component.scss']
})
export class AppComponent implements OnInit {

  halUrl = "http://...";
  headers = "";

  collectionResource: HalResourceService;

  totalItems;
  items;
  fetchStatus;
  error;
  resource;

  page: number = 1;
  itemsPerPage: number = 5;

  constructor(private httpClient: HttpClient) { }

  ngOnInit() {
    this.collectionResource = new HalResourceService(
      this.halUrl,
      new HttpHeaders(this.headers),
      this.httpClient
    );

    this.collectionResource.fetchResource({
      _start: this.page,
      _num: this.itemsPerPage
    });

    this.resource = this.collectionResource.resource;
    this.fetchStatus = this.collectionResource.fetchStatus;
    this.error = this.collectionResource.errorMessage;
    this.items = this.collectionResource.items;
    this.totalItems = this.collectionResource.totalItems;
  }
}

Contributing

Before opening new issues or pull requests, please refer to CONTRIBUTING.MD.

Development Setup

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes.

The project is divided in two main folders. One is for the actual library, and the other is an Angular application using the library.

Library

Contained in the diaas-angular-cdk-hal folder.

cd projects\diaas-angular-cdk-hal

Install the library dependencies.

npm install

Run the build process into dist folder, detecting and automatically building changes in src.

npm run build-lib:watch

Or if there is no need to watch for changes, run the build process and pack it to generate the library.

npm run generate-lib

Example Application

Contained in the cdk-hal-examples folder, but it can be run from the root of the repository.

cd halstack-angular-hal

Install the application dependencies.

npm install

The Halstack HAL Angular CDK needs to be linked to the application (from the folder dist\diaas-angular-cdk-hal). This one must have been previously built as shown before.

npm run link-lib

Start the application.

npm run start

To be able to see data on these components, a server should be run. It is used json-server for this purpose so it must be installed.

Once it is done, go to db folder and execute the server.

cd db
node server.js

If you are watching for changes, anytime you make a change to the library or the app, angular cli will live-reload your local dev server so you can iterate on your component in real-time.

Running the tests

Run tests from the library folder projects\diaas-angular-cdk-hal after the library dependencies have been installed.

cd projects\diaas-angular-cdk-hal
npm run test