PLATFORM_README.md

Fundamental Library for Angular

Description

The @fundamental-ngx/platform is built on top of the @fundamental-ngx/core to enhance existing functionality and to provide a higher abstraction for the components by hiding most of the internal implementation details. The goal is to create a layer which is closer to application development and not to the library creators.

Since there is a plan to generate UI programatically then components must be instantiable (they cannot be directives).

Design

Each component that is developed here needs to have corresponding technical specification, where we need to agree on several things:

• Component Signature
• We try to capture common things among components
• Functionality
• We decide how much extensible the component needs to be.

As already mentioned above platform the goal is try to be closer to application developer as well as make it more ready for enterprise use.

• Defining component model and how we work with data
• Pre-defined layouts (Dashboard, detail page, master/detail page, Search/result page).

This Platform UI library is not going to be only about UI but it needs to also capture other aspects:

• Application state UI
• Bootstrapping and Configuration
• Communication with the backend system.

Example:

This example captures several things:

a). How we abstract form assembly that me as developer I dont deal with layouting of elements for labels, controls, hints, etc..

b). Assembly like this gives pretty big space in terms of different layouts that we want to support in the application (1 colum, 2 colums)

c). If we need to group information into sections

d). How we are handling and forms errors

e). Dropdown usage. Everything is happening inside the component that manages the iteration of the items we just pass list of values.

<fdp-form-group
    [isFiveZoneLayout]="true"
    labelLayout="floating"
    [formGroup]="fg"
    [errorHanlding]="'navigate'"
    (onSubmit)="save($event)"
    (navigateToError)="onGoToError($event)"
>
    <fdp-form-field label="email" id="email" zone="left">
        <fdp-input type="email" placeholder="email" [required]="true"></fdp-input>
    </fdp-form-field>

    <fdp-form-field
        reqiuire="true"
        label="My Favorite Colors"
        id="colors"
        hint="Pick one of your favorite color"
        zone="right"
    >
        <fdp-select [list]="myColors"></fdp-select>
    </fdp-form-field>

    <fdp-form-field label="Description" id="desription" zone="bottom">
        <fdp-text-area [autoSizeEnabled]="true"></fdp-text-area>
    </fdp-form-field>
</fdp-form-group>

<fdp-form-group [isFiveZoneLayout]="true" labelLayout="floating" [formGroup]="fg" [errorHanlding]="'navigate'">
    <fdp-form-section title="Basic Information">
        <fdp-form-field label="email" id="email" zone="left">
            <fdp-input type="email" placeholder="email" [required]="true"></fdp-input>
        </fdp-form-field>
        <fdp-form-field
            reqiuire="true"
            label="My Favorite Colors"
            id="colors"
            hint="Pick one of your favorite color"
            zone="right"
        >
            <fdp-select [list]="myColors"></fdp-select>
        </fdp-form-field>
    </fdp-form-section>
    <fdp-form-field label="Description" id="desription" zone="bottom">
        <fdp-text-area [autoSizeEnabled]="true"></fdp-text-area>
    </fdp-form-field>
</fdp-form-group>

API Reference

See Component Documentation for examples and API details.

Requirements

To download and use Fundamental Library for Angular, you will first need to install the node package manager.

Fundamental Library for Angular is intended for use with Angular 8 or newer.

Prior knowledge of Angular is recommended.

Getting Started

For an existing Angular CLI application,

1. Install Fundamental-NGX. ng add @fundamental-ngx/platform For models prior to 0.11.1 use fundamental-ngx

   If you do not use the Angular CLI or if this command does not work for you, please see the full installation guide.

2. Import the modules you want to use.

   To add the entire library, add the following import to your main application module.

   import { FundamentalNgxPlatformModule } from '@fundamental-ngx/platform';
   
   @NgModule({
       ...
       imports: [FundamentalNgxPlatformModule],
   })
   export class DemoModule { }

   To include an individual Angular Fundamental component in your application, you only need to import the relevant module.

   For example, to use Link, add the following import to your main application module.

   import { PlatformLinkModule } from '@fundamental-ngx/platform';

   Note: Be careful while importing the entire FundamentalNgxPlatformModule as it loads all modules; we recommend to only import relevant modules as needed.

   For models prior to 0.11.1 use fundamental-ngx

   import { PlatformLinkModule } from '@fundamental-ngx/platform';
   
   @NgModule({
   ...
   imports: [PlatformLinkModule],
   })
   export class DemoModule { }

3. Add the component to your HTML.

   <fdp-link [href]="'http://www.google.com'" [title]="'Extra info as tooltip text and aria-label'">
       Standard Link
   </fdp-link>

4. To add support for i18n

   To mark a text for translation, use Angular's i18n marker.

   For example, to translate the button text, add i18n on the element fdp-button:

   <fdp-button
       i18n="emphasized button|An example for button with emphasized property@@buttonEmphasizedBtn"
       buttonType="emphasized"
       label="Emphasized Button"
   ></fdp-button>

   It is recommended to give ID to the marker like @@buttonEmphasizedBtn in the format @@<Module>.<Component>.<UniqueId> for easier tracking in the extracted messages.xlf file. A meaningful description such as An example for button with emphasized property and a context like emphasized button for easier understanding for translators can also be given.

   Note: Some components allow you to provide data imperatively through an array of objects like [list]="seasons" in the below example:

   <fdp-radio-group [id]="'radio1'" [name]="'radio1'" [list]="seasons" [value]="'Summer'" formControlName="example1">
   </fdp-radio-group>

   When data is provided like this (probably coming from a db or backend server), it is left to the application to provide for the translated text. Providing i18n markers as shown in the previous example will not work as this is a limitation of Angular's i18n for now.

Tests

Fundamental Library for Angular makes use of Jasmine and Karma for its unit tests.

Run ng test platform. Append --code-coverage to generate code coverage documentation.

For models prior to 0.11.1 use fundamental-ngx

Versioning

The @fundamental-ngx/platform library follows Semantic Versioning. These components strictly adhere to the [MAJOR].[MINOR].[PATCH] numbering system (also known as [BREAKING].[FEATURE].[FIX]).

For models prior to 0.11.1 use fundamental-ngx

Merges to the master branch will be published as a prerelease. Prereleases will include an rc version (e.g. [MAJOR].[MINOR].[PATCH]-rc.[RC]).

Known Issues

Please see Issues.

Support

If you encounter an issue, you can create a ticket.

Contributing

If you want to contribute, please check the CONTRIBUTING.md documentation for contribution guidelines. Please follow the Angular commit message guidelines.

Check out the NEW_COMPONENT.md guide on building a new component for the library and creating the necessary documentation for your new component.