From 3b6243ea6fc72aaab341c7029fdbc61c926dcb96 Mon Sep 17 00:00:00 2001 From: kavya-b Date: Wed, 27 May 2020 16:15:14 +0530 Subject: [PATCH] docs: Update platform lib README.md with i18n section (#2545) * 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 --- PLATFORM_README.md | 155 ++++++++++++++++++++++++++-------------- libs/platform/README.md | 54 +++++++------- 2 files changed, 131 insertions(+), 78 deletions(-) diff --git a/PLATFORM_README.md b/PLATFORM_README.md index 2d15c3c4d94..ce8106f6d24 100755 --- a/PLATFORM_README.md +++ b/PLATFORM_README.md @@ -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: @@ -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. -``` - - -     -         -     - -     -         -     - -     -         -     -     +```html + + + + + + + + + + + + + ``` -``` -     -         -         -         -             -         -         -             -         -     -         -             -         -     +```html + + + + + + + + + + + + + ``` ## API Reference @@ -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 + + Standard 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 + Emphasized Button ``` -3. **Add the component to your HTML.** + It is recommended to give ID to the marker like `@@buttonEmphasizedBtn` in the format `@@..` 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 - Large Switch + + ``` + 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` diff --git a/libs/platform/README.md b/libs/platform/README.md index d144c6bd79d..45dae2f5403 100644 --- a/libs/platform/README.md +++ b/libs/platform/README.md @@ -9,9 +9,9 @@ ## 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). @@ -19,24 +19,23 @@ Since there is a plan to generate UI programatically then components must be  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. @@ -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 - Large Toggle + + Standard 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` @@ -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. @@ -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).