@indigina/kendo v1.2.71

@indigina/kendo

The library contains shared components for Indigina projects.

Important notice:

The library exports all included packages, which means you can import any dependent package of the '@indigina/kendo'.

Table of Contents

1. Install

2. Configuration

   • Complete Library Configuration

3. Components

   • AccountMenu Component

   • Form Components

     • FormGroupWithErrors

     • General-Errors Component

     • FieldInput Component

     • NumberInput Component

   • LanguageSelector Component

   • Widget Components

     • ActivityFilter Component

     • ConfirmDialog Component

     • CurrentTimezone Component

     • EntityList Component

     • EntityEdit Component

     • ExcelExportButton Component

     • FooterBar Component

     • ModalWindow Component

     • MulticheckFilter Component

     • TopBar Component

   • Side-Menu Component

   • Tree-View Component

4. Directives

   • Debounce Directive

   • RequirePermission Directive

5. Services

   • AccountService

   • ActivityFilterService

   • AppToastrService

   • BaseAccountService

   • EntityService

   • HttpService

   • PermissionsService

   • TranslateSettingsService

6. Models

   • ActivityFilter

   • AppSettings

   • CustomFilter

   • CustomFilterElement

   • CustomHttpErrorResponse

   • FieldTypes

   • FilterTargets

   • HttpCodes

   • HttpMethods

   • IdentifiedModel

   • IndiginaConfiguration

   • Language

   • Member

   • MemberBase

   • MemberTypes

   • NamedModel

   • OidcSettings

   • Operators

   • Page

   • Permissions

   • PermissionTypes

7. Provided Packages

8. Exports Table

Install

Before installing.

The library depends on the next packages: @ngx-translate, ngx-clipboard, angular-oauth2-oidc, angular-oauth2-oidc-jwks, @microsoft/signalr and includes most of the kendo.

If your application depends on the following packages, you should remove them from "package.json" file.

Make sure your package.json file does not contain the packages '@indigina/kendo' depends on.

To install the package you'll need to enter the command at the terminal:

npm i @indigina/kendo@latest --save

Open your module file e.g. app.module.ts and update imports array:

import { IndiginaModule, KendoModule } from '@indigina/kendo';
import { ReactiveFormsModule } from '@angular/forms';

...

imports: [
    ...
    IndiginaModule,
    KendoModule,
    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/kendo/assets/indigina-theme.css
@import @indigina/kendo/assets/kendo-theme.css

The @indigina/kendo 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/kendo also provides TranslateSettingsService for set or get current locale See more.

For setup TranslationModule see Library Configuration

Library Configuration

To configure the library you must use an IndiginaConfiguration interface

IndiginaConfiguration abstract class is provided from @indigina/angular library configuration.

When you configure the '@indigina/kendo' then the config is passed to '@indigina/angular'.

For configure library you must use a IndiginaConfiguration interface

IndiginaConfiguration abstract class is provided for @indigina/angular library configuration.

IndiginaConfiguration class overview

Setup TranslationModule

For setup TranslationModule you need to pass the TranslateLoader to the 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: [
...
KendoModule.forRoot({ langs })
...
]

Setup AppSettings

To use the most of the services you need to setup a library with appSettings. For that you need to pass 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: [
...
KendoModule.forRoot({ appSettings })
...
]

Complete library configuration

To take full advantage of the library and use environments for separate builds e.g. development/production, you need to setup the library as follows:

1. Open your environment file e.g. environments/environmet.ts and update following:

   export const environment = {
     production: false,
     appSettings: {
       apiUrl: 'http://localhost:8080/',
       accountUrl: 'https://sso.localhost:8000/',
       toastrTimeOut: 3000,
       },
   };

2. Open your module file e.g. app.module.ts and update following:

       import { environment } from '../environments/environment';
   
       ...
   
       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: [
       ...
       KendoModule.forRoot({ appSettings: environment.appSettings, langs })
       ...
       ]

Components

AccountMenu Component

Overview

Selector: account-menu

Thats already included in TopBar Component.

This component shows menu items for current user:

• User info - shows avatar and username.
• Change Language - Shows LanguageSelector Component for change current culture.
• Account - Link to accountUrl from IndiginaConfiguration provided by @indigina/angular module.
• Logout - Link on the server-endpoint to logout.

The component accepts input parameters:

• user: Member - the current user. Member description.

Usage:

<account-menu [user]="currentUser"></account-menu>

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>

LanguageSelector Component

Overview

Selector: language-selector

This component displays a window with a list of available languages. And lets you choose one.

Used input parameters:

• visible: boolean - sets the show/hide window

Output parameters:

• visibleChange: boolean - emits event when visible property switched.

Usage:

<language-selector [(visible)]="languageSelectorVisible"></language-selector>

Widget Components

ActivityFilter Component

Overview

Selector: activity-filter

Component to show set of UI filters. This component works with ActivityFilterService. Can render content inside tag declaration.

Used input parameters:

• showArchiveSwitcher: boolean - set true to show switcher.
• showSearhText: boolean - - set true to show search text field input.
• customFilterElements: CustomFilterElement[] - set of CustomFilterElement
• filterService: ActivityFilterService - the filter service to work

Usage

<activity-filter
    [customFilterElements]="customFilterElements"
    [showSearhText]="false"
    [showArchiveSwitcher]="false"
    [filterService]="filterService"
>
    <span>Additional content</span>
</activity-filter>

ConfirmDialog Component

Overview

Selector: confirm-dialog

This component shows a modal dialog with Cancel and Confirm buttons.

You can control the component by the public method open

public open(content: string, callback () => void)

Arguments:

• content - content to show
• callback - called only when user press confirm button

Usage

You can create the component with confirm-dialog import

import { ConfirmDialogComponent } from '@indigina/kendo';

...

public dialog: ConfirmDialogComponent;

Then you can call the open method anywhere you need:

public confirmHandler() {
  // do something
}

public showDialog() {
  const content = this.translate.instant("Are you shure?")
  this.dialog(content, () => this.confirmHandler())
}

And in the template you need to include as follows:

<confirm-dialog #confirmDialog></confirm-dialog>

CurrentTimezone Component

Overview

Selector: current-timezone

This component shows current time zone.

Usage:

<current-timezone></current-timezone>

EntityList Component

Overview

Selector: entity-list

This component shows entities from the standard REST backend application that uses ODataQuery. The view is using the kendo-grid component.

The server backend base path is setup in the IndiginaConfiguration at the appSettings.apiUrl.

Used input parameters:

• service: IEntityService<NamedModel> - Service with data retrieval implementation. You can extend the exported abstract class EntityService with default implementation.
• filters: Array<FilterDescriptor | CompositeFilterDescriptor> - spicifies data filtration. You can getting more information about generic types on kendo-data-query npm.

• fields?: Field[] - field list to show from dataset. Field - Interface which describes:

  name	type	description
  name	string	the field name in the dataset.
  title	string	the title which shows in the header in data-grid column.
  sortable?	boolean	indicates if a column is sortable. Default is "true".
  position?	number	indicates columns order. "Name" coulumn position is 0.

• commands?: Command[] - array of custom, developer defined commands. Command - Interface which describes:

• rowClass?: (dataItem: NamedModel, index: number) => {} - calculates css classes based on a current dataItem.

Output parameters:

• filterChange: CompositeFilterDescriptor - emits event when filter is changed.

Usage:

<entity-list [service]="service"></entity-list>

EntityEditForm Component

Overview

Selector: entity-edit-form

The component shows specific edit form for single entity, for example: Selected entity in EntityList Component. It includes default save actions. Used like wrapper of form for entity.

Used input parameters:

• title: string - The title to show at top.
• adapter: IFormAdapter<IdentifiedModel> - accepts form adapter, see usage of EntityEdit Component

Usage:

<entity-edit-form title="User Details" [adapter]="adapter">
  <div *ngIf="form" [formGroup]="form">
    <field-input
    fieldName="userName"
    labelKey="Username"
    maxlength="200"
    required
  >

  ....

  </div>
</entity-edit-form>

EntityEdit Component

Overview

Selector: -

Thats abstract class which implements IFormAdapter. Used by EntityEditForm Component as adapter input attribute.

Declaration:

abstract class EntityEditComponent<T extends IdentifiedModel>

IdentifiedModel - Interface exported by @indigina/angular

Usage:

export class UserEditComponent extends EntityEditComponent<User> {
  constructor (service: UserDataService) {
    base(service);
  }
}

ExcelExportButton Component

Overview

Selector: excel-export-button

Basically, this is styled button component for default kendo-grid Excel Export Action.

This component used in EntityList Component by default.

Usage

<ng-template kendoGridToolbarTemplate>
  <excel-export-button></excel-export-button>
</ng-template>

FooterBar Component

Overview

Selector: footer-bar

Component to show standard Indigina styled footer.

Usage

<footer-bar>Footer Content</footer-bar>

ModalWindow Component

Overview

Selector: modal-window

This component shows a modal window with content provided from the inner content of the selector tag.

Used input parameters:

• callbackPath: string - the callback path to navigate when the window has closed.

Usage

For example, you have an UserProfileComponent with table of basic profile fields and you want to show detaled user profile by clicking the button. At first you need to add the following template at the end of UserProfileComponent:

    ...
    <router-outlet></router-outlet>

It is necessery to show the child component, suppose the DetailedUserProfileComponent.

The next step is to add route into children property of the parent component route configuration. Usualy the app-routing.module.ts file in your application. It can be done like this:

    ...
    {
        path: '/profiles',
        component: UserProfileComponent,
        children: [
            {
                path: ':id',
                component: DetailedUserProfileComponent,
            },
        ],
    },

And the last step is to add the following into DetailedUserProfileComponent template:

    <modal-window [callbackPath]="callbackPath">The content of modal window</modal-window>

For example, you can use '/' constant as callbackPath. That means that after the modal window has been closed, the router will navigate to '/',which is a root path of the application.

MulticheckFilter Component

Overview

Selector: multicheck-filter

Component provides nested filters as the list of the values of selected field to the kendo-grid.

Used input parameters:

• currentFilter: CompositeFilterDescriptor - the current kendo-grid filter
• data: NamedModel[] - list of values for field to can add to filter
• filterService: FilterService - service exported from kendo-angular-grid
• field: string - name of field to filter

Usage

<multicheck-filter
        field="Id"
        [filterService]="filterService"
        [currentFilter]="gridState.filter"
        [data]="users"
      >
</multicheck-filter>

TopBar Component

Overview

Selector: top-bar

Component display AccountMenu Component and SideMenu Component toggler.

Used input parameters:

• currentUser: Member - the current user for AccountMenu Component

Usage

<top-bar [currentUser]="user"></top-bar>

Side-Menu Component

Selector: side-menu

This component displays a menu. Used input parameter items with type MenuItem[]:

MenuItem type overview

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',
            },
        ]
    }
];

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 - the maximum text length that will be displayed, otherwise hidden and expand button is shown (default is 1200)
• maxRootItems: number - 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>

Directives

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)" />

RequirePermission Directive

Overview

Selector: requirePermission

This directive is shows element only when current user has specific permission.

Used input parameters:

• permissionType: PermissionTypes | PermissionTypes[] - specifies the permission type to check. See PermissionTypes.

• permissionCategory?: string - permission category to check.

Usage

<a [routerLink]="/link" requirePermission permissionType="Create">link</a>

Services

AccountService

This service extends of BaseAccountService and implements the isAdmin abstract method.

ActivityFilterService

This service provides current ActivityFilter and gridState by the subscription.

Public Methods Provided:

• reset() - Clearing currentFilter to default values with populating currentFilter and currentGridState.
• clearFilter() - Clearing currentFilter to default values without populating currentFilter and currentGridState.
• setFilter(filter: ActivityFilter) - Sets currentFilter from the filter values, without populating currentFilter and currentGridState.
• applyFilter(filter: ActivityFilter) - Sets currentFilter from the filter values, then populating currentFilter and currentGridState.
• setToday() - Sets dates for current day time range, then populating currentFilter and currentGridState.
• setTodayDates() - Sets dates for current day time range without populating currentFilter and currentGridState.
• setGridState(state: State) - Sets currentFilter from state, then populating currentFilter and currentGridState.

Public Properties Provided:

• currentFilter: ActivityFilter - store current filter
• currentGridState: State - store current gridState
• filter$ - Observable stream for subscription. Returns ActivityFilter
• gridState$ - Observable stream for subscription. Returns State

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

BaseAccountService

This is an abstract generic class of service that provides current user and initiates authentication flow. That service uses OAuthService from angular-oauth2-oidc for authentication.

Public Methods Provided:

• login() - initiates authentication flow
• logout() - allows current user to logout
• getCurrentUser(): Observable<Member> - returns current authenticated user, initiates authenticate if not authenticated
• abstract isAdmin(member: T): boolean - declares a method that indicates the user is admin.

EntityService

This is an abstract generic class which declares public methods for work with entities on server endpoint using REST.

Declaration:

export abstract class EntityService<T extends IdentifiedModel>
implements IEntityService<T> {
constructor(
  protected httpService: HttpService,
  protected endpoints: IEntityEndpoints
) {}

...

}

Where IEntityEndpoints - Interface which describe:

Public Methods Provided:

• getPage(state: State): Observable<Page<T>> - accept state of kendo-grid and returns paged result. See Page
• get(id: string): Observable<T> - get single entity from endpoint.
• delete(id: string): Observable<object> - delete entity by id.
• save(model: T): Observable<T> - create or modify entity.

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

Public Methods Provided:

• get<T>(path: string): Observable<T> - make a GET request and return a response.
• post<T>(path: string, data: T): Observable<T> - make a POST request with data and return a response.
• put<T>(path: string, data: T): Observable<T> - make a PUT request with data and return a response.
• delete(path: string): Observable<object> - make a DELETE request to endpoint and return a response.

*path - is target endpoint without a basic apiUrl part

PermissionsService

This service gets permissions from server endpoint.

Public Methods Provided:

• getAll(memberType: MemberTypes): Observable<Permissions> - get all permissions for selected member type. See MemberTypes
• getMine(): Observable<Permissions> - get permissions of the current user.

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

Models

ActivityFilter

Type: interface

Extends: -

Description: The model that stores UI filter.

Overview

AppSettings

Type: abstract class

Extends: -

Description: The model for configuration HttpService and AppToastrService.

Overview

CustomFilter

Type: interface

Extends: -

Description: The model that stores additional filter for UI.

Overview

CustomFilterElement

Type: interface

Extends: -

Description: The model that stores additional visible filter component.

Overview

CustomHttpErrorResponse

Type: declare class

Extends: HttpErrorResponse (from @angular/common/http)

Description: Add title property to HttpErrorResponse Type.

Overview

FieldTypes

Type: enum

Extends: -

Description: Enum for type of renderable element.

Overview

FilterTargets

Type: enum

Extends: -

Description: Enum for setting how filter to affect.

Overview

HttpCodes

Type: enum

Extends: -

Description: Enum for http codes.

Overview

HttpMethods

Type: const : NamedModel[]

Extends: -

Description: - .

Overview

IdentifiedModel

Type: interface

Extends: -

Description: Declare id field.

Overview

IndiginaConfiguration

Type: abstract class

Extends: -

Description: Interface for configuration @indigina/angular library.

Overview

Language

Type: interface

Extends: -

Description: The model that store language info.

Overview

Member

Type: interface

Extends: MemberBase

Description: The model that store member info.

Overview

MemberBase

Type: interface

Extends: NamedModel from '@indigina/angular'

Description: The model that store basic member info.

Overview

MemberTypes

Type: enum

Extends: -

Description: Enum for member type.

Overview

NamedModel

Type: interface

Extends: - IdentifiedModel

Description: Declare name field with id field which inherits from IdentifiedModel.

Overview

OidcSettings

Type: interface

Extends: -

Description: The model that store basic config for OAuthService.

Overview

Operators

Type: enum

Extends: -

Description: Enum to set OData query-selection filter operator.

Overview

Page

Type: interface

Extends: -

Description: The model that store paged response for kendo-grid.

Overview

Permissions

Type: interface

Extends: -

Description: Model that store PermissionCategory as key and PermissionTypes as value

Overview

PermissionTypes

Type: enum

Extends: -

Description: Enum for permission type.

Overview

Provided packages

• @angular/platform-browser/animations
• @ngx-translate/core
• ngx-clipboard
• ngx-toastr
• angular-oauth2-oidc
• moment-timezone as momentTimezone const