@indigina/angular
v1.0.67-beta
Published
Shared angular components for Indigina projects.
Downloads
15
Readme
@indigina/angular
This library contains shared angular components for Indigina projects.
Table of Contents
Install
Before installing.
The library depends for packages next versions: @ngx-translate ">12.0.0" and ngx-clipboard ">12.0.0".
If your application depends on the following package versions below the recommended ones, you should update the packages or simply delete them in "package.json" file, in which case the latest version of the packages will be installed.
Make sure your package.json file contains packages of the recommended version.
To install the package you'll need enter command at terminal
npm i @indigina/angular --saveOpen your module file e.g. app.module.ts and update imports array:
import { IndiginaModule } from '@indigina/angular';
import { ReactiveFormsModule } from '@angular/forms';
...
imports: [
...
IndiginaModule,
ReactiveFormsModule,
...
]Also, you need to setup the routes and import RouterModule. How to Setup
Open your global style file for application e.g. styles.css and add the following:
@import @indigina/angular/assets/indigina-theme.cssImportant notes:
The @indigina/angular provides the TranslationModule from @ngx-translate package (List of provided packages). You can use translate pipe without any additional includes in your app.
The @indigina/angular also provides TranslateSettingsService for set or get current locale See more.
For setup TranslationModule see Library Configuration
Library Configuration
For configure library you must use a IndiginaConfiguration interface
IndiginaConfiguration abstract class is provided for @indigina/angular library configuration.
IndiginaConfiguration class overview
| Param Name | Required | Type | Description | | ----------- | -------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | langs | no | TranslateLoader | The Translate module config. If you provide langs then @indigina/angular use the factory config, fo more information see original documentation. And see an example of Setup TranslationModule | | appSettings | no | AppSettings | The basic Application settings for working with server endpoint. |
Setup TranslationModule
For setup TranslationModule you needs to push the TranslateLoader to library, for example open your module file e.g. app.module.ts and update next:
...
const langs = {
'en' = {
UserName: 'User Name',
},
'ru' = {
UserName: 'Имя пользователя',
},
getTranslations(lang: string): Observable<any> {
if (Object.keys(this).includes(lang)) {
return of(this[lang]);
}
return of(this['en']);
}
}
...
imports: [
...
IndiginaModule.forRoot({ langs })
...
]Setup AppSettings
To use the HttpService and the AppToastrService you need to setup library with appSettings. For setup library to use provided services, you need to push AppSettings to library, for example open your module file e.g. app.module.ts and update next:
...
const appSettings = {
apiUrl: 'http://localhost:8080/',
accountUrl: 'http://localhost:3000/signin/',
toastrTimeOut: 3000
}
...
imports: [
...
IndiginaModule.forRoot({ appSettings })
...
]Components
Tree-View Component
Selector: tree-view
This component shows any type of content (XML, JSON) as a tree. The text data will be rendered inside the <pre> tag.
The component accepts input parameters:
- [data: string] - the data to view
- [maxTextLength: number] (optional) - the maximum text length that will be displayed, otherwise hidden and expand button is shown (default is 1200)
- [maxRootItems: number] (optional) - the maximum root nodes that will be displayed, otherwise hidden and expand button is shown (default is 10)
Tree-View Component Usage:
<tree-view [data]="data"></tree-view>
<tree-view [data]="data" [maxRootItems]="15"></tree-view>Side-Menu Component
Selector: side-menu
This component displays a menu. Used input parameter [items] with type MenuItem[]:
MenuItem type overview
| Param name | Required | Type | Description | | ------------- | -------- | ---------- | ------------------------------------------------------------------------------------------- | | text | yes | string | Text to show. It will be translated by translate pipe inside (@ngx-translate package) | | url | no | string | Use for external url link | | link | no | string | Use for internal url route | | iconClass | no | string | The class of icon. For exapmle: 'fa fa-dashboard' | | expanded | no | boolean | You can set expand flag manually. Child elements are displayed if flag is set to true | | items | no | MenuItem[] | Collection of child menu items |
Side-Menu Component Usage
Inside the template class
<side-menu [items]="items">Inside your component class
public items: MenuItem[];
...
this.items = [
{
text: 'Home',
iconClass: 'fa fa-home',
link: '/'
},
{
text: 'Management',
iconClass: 'fa fa-dashboard',
items: [
{
text: 'Users',
iconClass: 'fa fa-user',
link: '/users',
},
{
text: 'Roles',
iconClass: 'fa fa-user-plus',
link: '/users/roles',
},
]
}
];Form Components
FormGroupWithErrors
This is an extension of FormGroup class which provides the additional public methods:
Get control by name.
getControl(name: string): AbstractControl;
Sets errors by control names
applyServerErrors( error: {title?: string, errors: {[key: string]: string[]}}, form?: FromGroupWithErrors ): void;
- where form - target form class (default is this )
General-Errors Component
This component shows the general errors for FormGroup. Provides a public method:
setErrors(errors: string): void;Used input parameters:
- [form: FormGroup] - FormGroup to set the general errors.
FieldInput Component
Overview
Selector: field-input Basically, this is extended angular FormControl Class, that shows input HTML Element with label and supports validators (like required etc.).
Used input parameters:
- [labelKey: string] - the text for label and input placeholder. This value will be translated by translate pipe inside (@ngx-translate package)
- [fieldName: string] - the name of input
- [disabled: boolean] - allows to dynamically control the disablement of an input field
This component may use only inside form-group directive.
Usage
<field-input fieldName="userName" labelKey="Dto.UserName" required>NumberInput Component
Overview
Selector: number-input Class extended of FieldInput Component for number inputs. It has all inputs and validators inherent to FieldInput. FormControl value for this input has number type.
Additional input parameters:
- [isPositive: boolean] - allows to set only positive numbers (by default has false value).
This component may use only inside form-group directive.
Usage
<number-input fieldName="userName" labelKey="Dto.UserName" required>Debounce Directive
Selector: [appDebouce]
This directive is applicable to input elements.
This directive adds a delay and emits output Event debounceKeyup with input data.
Used input parameters:
- debounceTime - time to delay in ms (default is 500)
Usage
<input appDebouce (debounceKeyup)="search($event.target.value)" />Services
TranslateSettingsService
This service provides public methods for managing the current locale for an application.
Public Methods Provided:
- getLocales(): {name: string, code: string} - returns a list of supported languages
- getLocale(): string - returns the current locale code
- setLocale(locale: string): void - sets input locale code as current and switch TranslateModule to current
HttpService
This service provides public methods for get any content from server endpoint.
Important Notice:
This service require AppToastrService to configure Library for apiUrl see the Configure Library section
Standard Error Handling
All public methods provided by HttpService have standard error handling based on Http Status codes.
Exceptional case:
When the service receives a connection error then shows a toast message from the HttpErrorResponse class.
Error Handle Actions
| Http Status Code | Status Name | Action | | ---------------- | --------------------- | --------------------------------------------------------- | | 401 | Unauthorised | Shows toast message and navigate to 'home' route | | 403 | Frobidden | Shows toast message and navigate to 'forbidden' route | | 404 | NotFound | Shows toast message and navigate to '/' route | | 500 | Internal Server Error | Show toast message and returns null | | any | | throws error |
Public Methods Provided:
- get<T>(path: string): Promice<T> - make a GET request and return a response.
- post<T>(path: string, data: T): Promice<T> - make a POST request with data and return a response.
- put<T>(path: string, data: T): Promice<T> - make a PUT request with data and return a response.
- delete(path: string): Promice<object> - make a DELETE request to endpoint and return a response.
*path - is target endpoint without a basic apiUrl part
AppToastrService
This service provides a public methods to show toast messages.
Important Notice:
This service require to configure Library for default toastrTimeOut see the Configure Library section
Public Methods Provided:
- showError(message: string, title: string = 'Error'): void - shows the stylized error message
- showSuccess(message: string, title: string = ''): void - shows the stylized success message
Models
AppSettings
Type: abstract class
Extends: -
Description: The model for configuration HttpService and AppToastrService.
Overview
| Prop name | Required | Type | Description | | ------------- | -------- | ------ | ----------------------------------- | | apiUrl | yes | string | The base endpoint server url | | accountUrl | yes | string | The url to account server | | toastrTimeOut | yes | number | Timeout to auto close toast message |
CustomHttpErrorResponse
Type: declare class
Extends: HttpErrorResponse (from @angular/common/http)
Description: Add title property to HttpErrorResponse Type.
Overview
| Prop name | Required | Type | Description | | --------- | -------- | ------ | ----------- | | title | yes | string | The title |
CustomHttpErrorResponse
Type: enum
Extends: -
Description: Enum for http codes.
Overview
| Key | Value | | ------------------- | ----- | | BadRequest | 400 | | Forbidden | 403 | | InternalServerError | 500 | | NotFound | 404 | | OK | 200 | | Unauthorized | 401 |
HttpMethods
Type: const : NamedModel[]
Extends: -
Description: - .
Overview
| id | name | | ------ | ------ | | POST | POST | | PUT | PUT | | GET | GET | | DELETE | DELETE |
IdentifiedModel
Type: interface
Extends: -
Description: Declare id field.
Overview
| Prop Name | Required | Type | | --------- | -------- | ------ | | id | yes | string |
NamedModel
Type: interface
Extends: IdentifiedModel
Description: Declare id and name fields.
Overview
| Prop Name | Required | Type | | --------- | -------- | ------ | | id | yes | string | | name | yes | string |
IndiginaConfiguration
Type: abstract class
Extends: -
Description: Interface for configuration @indigina/angular library.
Overview
| Prop Name | Required | Type | Description | | --------- | -------- | --------------------------- | ---------------------------------- | | langs | no | TranslateLoader | Configuration for Translate Module | | name | no | AppSettings | Basic application environment |
Language
Type: interface
Extends: -
Description: -
Overview
| Prop Name | Required | Type | Description | | --------- | -------- | ------ | ------------------- | | name | yes | string | Language name | | code | yes | string | Language identifier |