ng-prime-tools v1.0.26

NG Prime Tools

An advanced PrimeNG tools library for Angular.

Table of Contents

• Introduction
• Installation
• Compatibility
• Usage
  • pt-advanced-prime-table
    • Inputs
    • Outputs
    • Example
  • multi-search-criteria
    • Inputs
    • Outputs
    • Example
  • FormBuilder
    • Components
    • Example
• Changelog
• 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:

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.

   import { NgAdvancedPrimeTableModule, TableColumn, TableTypeEnum } from "ng-prime-tools";

2. Add the Component:

   Add the pt-advanced-prime-table component to your template:

   <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:

   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:

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;
  }
}

<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.

   import { MultiSearchCriteriaModule, SearchCriteria, SearchCriteriaTypeEnum } from "ng-prime-tools";

2. Add the Component:

   Add the multi-search-criteria component to your template:

   <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:

   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:

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
  }
}

<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:

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.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.