Skip to content

Commit

Permalink
docs: Update platform lib README.md with i18n section (#2545)
Browse files Browse the repository at this point in the history 
* docs: update platform readme.md with i18n section, documentation readme with i18n example for application user's reference

* docs: corrected documentation and readme with platform example

* docs: modified description and i18n section
  • Loading branch information
@kavya-b
kavya-b committed May 27, 2020
1 parent b743edd commit 3b6243e
Show file tree
Hide file tree
Showing 2 changed files with 131 additions and 78 deletions.
155 changes: 102 additions & 53 deletions PLATFORM_README.md
View file
Expand Up @@ -9,25 +9,34 @@

## Description

The `@fundamental-ngx/platform` is built on top of the `@fundamental-ngx/core` to enhance existing functionality.
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.

Provide a higher abstraction for the components by hiding most of the internal implementation details which boosts developer productivity.
Since there is a plan to generate UI programatically then components must be instantiable (they cannot be directives).

Components must be instantiable programmatically.
## Design

Enterprise readiness:
Each component that is developed here needs to have corresponding [technical specification](https://github.com/SAP/fundamental-ngx/wiki/Platform-Library-Home), where we need to agree on several things:

1. Working with data( reactive stream over the array, Data sources over the reactive steam)
- Component Signature
- We try to capture common things among components
- Functionality
- We decide how much extensible the component needs to be.

2. Layouts (Dashboard, detail page, master/detail page, Search/result page).
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.

It is not about UI:
- Defining component model and how we work with data
- Pre-defined layouts (Dashboard, detail page, master/detail page, Search/result page).

1. Application state UI
    2. Bootstrapping and Configuration
    3. Communication with the backend system.
This `Platform UI library` is not going to be only about UI but it needs to also capture other aspects:

Example:
- Application state UI
- Bootstrapping and Configuration
- Communication with the backend system.

### Example:

This example captures several things:

Expand All @@ -41,43 +50,55 @@ 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>
```html
<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>
```html
<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
Expand Down Expand Up @@ -119,37 +140,65 @@ For an existing Angular CLI application,

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

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

```javascript
import { SwitchModule } from '@fundamental-ngx/core';
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 { SwitchModule } from '@fundamental-ngx/core';
```javascript
import { PlatformLinkModule } from '@fundamental-ngx/platform';

@NgModule({
...
imports: [SwitchModule],
imports: [PlatformLinkModule],
})
export class DemoModule { }
```

3. **Add the component to your HTML.**

```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](https://angular.io/guide/i18n#mark-text-with-the-i18n-attribute).

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

```html
<fdp-button
i18n="emphasized button|An example for button with emphasized property@@buttonEmphasizedBtn"
[type]="'emphasized'"
>Emphasized Button</fdp-button
>
```

3. **Add the component to your HTML.**
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:

```html
<fd-switch [size]="'l'" [(checked)]="myValue">Large Switch</fd-switch>
<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 @fundamental-ngx/platform`. Append `--code-coverage` to generate code coverage documentation.
Run `ng test platform`. Append `--code-coverage` to generate code coverage documentation.

For models prior to 0.11.1 use `fundamental-ngx`

Expand Down
54 changes: 29 additions & 25 deletions libs/platform/README.md
View file
Expand Up @@ -9,34 +9,33 @@

## 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.
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](https://github.com/SAP/fundamental-ngx/wiki/Platform-Library-Home), 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.
- 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.
enterprise use.

* Defining component model and how we work with data
* Pre-defined layouts (Dashboard, detail page, master/detail page, Search/result page).
- 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.
- Application state UI
- Bootstrapping and Configuration
- Communication with the backend system.


## API Reference

See [Component Documentation](https://sap.github.io/fundamental-ngx/docs/platform/home) for examples and API details.
Expand Down Expand Up @@ -76,37 +75,39 @@ For an existing Angular CLI application,

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

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

```javascript
import { ToggleModule } from '@fundamental-ngx/core';
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 { ToggleModule } from '@fundamental-ngx/core';
```javascript
import { PlatformLinkModule } from '@fundamental-ngx/platform';

@NgModule({
...
imports: [ToggleModule],
...
imports: [PlatformLinkModule],
})
export class DemoModule { }

```
```

3. **Add the component to your HTML.**

```html
<fd-toggle [size]="'l'" [(checked)]="myValue">Large Toggle</fd-toggle>
<fdp-link [href]="'http://www.google.com'" [title]="'Extra info as tooltip text and aria-label'">
Standard Link
</fdp-link>
```

## Tests

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

Run `ng test @fundamental-ngx/platform`. Append `--code-coverage` to generate code coverage documentation.
Run `ng test platform`. Append `--code-coverage` to generate code coverage documentation.

For models prior to 0.11.1 use `fundamental-ngx`

Expand All @@ -132,7 +133,6 @@ If you want to contribute, please check the [CONTRIBUTING.md](https://github.com

Check out the [NEW_COMPONENT.md](https://github.com/SAP/fundamental-ngx/blob/master/NEW_COMPONENT.md) guide on building a new component for the library and creating the necessary documentation for your new component.


# Platform

This library was generated with [Angular CLI](https://github.com/angular/angular-cli) version 7.2.0.
Expand All @@ -155,6 +155,10 @@ After building your library with `ng build platform`, go to the dist folder `cd

Run `ng test platform` to execute the unit tests via [Karma](https://karma-runner.github.io).

## Supporting internationalization

If you want to support i18n, please check the [Supporting i18n in ngx/platform Wiki](https://github.com/SAP/fundamental-ngx/wiki/Internationalization-Supporting-in-@fundamental-ngx-platform) documentation for general guidelines when working on a new component.

## Further help

To get more help on the Angular CLI use `ng help` or go check out the [Angular CLI README](https://github.com/angular/angular-cli/blob/master/README.md).

0 comments on commit 3b6243e

Please sign in to comment.