UNPKG

ng-prime-tools

Version:

An advanced PrimeNG table for Angular

815 lines (649 loc) 26.3 kB
# NG Prime Tools An advanced PrimeNG tools library for Angular. ## Table of Contents - [Introduction](#introduction) - [Installation](#installation) - [Compatibility](#compatibility) - [Usage](#usage) - [pt-advanced-prime-table](#pt-advanced-prime-table) - [Inputs](#inputs) - [Outputs](#outputs) - [Example](#example) - [multi-search-criteria](#multi-search-criteria) - [Inputs](#inputs-1) - [Outputs](#outputs-1) - [Example](#example-1) - [FormBuilder](#formbuilder) - [Components](#components) - [Example](#example-2) - [Changelog](#changelog) - [License](#license) ## Introduction `ng-prime-tools` is a collection of advanced tools built on top of PrimeNG for Angular applications. To include the necessary steps for installing `ng-prime-tools` along with its dependencies, you can update the installation instructions as follows: ## Installation To install `ng-prime-tools` and its necessary dependencies, use the following commands: ```bash npm install ng-prime-tools npm install chart.js chartjs-plugin-datalabels ``` This ensures that all required libraries are properly installed and available for use in your project. ## Compatibility - **Angular Version**: 17.3.1 or higher - **PrimeNG Version**: 17.18.0 or higher ## Usage ### pt-advanced-prime-table To use the `pt-advanced-prime-table` component, follow these steps: 1. **Import the Module:** Import the `NgAdvancedPrimeTableModule` in your Angular module or standalone component. ```typescript import { NgAdvancedPrimeTableModule, TableColumn, TableTypeEnum } from "ng-prime-tools"; ``` 2. **Add the Component:** Add the `pt-advanced-prime-table` component to your template: ```html <pt-advanced-prime-table [columns]="columns" [data]="data" [hasSearchFilter]="true" [hasColumnFilter]="true" [isPaginated]="true" [totalRecords]="totalRecords" [isSortable]="true"></pt-advanced-prime-table> ``` 3. **Define the Inputs:** In your component, define the necessary inputs for the table: ```typescript import { Component, OnInit } from "@angular/core"; import { NgAdvancedPrimeTableModule } from "ng-prime-tools/pt-advanced-prime-table"; import { TableColumn } from "ng-prime-tools/models"; import { TableTypeEnum } from "ng-prime-tools/enums"; @Component({ selector: "app-root", standalone: true, imports: [NgAdvancedPrimeTableModule], templateUrl: "./app.component.html", styleUrls: ["./app.component.css"], }) export class AppComponent implements OnInit { columns: TableColumn[] = []; data: any[] = []; totalRecords: number = 0; ngOnInit(): void { this.columns = [ { title: "Name", code: "name", type: TableTypeEnum.STRING, isEditable: true, }, { title: "Date", code: "date", type: TableTypeEnum.DATE, isEditable: true, }, { title: "Amount", code: "amount", type: TableTypeEnum.AMOUNT, currency: "USD", isEditable: true, }, ]; this.data = [ { name: "John Doe", date: "11/06/2024", amount: 100 }, { name: "Jane Doe", date: "20/06/2024", amount: 200 }, ]; this.totalRecords = this.data.length; } } ``` ### Inputs - **data** (`any[]`): The data to be displayed in the table. - **columns** (`TableColumn[]`): The columns configuration for the table. - **totalRecords** (`number`): The total number of records. - **rowsPerPage** (`number[]`): The number of rows per page options for pagination. - **hasSearchFilter** (`boolean`): Whether the table has a global search filter. - **hasColumnFilter** (`boolean`): Whether the table has column-specific filters. - **isPaginated** (`boolean`): Whether the table is paginated. - **actions** (`any[]`): The actions available for the table rows. - **isSortable** (`boolean`): Whether the table columns are sortable. ### Outputs - **filter** (`EventEmitter`): Emitted when the table is filtered. - **search** (`EventEmitter<any>`): Emitted when a global search is performed. ### Example Here's a complete example of how to use the `pt-advanced-prime-table` component: ```typescript import { Component, OnInit } from "@angular/core"; import { CommonModule } from "@angular/common"; import { NgAdvancedPrimeTableModule } from "ng-prime-tools/pt-advanced-prime-table"; import { TableColumn } from "ng-prime-tools/models"; import { TableTypeEnum } from "ng-prime-tools/enums"; @Component({ selector: "app-root", standalone: true, imports: [CommonModule, NgAdvancedPrimeTableModule], templateUrl: "./app.component.html", styleUrls: ["./app.component.css"], }) export class AppComponent implements OnInit { columns: TableColumn[] = []; data: any[] = []; totalRecords: number = 0; ngOnInit(): void { this.columns = [ { title: "Name", code: "name", type: TableTypeEnum.STRING, isEditable: true, }, { title: "Date", code: "date", type: TableTypeEnum.DATE, isEditable: true, }, { title: "Amount", code: "amount", type: TableTypeEnum.AMOUNT, currency: "USD", isEditable: true, }, ]; this.data = [ { name: "ZAK JAAI", date: "11/06/2024", amount: 100 }, { name: "ZAK2 JAAI", date: "20/06/2024", amount: 200 }, ]; this.totalRecords = this.data.length; } } ``` ```html <pt-advanced-prime-table [columns]="columns" [data]="data" [hasSearchFilter]="true" [hasColumnFilter]="true" [isPaginated]="true" [totalRecords]="totalRecords" [isSortable]="true"></pt-advanced-prime-table> ``` ### multi-search-criteria To use the `multi-search-criteria` component, follow these steps: 1. **Import the Module:** Import the `MultiSearchCriteriaModule` in your Angular module or standalone component. ```typescript import { MultiSearchCriteriaModule, SearchCriteria, SearchCriteriaTypeEnum } from "ng-prime-tools"; ``` 2. **Add the Component:** Add the `multi-search-criteria` component to your template: ```html <multi-search-criteria [title]="'Multi-Criteria Search'" [criteria]="criteria" [data]="data" [mode]="'dynamic'" (filteredData)="onFilteredData($event)" (searchCriteria)="onSearchData($event)"></multi-search-criteria> ``` 3. **Define the Inputs:** In your component, define the necessary inputs for the criteria: ```typescript import { Component, OnInit } from "@angular/core"; import { CommonModule } from "@angular/common"; import { MultiSearchCriteriaModule, SearchCriteria, SearchCriteriaTypeEnum, FilterOption } from "ng-prime-tools"; @Component({ selector: "app-root", standalone: true, imports: [CommonModule, MultiSearchCriteriaModule], templateUrl: "./app.component.html", styleUrls: ["./app.component.css"], }) export class AppComponent implements OnInit { criteria: SearchCriteria[] = []; data: any[] = []; filteredData: any[] = []; totalRecords: number = 0; ngOnInit(): void { this.criteria = [ { title: "Name", code: "name", type: SearchCriteriaTypeEnum.STRING, }, { title: "Date Range", code: "dateRange", type: SearchCriteriaTypeEnum.DATERANGE, }, { title: "Amount", code: "amount", type: SearchCriteriaTypeEnum.AMOUNT, currency: "USD", }, { title: "Type", code: "type", type: SearchCriteriaTypeEnum.MULTISELECT, filterOptions: [ { label: "Invoice", value: "Invoice" }, { label: "Bill", value: "Bill" }, ], }, ]; this.data = [ { name: "ZAK JAAI", date: "11/06/2024", amount: 100, type: "Invoice" }, { name: "ZAK2 JAAI", date: "20/06/2024", amount: 200, type: "Bill" }, ]; this.filteredData = [...this.data]; this.totalRecords = this.data.length; } onFilteredData(filteredData: any[]): void { this.filteredData = filteredData; this.totalRecords = filteredData.length; } onSearchData(searchCriteria: { [key: string]: any }): void { console.log(searchCriteria); } } ``` ### Inputs - **title** (` string`): The title of the multi-search criteria panel. - **criteria** (`SearchCriteria[]`): The search criteria configuration. - **data** (`any[]`): The data to be filtered (used in static mode). - **mode** (`'static' | 'dynamic'`): The mode of the multi-search criteria component. - `'static'`: Filters the data directly within the component. - `'dynamic'`: Emits the search criteria to be handled externally (e.g., for server-side filtering). ### Outputs - **filteredData** (`EventEmitter<any[]>`): Emitted with the filtered data (only in static mode). - **searchCriteria** (`EventEmitter<{ [key: string]: any }>`): Emitted with the search criteria (only in dynamic mode). ### Example Here's a complete example of how to use the `multi-search-criteria` component in dynamic mode: ```typescript import { Component, OnInit } from "@angular/core"; import { CommonModule } from "@angular/common"; import { MultiSearchCriteriaModule, SearchCriteria, SearchCriteriaTypeEnum, FilterOption } from "ng-prime-tools"; @Component({ selector: "app-root", standalone: true, imports: [CommonModule, MultiSearchCriteriaModule], templateUrl: "./app.component.html", styleUrls: ["./app.component.css"], }) export class AppComponent implements OnInit { criteria: SearchCriteria[] = []; data: any[] = []; filteredData: any[] = []; totalRecords: number = 0; ngOnInit(): void { this.criteria = [ { title: "Name", code: "name", type: SearchCriteriaTypeEnum.STRING, }, { title: "Date Range", code: "dateRange", type: SearchCriteriaTypeEnum.DATERANGE, }, { title: "Amount", code: "amount", type: SearchCriteriaTypeEnum.AMOUNT, currency: "USD", }, { title: "Type", code: "type", type: SearchCriteriaTypeEnum.MULTISELECT, filterOptions: [ { label: "Invoice", value: "Invoice" }, { label: "Bill", value: "Bill" }, ], }, ]; this.data = [ { name: "ZAK JAAI", date: "11/06/2024", amount: 100, type: "Invoice" }, { name: "ZAK2 JAAI", date: "20/06/2024", amount: 200, type: "Bill" }, ]; this.filteredData = [...this.data]; this.totalRecords = this.data.length; } onFilteredData(filteredData: any[]): void { this.filteredData = filteredData; this.totalRecords = filteredData.length; } onSearchData(searchCriteria: { [key: string]: any }): void { console.log(searchCriteria); // Perform server-side search or any other external data fetching logic } } ``` ```html <multi-search-criteria [title]="'Multi-Criteria Search'" [criteria]="criteria" [data]="data" [mode]="'dynamic'" (filteredData)="onFilteredData($event)" (searchCriteria)="onSearchData($event)"></multi-search-criteria> <pt-advanced-prime-table [columns]="columns" [data]="filteredData" [hasSearchFilter]="true" [hasColumnFilter]="true" [isPaginated]="true" [totalRecords]="totalRecords" [isSortable]="true"></pt-advanced-prime-table> ``` ### FormBuilder The `FormBuilder` component is a powerful and flexible tool for dynamically generating forms with various input types. It allows you to create nested groups, manage validations, and customize the appearance and behavior of your forms. #### Components The `FormBuilder` leverages several input components to build comprehensive forms: - **`pt-check-box-input`**: A customizable checkbox input component. - **`pt-date-input`**: A versatile date input component supporting both single date and date range selections. - **`pt-dropdown`**: A dropdown input component for selecting from a list of options. - **`pt-form-builder`**: The form builder component that dynamically renders form fields. - **`pt-multi-select`**: A multi-select dropdown component for selecting multiple values from a list. - **`pt-number-input`**: A numeric input component with support for validation and formatting. - **`pt-switch-input`**: A switch input component, ideal for toggling settings. - **`pt-text-area-input`**: A text area input component for larger, multi-line text entries. - **`pt-text-input`**: A standard text input component with support for icons, placeholders, and validation. #### Example Below is an example of how to use the `FormBuilder` component to create a user registration form with various input fields: ```typescript import { Component, OnInit } from "@angular/core"; import { CommonModule } from "@angular/common"; import { ReactiveFormsModule } from "@angular/forms"; import { FormFieldGroup, FormInputTypeEnum, ButtonColorEnum, FormButton, PTFormBuilderModule, InputValidationEnum, FormTextField, FormCheckBoxField, FormSwitchField, FormNumberField, FormDateField, FormDropdownField, FormMultiSelectField, FormTextAreaField } from "ng-prime-tools"; @Component({ selector: "app-form-builder-tester", standalone: true, imports: [CommonModule, ReactiveFormsModule, PTFormBuilderModule], templateUrl: "./form-builder-tester.component.html", styleUrls: ["./form-builder-tester.component.css"], }) export class FormBuilderTesterComponent implements OnInit { mainGroup: FormFieldGroup = { fields: [], groups: [] }; buttons: FormButton[] = []; ngOnInit() { this.initializeSettings(); } initializeSettings() { this.initializeMainGroup(); this.initializeButtons(); } initializeMainGroup() { this.mainGroup = { groups: [this.createNameGroup(), this.createSubscriptionGroup(), this.createAgeGroup(), this.createBirthdateGroup(), this.createDateRangeGroup(), this.createAmountGroup(), this.createCountryGroup(), this.createHobbiesGroup(), this.createDescriptionGroup()], }; } createNameGroup(): FormFieldGroup { return { fields: [ { type: FormInputTypeEnum.TEXT, label: "First Name", name: "firstName", required: true, placeholder: "Enter your first name", iconClass: "pi pi-user", iconPosition: "left", minLength: 3, maxLength: 10, inputValidation: InputValidationEnum.ONLY_LETTERS, } as FormTextField, { type: FormInputTypeEnum.TEXT, label: "Last Name", name: "lastName", required: true, placeholder: "Enter your last name", } as FormTextField, ], }; } createSubscriptionGroup(): FormFieldGroup { return { fields: [ { type: FormInputTypeEnum.CHECKBOX, label: "Subscribe", name: "subscribe", required: true, } as FormCheckBoxField, { type: FormInputTypeEnum.SWITCH, label: "Active", name: "active", required: true, } as FormSwitchField, ], }; } createAgeGroup(): FormFieldGroup { return { fields: [ { type: FormInputTypeEnum.NUMBER, label: "Age", name: "age", minValue: "18", maxValue: "40", required: true, errorText: "Age is required", placeholder: "Enter your age", } as FormNumberField, ], }; } createBirthdateGroup(): FormFieldGroup { return { fields: [ { type: FormInputTypeEnum.DATE, label: "Birthdate", name: "birthdate", required: true, dateFormat: "dd/mm/yy", hourFormat: "24", placeholder: "Select your birthdate", dateInputType: "date", } as FormDateField, ], }; } createDateRangeGroup(): FormFieldGroup { return { fields: [ { type: FormInputTypeEnum.DATE, label: "Date Range", name: "daterange", required: true, placeholder: "Select date range", dateInputType: "range", } as FormDateField, ], }; } createAmountGroup(): FormFieldGroup { return { fields: [ { type: FormInputTypeEnum.AMOUNT, label: "Amount", name: "amount", minValue: "100", maxValue: "1000", required: true, currency: "MAD", iconPosition: "right", placeholder: "Enter the amount", decimalDigits: 3, numberFormat: "fr-FR", disabled: true, } as FormNumberField, ], }; } createCountryGroup(): FormFieldGroup { return { fields: [ { type: FormInputTypeEnum.SELECT, label: "Country", name: "country", options: [ { label: "USA", value: "usa" }, { label: "Canada", value: "canada" }, ], required: true, placeholder: "Select your country", } as FormDropdownField, ], }; } createHobbiesGroup(): FormFieldGroup { return { fields: [ { type: FormInputTypeEnum.MULTISELECT, label: "Hobbies", name: "hobbies", options: [ { label: "Reading", value: "reading" }, { label: "Travelling", value: "travelling" }, { label: "Cooking", value: "cooking" }, ], required: true, placeholder: "Select your hobbies", } as FormMultiSelectField, ], }; } createDescriptionGroup(): FormFieldGroup { return { fields: [ { type: FormInputTypeEnum.TEXTAREA, label: "Description", name: "description", rows: 5, required: true, errorText: "Description est obligatoire !", placeholder: "Enter a description", minLength: 10, maxLength: 20, iconClass: "pi pi-dollar", iconPosition: "right", disabled: true, } as FormTextAreaField, ], }; } initializeButtons() { this.buttons = [ { text: "Custom Action", action: this.customAction, color: ButtonColorEnum.SUCCESS, icon: "pi pi-check", }, { text: "Submit", color: ButtonColorEnum.PRIMARY, isSubmit: true }, { text: "Clear", color: ButtonColorEnum.SECONDARY, isClear: true }, ]; } customAction() { console.log("Custom action executed"); } onFormSubmit(formData: { [key: string]: any }) { console.log("Form submitted with data:", formData); } } ``` ## Changelog ### Version 1.0.31 - Release Date: 16/04/2025 - pt-advanced-table : Fixing the filters with asynchronous data and composed types. ### Version 1.0.30 - Release Date: 10/04/2025 - fixing the disabling btn in pt-login ### Version 1.0.28 - 1.O.29 - Release Date: 05/04/2025 - Changing style of pt-button when disabled ### Version 1.0.27 - Release Date: 27/03/2025 - adding pt-notifier - fixing pt-dialog with ameliorations ### Version 1.0.26 - Release Date: 11/03/2025 - fixing pt-dialog with ameliorations ### Version 1.0.25 - Release Date: 06/03/2025 - adding pt-chart-comparison ### Version 1.0.24 - Release Date: 05/03/2025 - adding pt-group - adding pt-metric-panel ### Version 1.0.23 - Release Date: 03/03/2025 - fix NUMBER type in advanced table ### Version 1.0.22 - Release Date: 03/03/2025 - adding styles for composed types in advanced table ### Version 1.0.21 - Release Date: 28/02/2025 - fix composed types in advanced table ### Version 1.0.20 - Release Date: 24/02/2025 - fixing error message in login page ### Version 1.0.19 - Release Date: 18/02/2025 - fixing scroll bar pt-card ### Version 1.0.18 - Release Date: 22/01/2025 - fixing search in sidebar position - pt-card : adding background color transparency and pattern image transparency ### Version 1.0.17 - Release Date: 21/01/2025 - Adding positions for login page ### Version 1.0.16 - Release Date: 19/01/2025 - fix bug z-index fancy menu ### Version 1.0.15 - Release Date: 19/11/2024 - adding pt-line-chart ### Version 1.0.14 - Release Date: 15/11/2024 - fix metric-card 'fixedWidth' param - adding design for icons in metric cards - fix issue having multiple charts using pt-chart ### Version 1.0.13 - Release Date: 12/11/2024 - fix menu z-index - adding parametrable toggle - adding position param for background image in pt-card - remove background transparency for pt-card ### Version 1.0.12 - Release Date: 28/09/2024 - fix background transparency for pt-card ### Version 1.0.11 - Release Date: 28/09/2024 - fix column width for advanced table ### Version 1.0.10 - Release Date: 25/09/2024 - **New Components:** - **`pt-bar`:** Introduced a new bar component to visually represent progress or metrics in a horizontal bar layout. - **`pt-text-input`:** Added a customizable text input component to handle various form input needs with validation and error handling. - **`pt-page-skeleton`:** Introduced a page skeleton component for loading states, offering a clean UI while data is being fetched. - **`pt-footer`:** A new footer component providing a customizable and responsive footer layout for pages. - **`pt-menu-fancy`:** Added a new fancy menu component for stylish navigation menus with enhanced layout options. - **`pt-button`:** Introduced a highly customizable button component with various styles, icons, and action support. - **`pt-dialog`:** Added a flexible dialog component for modal-based interactions, supporting customizable content, actions, and layout. - **Enhancements to `pt-advanced-prime-table`:** - **Dynamic Column Width:** Enhanced the table to support dynamic column width adjustments based on content, ensuring alignment between header and body cells. - **Customizable Sticky Headers:** Improved sticky header behavior, allowing users to define `max-height` for tables with large datasets. - **Improved Icon Handling:** Optimized column and icon width calculations for better alignment and a more consistent visual experience. - **Cell Alignment Fixes:** Resolved issues with header and body cell misalignment when header content wraps. ### Version 1.0.9 - Release Date: 02/09/2024 - **`pt-advanced-prime-table`:** - **Loading Indicator:** Added loading spinner functionality to provide visual feedback during data fetching. - **Vertical Scrolling:** Enabled vertical scrolling to handle large datasets and improve usability. - **Empty Record Message:** Introduced a customizable message for when no data is available in the table. - **`pt-metric-card-group` & `pt-metric-card`:** Introduced a new metric card component and its group, designed for displaying key performance indicators in a visually appealing way. - **`pt-chart`:** Added a new chart component that supports various chart types (line, bar, doughnut, pie, etc.), with extensive customization options. - **`pt-card`:** Introduced a new card component for displaying content within a bordered and customizable container. - **`pt-menu`:** Added a new menu component to be used within cards, supporting various actions and a customizable layout. #### Version 1.0.8 Fix bug on size of buttons exports #### Version 1.0.7 Adding export to pdf and excel buttons in the `pt-advanced-prime-table`. ``` [hasExportExcel]="true" [hasExportPDF]="true" (exportExcelEvent)="onExportExcel()" (exportPdfEvent)="onExportPDF()" ``` #### Version 1.0.6 - **FormBuilder Component:** Introduced a powerful and flexible `FormBuilder` component that allows developers to dynamically create forms with various input types. The `FormBuilder` supports nested groups, input validation, and customizable form behavior. This component simplifies the process of building complex forms by providing a consistent and reusable structure. - **New Input Components:** - **`pt-check-box-input`**: A customizable checkbox input component for boolean selections. - **`pt-date-input`**: A versatile date input component supporting both single date and date range selections with customizable formats. - **`pt-dropdown`**: A dropdown input component for selecting single options from a list. - **`pt-multi-select`**: A multi-select dropdown component for selecting multiple values from a list. - **`pt-number-input`**: A numeric input component with support for validation (e.g., min/max values) and formatting. - **`pt-switch-input`**: A switch input component for toggling between two states. - **`pt-text-area-input`**: A text area input component for multi-line text entries with customizable rows and validation. - **`pt-text-input`**: A standard text input component with support for icons, placeholders, and input validation. ### Version 1.0.5 - **`multi-search-criteria` Component** - Added support for `mode` input to handle dynamic and static filtering. - `mode` input can be set to `'dynamic'` or `'static'`. When set to `'dynamic'`, the component emits search criteria for backend filtering. When set to `'static'`, the component filters data locally. - Fixed the bug in the `selectAll` functionality for multi-select filters. - Users can select or deselect all options in a multi-select filter. - **`pt-advanced-prime-table` Component** - Added support for customizable amount formatting. - New inputs for columns of type `AMOUNT`: - `thousandSeparator` (`comma` or `space`): Specifies the character used for thousands separator. - `decimalSeparator` (`comma` or `dot`): Specifies the character used for decimal separator. - Updated the `customCurrency` pipe to handle optional currency display and customizable separators. ### Version 1.0.4 - Added `multi-search-criteria` component. ### Version 1.0.3 - Initial release with `pt-advanced-prime-table` component. ## License This project is licensed under the MIT License.