Tuain-ng-forms-lib

Angular library to support Tuain Framework Forms operation.

Installation

Use the package manager npm to install the library in your Angular 9 application

npm install tuain-ng-forms-lib

Usage

Import the library module in your own module, and include it in your imports and exports if you need to use it with your own components in other application modules.

import { TuainNgFormsLibModule } from  'tuain-ng-forms-lib';

...
@NgModule({
imports: [
...
TuainNgFormsLibModule,
...,
],
declarations: [
...
],
exports: [
...
TuainNgFormsLibModule,
...
],
})

Public API

Tuain-ng-forms-lib expose a series of components and services to provide base clases to build forms in Angular applications following the Tuain Platforms standard behavior. The elements exposed by the API are described below.

| Element | Name | | ------ | ------ | | Component | ActionComponent | | Component | FieldComponent | | Component | PasswordComponent | | Component | ElementComponent | | Component | FormErrorComponent | | Component | FormHeaderComponent | | Component | SectionComponent | | Component | SubSectionComponent | | Component | LibTableFilterComponent | | Component | LibTablePagerComponent | | Component | LibTableRecordActionComponent | | Component | LibTableRecordFieldComponent | | Component | LibTableComponent | | Component | BasicFormComponent | | Service | LibFileManagementService | | Service | LibFormManagerService | | Service | IconDictionaryService |

Components

These components can be customized in your own application using inheritance to define your own components that behaves like these base components but with your own custom templates.

ActionComponent

This componet allows to create elements in a form to launch the execution of an action present in the form definition.

Inputs

This component allows to receive the following information

| Input Name | Description | | --- | ----------- | | actionObjec | Defines the action object of the form | | currentMode | Defines the current state of the form in order to define if the element can be visible or actionable | | busy | Defines in the form is makinh an exclusive process that prevents the action execution | | relatedField | Describe the field object related with this action | | style | Define a style attribute for the action | | showLabel | Define if the action shows it's label

Methods

The action component has the following methods.

• activate: Allows to activate the action
• icon: Returns the icon name of the action
• isVisible: Informs if the action is visible in the form

FieldComponent

Inputs

This component allows to receive the following information

| Input Name | Description | | --- | ----------- | | fieldObject | | | currentMode | |

Methods

The field component has the following methods.

• focus: Allows to focus on the native element of the field, usig the subclass method
• onInputChange: Allows to link the change on the native element with the form manager behavior
• onChangeContent: Allows to link the typing on the native element with the form manager behavior
• onShowInfo: Allows to link the show infor request on the component custom template with the form event handler defined to support the respective action request.
• numberInputValidation: Allows to use the number input validation to restrict the typing

ElementComponent

Inputs

This component allows to receive the following information

| Input Name | Description | | --- | ----------- | | element | | | formManager | |

FormErrorComponent

Inputs

This component allows to receive the following information

| Input Name | Description | | --- | ----------- | | errorTitle | | | errorMessage | | | errorType | |

FormHeaderComponent

Inputs

This component allows to receive the following information

| Input Name | Description | | --- | ----------- | | formManager | | | icon | | | goBackAction | | | showTitle | | | headerActions | |

Ouputs

Como salidas de este componente se genera el siguiente evento que permite determinar que desde el encabezado se solicita al formulario cerrar su operación y regresar al formulario previo.

| Input Event | Description | | --- | ----------- | | goBackEvent | |

SectionComponent

Inputs

This component allows to receive the following information

SubSectionComponent

Inputs

This component allows to receive the following information

| Input Name | Description | | --- | ----------- | | sectionObject | | | formManager | |

LibTableFilterComponent

Inputs

This component allows to receive the following information

| Input Name | Description | | --- | ----------- | | subSection | | | showHeader | | | formManager | |

LibTablePagerComponent

Inputs

This component allows to receive the following information

| Input Name | Description | | --- | ----------- | | table | | | visiblePages | | | pagesGroup | |

Outputs

| Output Event | Description | | --- | ----------- | | pageChanged | |

LibTableRecordActionComponent

Inputs

This component allows to receive the following information

LibTableRecordFieldComponent

Inputs

This component allows to receive the following information

| Input Name | Description | | --- | ----------- | | fieldCode | | | fieldType | | | recordData | |

LibTableComponent

Inputs

This component allows to receive the following information

| Input Name | Description | | --- | ----------- | | table | | | tableRecords | | | currentMode | | | waiting | |

Outputs

This component allows to generate the following events to his container

| Output Event | Description | | --- | ----------- | | tableActionActivated | | | tableStartGetData | |

BasicFormComponent

Methods

This component is provides as the base class to define any form in the Angular application as a super-class to provide all basic form operation with a full set of methods to allow make any objects access and modifications.

General form operation methods

This set of methods are oriented to access and modify general form attributes and configuration.

| Method Name | Description | | --- | ----------- | | supportState | Informs if a form supports the operation on a particular state | | supportModedeprecated | Informs if a form supports the operation on a particular state| | getTitle | Returns de form title | | cleanData | Cleand all fields and tables | | displayActionServerError | Show the error after the execution of the backend portion of an action| | displayValidationServerError | Show the error after the execution of the backend portion of a field validation | | showModalDialog | Shows a customized modal dialog| | openUploadDialog | Shows a standar file upload modal dialog| | goBackForm | Change the route of the application to go back to previous form| | goToSubPage | Request a new route to be displayed | | setError | Define the global form error| | get formManager | Returns the object that supports the data and structure of the form| | resetError | Clear the global error form object| | getErrorType | Returns the global form error type | | getErrorMessagedeprecated | Returns the global form error message | | getErrorDetaildeprecated | Returns the global form error detail | | getErrorCode | | Returns the global form error code | | get errorMessage | Returns the global form error message | | get errorDetail | Returns the global form error detail | | getCurrentState | Return the current state | | getCurrentModedeprecated | Return the current state | | getSubject | Return the subject id of the form | | getformSubjectdeprecated | Return the subject id of the form | | errorOccured| Return if there is an error | | changeState | Modify the current state |

Fields related methods

This set of methods allow subclass to access and modify fields in the form.

| Method Name | Description | | --- | ----------- | | getFields | Returns the form fields | | getField | Returns a form field object based on its name| | enableField | Set an status attribute of the field in order to be editable| | disableField | Set an status attribute of the field in order prevent edition | | getFieldValue | Returns the value of a field | | getFieldOptions | Returns an array with all posible values of the field with a description text| | setFieldValue | Change the current value of a field | | setFieldErrorMessage | Defines an error message for a field | | setFieldOptions | Define the posible values of the field with an array of values and description text | | setFieldRequired | Change an status attribute of the field to determine if it is required | | applyProcessToFieldSet | Execute a process on all the fields specified in an array, section or sub-section. If the fields are not specified, the execition will be over the whole set of fields in the form (processFunc, fieldArray?, sectionCode?, subSectionCode?)| | cleanFields | Clean all the fields specified in an array, section or sub-section using their default value. If the fields are not specified, the execition will be over the whole set of fields in the form (fieldArray?, sectionCode?, subSectionCode?)| | getRequiredFields | Obtain all the required fields specified in an array, section or sub-section using their default value. If the fields are not specified, the execition will be over the whole set of fields in the form (fieldArray?, sectionCode?, subSectionCode?)| | getRequiredEmptyFields | Obtain all the required and empty fields specified in an array, section or sub-section using their default value. If the fields are not specified, the execition will be over the whole set of fields in the form (fieldArray?, sectionCode?, subSectionCode?)| | getChangedFields | Obtain all the fields that changed since the last backend refresh over a field set specified in an array, section or sub-section using their default value. If the fields are not specified, the execition will be over the whole set of fields in the form (fieldArray?, sectionCode?, subSectionCode?)| | getFieldsWithValidationIssues | Obtain all the fields that has validation errors over a field set specified in an array, section or sub-section using their default value. If the fields are not specified, the execition will be over the whole set of fields in the form (fieldArray?, sectionCode?, subSectionCode?)| | tagFieldsWithError | Set an error mesagge for all the fields specified in an array, section or sub-section using their default value. If the fields are not specified, the execition will be over the whole set of fields in the form (errorMessage, fieldArray?, sectionCode?, subSectionCode?)| | cleanErrorFields | Clean the error on all the fields specified in an array, section or sub-section using their default value. If the fields are not specified, the execition will be over the whole set of fields in the form (fieldArray?, sectionCode?, subSectionCode?)| | showLabelFields | Show the label on all the fields specified in an array, section or sub-section using their default value. If the fields are not specified, the execition will be over the whole set of fields in the form (fieldArray?, sectionCode?, subSectionCode?)| | hideLabelFields | Hide the label on all the fields specified in an array, section or sub-section using their default value. If the fields are not specified, the execition will be over the whole set of fields in the form (fieldArray?, sectionCode?, subSectionCode?)| | enableFields | Enable for edition all the fields specified in an array, section or sub-section using their default value. If the fields are not specified, the execition will be over the whole set of fields in the form (fieldArray?, sectionCode?, subSectionCode?)| | disableFields | Disable for edition all the fields specified in an array, section or sub-section using their default value. If the fields are not specified, the execition will be over the whole set of fields in the form (fieldArray?, sectionCode?, subSectionCode?)| | showFields | Show all the fields specified in an array, section or sub-section using their default value. If the fields are not specified, the execition will be over the whole set of fields in the form (fieldArray?, sectionCode?, subSectionCode?)| | hideFields | Hide all the fields specified in an array, section or sub-section using their default value. If the fields are not specified, the execition will be over the whole set of fields in the form (fieldArray?, sectionCode?, subSectionCode?)| | showFieldInfo | Show help information related with a field | | addFieldInputValidation | (fields, callbackMethod)| | addFieldValidationStart | Defines a callback function to be triggered when a field change its content in order to be validated. The returned value of this callback defines if the process must continue in the backend| | addFieldValidationFinish | Defines a callback function to be triggered when the field validation process returns from the backend portion execution in order to be completed | | startFieldInputValidation | Defines a callback function to be triggered when a field receive any input and is change is not complete, so the user typing can be verified and validated. This process do not have any backend process by default | startFieldValidation | Start the field validation process| | startServerFieldValidation | Trigger the execution of a field validation, starting on the backend portion without the first callbacks execution|

Actions related methods

This set of methods allow subclass to access and modify actions in the form.

| Method Name | Description | | --- | ----------- | | getHeaderActions | Returns the form actions defined to be placed on the form header| | getAction | Returns a form action object based on its name| | showAction | Change the visibility of an action to be displayed based on its name| | hideAction | Change the visibility of an action to be hidden based on its name| | showActions | Change the visibility of an action set to be displayed based on an array of names| | hideActions | Change the visibility of an action set to be hidden based on an array of names| | enableAction | Modify the status of an action to be available for execution| | disableAction | Modify the status of an action to prevent execution| | enableActions | Modify the status of an actionset to be available for execution based on an array of names| | disableActions | Modify the status of an action to prevent execution based on an array of names| | addActionMethodStart | Defines a callback function to be triggered when an action is requested. The returned value of this callback defines if the process must continue in the backend| | addActionMethodFinish | Defines a callback function to be triggered when an action returns from the backend portion execution in order to be completed | | startAction | Start the execution of an action, starting with the initial callbacks, continuing in the backend if former callbacks were ok and execuing the after backend callbacks| | startServerAction | Trigger the execution of an action, starting on the backend portion without the first callbacks execution|

Tables related methods

This set of methods allow subclass to access and modify tables in the form.

| Method Name | Description | | --- | ----------- | | getTables | Returns all form tables | | getTable | Returns a form table object based on its name | | showTable | Change the visibility of a table to be displayed based on its name | | hideTable | Change the visibility of a table to be hidden based on its name| | showTables | Change the visibility of a table set to be displayed based on an array of names| | hideTables | Change the visibility of a table set to be hidden based on an array of names| | cleanTable | Delete the content of a table | | getTableRecord | Returns an array with all records of a table| | displayTableServerError | Shows an error message with the result of a table action on the backend| | addTableActionStart | Defines a callback function to be triggered when an action of the table is requested. The returned value of this callback defines if the process must continue in the backend| | addTableActionFinish | Defines a callback function to be triggered when an action of the table returns from the backend portion execution in order to be completed | | addTableGetDataStart | Defines a callback function to be triggered when the table need to refresh or update its data as a consequence of pagination or any refresh request| | addTableGetDataFinish | Defines a callback function to be triggered when the table data refresh or update is executed on the backend| | startTableAction | Start the execution of a table action, starting with the callback actions, continue in the backend if former callbacks were ok and execute the after backend callbacks| | startTableServerAction | Trigger the execution of a table action, starting on the backend portion without the first callbacks execution| | startTableGetData | Start the execution of a table get data action, starting with the callback actions, continue in the backend if former callbacks were ok and execute the after backend callbacks| | startTableServerGetData | Trigger the execution of a table get data action, starting on the backend portion without the first callbacks execution|

Sections related methods

This set of methods allow subclass to access and modify fields in the form.

| Method Name | Description | | --- | ----------- | | getSections | Returns all form sections | | getSection | Returns the section object based on its name | | activateSection | Set a section as the active one based on its name | | activeSection | Returns the name of the active section | | getSubSection | Returns the sub-ection object based on the section name and subsection name | | getSectionsTitles | Returns an array with all section titles | | showSection | Change the visibility of a section to be displayed based on its name | | hideSection | Change the visibility of a section to be hidden based on its name | | showSections | Change the visibility of a section set to be displayed based on an array of names| | hideSections | Change the visibility of a section set to be hidden based on an array of names| | showSubSection | Change the visibility of a sub-section to be displayed based on the section name and subsection name| | hideSubSection | Change the visibility of a sub-section to be hidden based on the section name and subsection name| | addSectionActivation | Defines a callback function to be triggered when any of the sections with name in the input array of section names is activated| | addSectionInactivation | Defines a callback function to be triggered when any of the sections with name in the input array of section names is inactivated| | checkSectionRequiredFields | Return a list of a section based on its name, with the required fields that are empty | | validateSectionConsistency | Verify that all required fields have value and don't have any validation errors |

Utilities and complex methods

This set of methods interact with multiple element types to provide tools to simplify complex but common operations in the forms.

| Method Name | Description | | --- | ----------- | | copyTableRecordToFields | Copy all columns in a table record to a set of fields using a mapping objec to relate column names with field names. If the mapping object is not present, look for fields with same names| | defineEditionTable | Configure an object to copy fields, enable edition, hide fields and actions to operate table and fields for records edition|

License

MIT