FrontierDocumentation

Frontier ngx-components Documentation

Frontier Components comprises a range of components which implement common interaction patterns based on Angular and Material Design specification.

To assist in the creation of a Frontier Software Component following the Frontier Software standards we have created a CLI (@frontier/ftr-ngx-cli) that works with the Angular CLI to create a basic component that should be used as a starting point for any component you create.

The components are stored in a monorepo controlled by Lerna. By using the Frontier Software CLI your project will contain the necessary configuration to support the monorepo.

We automatically generate documentation using compodoc. The Frontier Software CLI will also prepare your component to work with the documentation generation process.

As much as possible Frontier Software components build on Angular Material components. Please consider theming or extending an existing Material component before you write your own component from scratch.

Getting Started

The Frontier Software component library repo

Pull the Frontier Software component library repo (ngx-components) from the web-component project. The repo can be found at this URL which can be used to pull the component library

https://frontiersoftware.visualstudio.com/web-component/_git/ngx-components

Being a monorepo housing a component library there is no develop branch since it does not follow gitflow conventions. Create your feature branches directly from the master branch. Pull requests push changes directly to master.

The Frontier Software private NPM repository

The components are published to a private NPM repository hosted by Azure DevOps. This repository also acts as a proxy to the normal NPM repository so it will contain NPM packages other than Frontier Software components. All Frontier Software components are in the @frontier Org. Filter by @frontier to see only Frontier Software components.

To set up the connection to the Frontier Software NPM repository go to the link below, select NPM and follow the instructions.

https://frontiersoftware.visualstudio.com/web-component/_packaging?_a=connect&feed=WebLibrary

Install the Frontier Software component CLI

It is recommended you install the Frontier Software component CLI globally. To do this run the following command

npm install -g @frontier/ftr-ngx-cli@latest

You can also run this command to update to the latest CLI when there is a new version.

NB. To use the CLI you must also set up the connection to the Frontier Software private NPM repository otherwise installing some dependent packages will fail.

Creating a component

In the folder where you pulled the Frontier Software component library repo, open a command prompt and change to the packages folder. All components that are under the control of Lerna exist in this folder.

In this folder type ngxc new {component name} where component name is the name of the component you want to create. You do not need to add the @frontier Org, this will be added automatically for you. So, as an example, to create a component called @frontier/my-component, you would simply type the following in the packages folder.

ngxc new my-component

This will create a basic component, a demo application, and add some standard packages and tooling to your component project.

Once the creation script finishes your component will be in the folder @frontier-my-component. Change to this folder and run the npm start command. This will start the demo project that was created for your component. The following output will be displayed.

ftr-my-component works!

Component structure

All paths mentioned in this section are relative to the components folder. In the example above the components folder is packages/@frontier-my-component.

The component implementation

projects/ftr-{component name}/src/lib

In this folder there will be a component and a service. This is where you will develop your component.

NB. The project name for the component is prefixed with ftr- so if you originally created my-component the project will be named ftr-my-component.

The demo project

projects/demo/src

This folder contains a simple project that uses your new component. This project has 2 purposes.

  1. It enables you to test your component as you develop it, very useful.
  2. Once you component gets published it becomes the live example accessible in the documentation, so take a little care with how it looks, and give some thought to the demonstration of features.

Component documentation

An empty markdown file is created. Please put general documentation for the component in here.

projects/ftr-{component name}/src/lib/{component name}.component.md

Standard installed packages

  • @angular/flex-layout
  • @angular/cdk
  • @angular/material
  • @frontier/common-lib

When building your component please use @angular/flex-layout to position your html elements. A good tool for understanding flex-layout's use can be found here. The flex-layout documentation can be found here. Use flex-layout to also control responsiveness.

@frontier/common-lib

The @frontier/common-lib contains common fonts and styles used by most components. It would be unusual for a component not to use the common-lib.

Popular files contained in common-lib are:

  • ftr-base-styles.scss Sets the Lato font and alternatives which is the Frontier Software standard font. Sets box-sizing: border-box

  • ftr-theme.scss Contains the global theme for the Material components.

  • ftr-colours.scss Contains all the standard colour constants that should be used in the component or application.

  • ftr-utility.scss Holds some very common stylesheet classes.

NB. The ftr-all-icons font contained in common-lib is no longer updated. It is now in the ftr-icon component which is updated automatically when the UX team add new icons. Please use that instead. in ftr-icon, as well as the ftr-all-icons, you will find the icons as CSV and available as Material Icons.

NB. The common-lib also contains some legacy styles and fonts such as the ftr-all-icon font and ftr-button. Before using styles from common-lib please consider if there is a Material equivalent that can be used.

Adding to your component

It is recommended that you use the Angular CLI to add standard angular pieces (components, services, directives, pipes etc.) to your component. For example to add a new service to the @frontier/my-component component you should use the following command in the components root folder (@frontier-my-component).

ng generate service my-new-service --project ftr-my-component

NB. The project name for the component is prefixed with ftr- so if you originally created my-component the project will be named ftr-my-component.

The components public-api.ts

If you add something like a new component or service to your component and you want it to be accessible when your component is used make sure you update the public-api.ts with a reference to your new code.

projects/ftr-{component name}/src/public-api.ts

Unit testing

We strive for 100% coverage of components by unit tests. Some times it is not possible to cover all code but at least 80% should be covered.

When you run npm test a code coverage report will be generated. That report is placed in the coverage/ftr-{component name} folder. For example my-component's coverage report will be available by opening

@frontier-my-component/coverage/ftr-my-component/index.html

NB. You do not have to create unit tests for the demo project. It is ignored during the testing process.

Before you create a pull request

Ensure the following commands run successfully before you create your pull request. The CI process will run these and expect them to pass.

  • npm test
  • npm run lint
  • npm run build
  • npm run build:demo

The demo build is run because it is built and uploaded to blob storage to be used as the live demo for the generated documentation.

Disabling the live demo

In some cases it is desirable to disable the live demo in the documentation. For instance the web-api demo requires a connection to a real BRE which is not possible.

To disable the live demo

  • Remove the build:demo script from the package.json in the root folder of the component.
  • Remove the example-url comment in the main component file of your component.

Do the reverse of these instructions to re-enable the live demo.

Version numbering

The components use semantic versioning. The version number is taken from the package.json file in the component project folder. For example for the my-component project

@frontier-my-component/projects/ftr-my-component/package.json

During normal development you should not need to manipulate the version number manually. The publish process will use the version in the package.json file as a seed value and update the third number to be the next available version. For Example

  • The package.json file contains the version 2.3.1
  • The latest version of the component in NPM is 2.3.14
  • The component will be published as 2.3.15

If you want to change the first or second number in the version you must do this manually. For example

  • The package.json file contains the version 2.3.1
  • Manually change the package.json version to 3.0.1 and include in your pull request
  • The latest version of the component in NPM is 2.3.14
  • The component will be published as 3.0.1
  • The component will be subsequently published as 3.0.2, 3.0.3, 3.0.4 etc.

Expanding on the standard documentation

It is encouraged that the developer should expand on the automatically generated documentation where possible. This is achieved by using JSDoc tags in the source code of the component.

Also by adding markdown to the ftr-{component name}-component.md file and the README.md file in the component project folder.

  • Here is a link to the compodoc talking about JSDoc JSDoc tags
  • Here is a basic guide to writing markdown. Markdown Guide.

To preview your generated documentation run

npm run generatedocs

NB. You must install compodoc globally to generate the docs. Use npm install -g @compodoc/compodoc

result-matching ""

    No results matching ""