diff --git a/README.md b/README.md index 728c680..0165c8e 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,511 @@ -# Getting Started with the Angular Pivot Table Component -A quick-start project that helps you to create and configure the Syncfusion Angular Pivot Table. This project also includes a code snippet to add required fields in the Angular Pivot Table and shows you how to add useful features like a grouping bar, filtering, formatting, Calculated field, Sorting and a field list. +# ๐Ÿ“Š Getting Started โ€” Angular Pivot Table Component (Syncfusion EJ2) -Refer to the following documentation to learn about the Angular Pivot Table component: https://ej2.syncfusion.com/angular/documentation/pivotview/getting-started +[![License](https://img.shields.io/badge/license-SEE%20LICENSE%20IN%20license-blue.svg)](https://www.syncfusion.com/content/downloads/syncfusion_license.pdf) +[![Angular](https://img.shields.io/badge/Angular-Latest-red.svg)](https://angular.io/) +[![Syncfusion Version](https://img.shields.io/badge/Syncfusion%20EJ2-*-green.svg)](https://www.syncfusion.com/angular-components/) +[![Node.js](https://img.shields.io/badge/Node.js-LTS-green.svg)](https://nodejs.org/) +[![npm](https://img.shields.io/badge/npm-v10%2B-blue.svg)](https://www.npmjs.com/) -Check out this online example of the Blazor Pivot Table component: https://ej2.syncfusion.com/angular/demos/#/bootstrap5/pivot-table/default - -## Project prerequisites +> ๐Ÿš€ **Angular quick-start template** demonstrating Syncfusion EJ2 `PivotView` (Pivot Table) with **Field List**, **Grouping Bar**, **Calculated Fields**, **Formatting**, and **Sorting** โ€” includes sample data, CLI scripts, and production-ready configuration. -Make sure that you have the latest versions of NodeJS and Visual Studio Code in your machine before starting to work on this project. +> **๐Ÿ“บ Official Demo:** https://ej2.syncfusion.com/angular/demos/#/bootstrap5/pivot-table/default +> **๐Ÿ“š Official Documentation:** https://ej2.syncfusion.com/angular/documentation/pivotview/getting-started -## How to run this application? -To run this application, you need to clone the `Getting Started with the Angular Pivot Table Component` repository and then open it in Visual Studio Code. Now, simply install all the necessary angular packages into your current project using the `npm install` command and run your project using the `ng serve` command \ No newline at end of file +--- + +## ๐Ÿ“‘ Table of Contents + +- [๐Ÿ” Overview](#-overview) +- [โœจ Key Features](#-key-features) +- [๐Ÿงญ Quick Start](#-quick-start) +- [๐Ÿ—‚๏ธ Project Structure](#-project-structure) +- [๐ŸŽจ Theming & Styling](#-theming--styling) +- [๐Ÿงฉ Minimal Example](#-minimal-example) +- [โš™๏ธ Configuration & Customization](#-configuration--customization) +- [๐Ÿค Contributing](#-contributing) +- [๐Ÿ“œ License & Support](#-license--support) + +--- + +## ๐Ÿ” Overview + +This repository provides a **production-ready starter template** for integrating Syncfusion's powerful `PivotView` (Pivot Table) component into your **Angular applications**. It demonstrates essential features including: + +- โœ… Interactive Pivot Table with drag-and-drop functionality +- โœ… Dynamic Field List for runtime field configuration +- โœ… Grouping Bar for intuitive data organization +- โœ… Calculated Fields for custom data computations +- โœ… Data Formatting (currency, percentages, etc.) +- โœ… Multi-level Sorting and Filtering +- โœ… Responsive Design with Tailwind CSS styling + +--- + +## โœจ Key Features + +| Feature | Description | Benefit | +|---------|-------------|---------| +| ๐ŸŽฏ **Field List Interface** | Dynamically add, remove, and rearrange data fields at runtime | Empowers end-users to customize reports without code | +| ๐Ÿ“Š **Grouping Bar** | Drag-and-drop fields between rows, columns, values, and filters | Intuitive data organization and real-time pivot manipulation | +| ๐Ÿงฎ **Calculated Fields** | Create custom formulas combining multiple data fields | Advanced data analysis and custom metrics | +| ๐Ÿ’ฑ **Data Formatting** | Display values in currency, percentages, and custom formats | Professional presentation of numerical data | +| โ†•๏ธ **Multi-Level Sorting** | Sort by multiple fields with ascending/descending control | Enhanced data exploration capabilities | +| ๐Ÿ”— **Advanced Filtering** | Filter by single or multiple criteria across all dimensions | Focused data analysis and drill-down exploration | +| ๐Ÿ“ฑ **Responsive Design** | Adapts seamlessly to desktop, tablet, and mobile screens | Universal accessibility across devices | +| ๐Ÿš€ **Server-Side Rendering (SSR)** | Full Angular SSR support out-of-the-box | SEO-friendly and faster initial page loads | +| โšก **Ivy Compilation** | Modern Angular Ivy rendering engine | Smaller bundle sizes and improved performance | +| ๐ŸŽจ **Theme Support** | Multiple Tailwind and Bootstrap themes available | Consistent branding and visual customization | + +--- + +## ๐Ÿš€ Quick Start + +### Prerequisites + +Ensure you have the following installed on your system: + +- **Node.js** (LTS version or higher) โ€” [Download](https://nodejs.org/) +- **npm** (v10+) โ€” Included with Node.js +- **Angular CLI** โ€” Install globally: `npm install -g @angular/cli` +- **Visual Studio Code** โ€” Optional but recommended โ€” [Download](https://code.visualstudio.com/) + +### Installation & Setup + +```bash +# 1๏ธโƒฃ Clone the repository +git clone https://github.com/SyncfusionExamples/getting-started-with-the-angular-pivot-table-component-in-angular-18.git + +# 2๏ธโƒฃ Navigate to the project directory +cd getting-started-with-the-angular-pivot-table-component-in-angular-18 + +# 3๏ธโƒฃ Install dependencies +npm install + +# 4๏ธโƒฃ Start the development server +npm start +``` + +**๐ŸŽ‰ Success!** Your application will open at `http://localhost:4200/` in your default browser. + +### Additional Commands + +```bash +# ๐Ÿ”จ Build for production +npm run build + +# ๐Ÿ‘€ Build and watch for changes (development) +npm run watch + +# ๐Ÿงช Run unit tests +npm test + +# ๐ŸŒ Serve SSR version +npm run serve:ssr:my-app +``` + +--- + +## ๐Ÿ—‚๏ธ Project Structure + +``` +getting-started-with-the-angular-pivot-table-component-in-angular-18/ +โ”œโ”€โ”€ ๐Ÿ“„ angular.json # Angular CLI configuration +โ”œโ”€โ”€ ๐Ÿ“„ package.json # Project dependencies & scripts +โ”œโ”€โ”€ ๐Ÿ“„ tsconfig.json # TypeScript compilation config +โ”œโ”€โ”€ ๐Ÿ“„ tsconfig.app.json # App-specific TypeScript config +โ”œโ”€โ”€ ๐Ÿ“„ tsconfig.spec.json # Testing TypeScript config +โ”œโ”€โ”€ ๐Ÿ“„ server.ts # Express server for SSR +โ”œโ”€โ”€ ๐Ÿ“„ README.md # This file +โ”‚ +โ”œโ”€โ”€ ๐Ÿ“ src/ +โ”‚ โ”œโ”€โ”€ ๐Ÿ“„ index.html # Main HTML entry point +โ”‚ โ”œโ”€โ”€ ๐Ÿ“„ main.ts # Angular bootstrap file +โ”‚ โ”œโ”€โ”€ ๐Ÿ“„ main.server.ts # SSR bootstrap file +โ”‚ โ”œโ”€โ”€ ๐Ÿ“„ styles.css # Global styles & Syncfusion CSS imports +โ”‚ โ”‚ +โ”‚ โ””โ”€โ”€ ๐Ÿ“ app/ +โ”‚ โ”œโ”€โ”€ ๐Ÿ“„ app.component.ts # Root component with PivotView +โ”‚ โ”œโ”€โ”€ ๐Ÿ“„ app.component.html # Component template (optional) +โ”‚ โ”œโ”€โ”€ ๐Ÿ“„ app.component.css # Component styles +โ”‚ โ”œโ”€โ”€ ๐Ÿ“„ app.component.spec.ts # Component unit tests +โ”‚ โ”œโ”€โ”€ ๐Ÿ“„ app.config.ts # Application-level config +โ”‚ โ”œโ”€โ”€ ๐Ÿ“„ app.config.server.ts # SSR-specific config +โ”‚ โ”œโ”€โ”€ ๐Ÿ“„ app.routes.ts # Application routing (if enabled) +โ”‚ โ””โ”€โ”€ ๐Ÿ“„ datasource.ts # Sample data source +``` + +### Key Files Explained + +| File | Purpose | +|------|---------| +| `src/main.ts` | Angular application bootstrap entry point | +| `src/app/app.component.ts` | Root component containing PivotView logic | +| `src/styles.css` | Global styles and Syncfusion CSS imports | +| `package.json` | NPM dependencies (includes Syncfusion EJ2 packages) | +| `angular.json` | Angular CLI configuration for builds and dev server | + +--- + +## ๐ŸŽจ Theming & Styling + +### Global CSS Imports (`src/styles.css`) + +Add Syncfusion theme CSS to your global styles: + +```css +/* Tailwind3 Theme (Modern) */ +@import '../node_modules/@syncfusion/ej2-base/styles/tailwind3.css'; +@import '../node_modules/@syncfusion/ej2-buttons/styles/tailwind3.css'; +@import '../node_modules/@syncfusion/ej2-dropdowns/styles/tailwind3.css'; +@import '../node_modules/@syncfusion/ej2-grids/styles/tailwind3.css'; +@import '../node_modules/@syncfusion/ej2-inputs/styles/tailwind3.css'; +@import '../node_modules/@syncfusion/ej2-lists/styles/tailwind3.css'; +@import '../node_modules/@syncfusion/ej2-navigations/styles/tailwind3.css'; +@import '../node_modules/@syncfusion/ej2-popups/styles/tailwind3.css'; +@import '../node_modules/@syncfusion/ej2-splitbuttons/styles/tailwind3.css'; +@import '../node_modules/@syncfusion/ej2-angular-pivotview/styles/tailwind3.css'; +``` + +### Available Themes + +- ๐ŸŽจ **tailwind3** โ€” Modern Tailwind CSS v3 design system +- ๐Ÿข **bootstrap5** โ€” Bootstrap 5 professional styling +- ๐Ÿ’Ž **fluent2** โ€” Microsoft Fluent Design System +- ๐ŸŒ™ **material3** โ€” Google Material Design 3 +- ๐ŸŽญ **fabric** โ€” Microsoft Fabric Design System + +**Swap themes** by replacing the CSS import path: + +```css +/* Switch to Bootstrap5 theme */ +@import '../node_modules/@syncfusion/ej2-angular-pivotview/styles/bootstrap5.css'; +``` + +--- + +## ๐Ÿงฉ Minimal Example + +### Component Implementation (`src/app/app.component.ts`) + +```typescript +import { Component, OnInit } from '@angular/core'; +import { PivotViewModule, PivotFieldListModule } from '@syncfusion/ej2-angular-pivotview'; +import { + IDataOptions, + IDataSet, + FieldListService, + CalculatedFieldService +} from '@syncfusion/ej2-angular-pivotview'; + +@Component({ + selector: 'app-root', + standalone: true, + imports: [PivotViewModule, PivotFieldListModule], + providers: [FieldListService, CalculatedFieldService], + template: ` +
+ + +
+ ` +}) +export class AppComponent implements OnInit { + public pivotData!: IDataSet[]; + public dataSourceSettings!: IDataOptions; + public width?: string; + + ngOnInit(): void { + this.pivotData = [ + { + Amount: 2100, + Country: "Canada", + Date: "FY 2005", + Product: "Bike", + Quantity: 22, + State: "Alberta" + }, + { + Amount: 1100, + Country: "Canada", + Date: "FY 2006", + Product: "Van", + Quantity: 32, + State: "Quebec" + }, + // ... more data items + ]; + + this.dataSourceSettings = { + dataSource: this.pivotData, + columns: [ + { name: 'Date', caption: 'Date' }, + { name: 'Product' } + ], + rows: [ + { name: 'Country' }, + { name: 'State' } + ], + values: [ + { name: 'Amount', caption: 'Sold Amount' }, + { name: 'Quantity', caption: 'Quantity' } + ], + filters: [], + expandAll: false, + enableSorting: true, + formatSettings: [{ name: 'Amount', format: 'C0' }], + drilledMembers: [{ name: 'Country', items: ['France'] }], + calculatedFieldSettings: [ + { name: 'Total', formula: '"Sum(Amount)"+"Sum(Quantity)"' } + ] + }; + + this.width = "100%"; + } +} +``` + +### Template Binding (`src/app/app.component.html`) + +The component uses inline template binding. For external templates, create: + +```html + +
+ + +
+``` +--- + +## โš™๏ธ Configuration & Customization + +### 1๏ธโƒฃ Configuring Pivot Table Axes + +The `dataSourceSettings` object defines how data is organized: + +```typescript +dataSourceSettings: { + // ๐Ÿ“Š Data Source + dataSource: this.pivotData, + + // ๐ŸŽฏ Row Fields (left vertical axis) + rows: [ + { name: 'Country', caption: 'Country' }, + { name: 'State', caption: 'State' } + ], + + // ๐Ÿ“ˆ Column Fields (top horizontal axis) + columns: [ + { name: 'Date', caption: 'Fiscal Year' }, + { name: 'Product', caption: 'Product Category' } + ], + + // ๐Ÿ’ฐ Value Fields (numeric aggregations) + values: [ + { name: 'Amount', caption: 'Sales Amount', type: 'Sum' }, + { name: 'Quantity', caption: 'Units Sold', type: 'Sum' } + ], + + // ๐Ÿ”— Filter Fields (master filters) + filters: [ + { name: 'Region', caption: 'Region' } + ] +} +``` + +### 2๏ธโƒฃ Enabling Interactive Features + +```typescript +// Component properties for interactive features +showFieldList: true, // โœ… Enable Field List UI +showGroupingBar: true, // โœ… Enable Grouping Bar +allowCalculatedField: true, // โœ… Allow user-defined calculated fields +enableSorting: true, // โœ… Enable multi-level sorting +enableFiltering: true, // โœ… Enable advanced filtering +allowDrillThrough: true, // โœ… Enable drill-through to detail data +``` + +### 3๏ธโƒฃ Module Injection for Advanced Features + +```typescript +import { + PivotViewModule, + PivotFieldListModule, + GroupingBarService, + FieldListService, + CalculatedFieldService +} from '@syncfusion/ej2-angular-pivotview'; + +@Component({ + providers: [ + GroupingBarService, // For drag-drop grouping bar + FieldListService, // For field list interface + CalculatedFieldService // For calculated field support + ] +}) +export class AppComponent { } +``` + +### 4๏ธโƒฃ Applying Data Formatting + +Format numeric values for better presentation: + +```typescript +formatSettings: [ + { name: 'Amount', format: 'C0' }, // Currency: $1,234 + { name: 'Quantity', format: 'N2' }, // Number: 1,234.56 + { name: 'Percentage', format: 'P2' }, // Percentage: 12.34% + { name: 'Date', format: 'yyyy-MM-dd' } // Date: 2025-02-03 +] +``` + +### 5๏ธโƒฃ Calculated Fields Example + +Create custom fields combining multiple data sources: + +```typescript +calculatedFieldSettings: [ + { + name: 'GrossSales', + formula: '"Sum(Amount)"+"Sum(Tax)"' + }, + { + name: 'NetSales', + formula: '"Sum(GrossSales)"-"Sum(Discount)"' + } +] +``` + +--- + +## ๐Ÿค Contributing + +We welcome contributions! Please follow these guidelines: + +### 1. Fork & Clone + +```bash +git clone https://github.com/YOUR-USERNAME/getting-started-with-the-angular-pivot-table-component-in-angular-18.git +cd getting-started-with-the-angular-pivot-table-component-in-angular-18 +``` + +### 2. Create Feature Branch + +```bash +git checkout -b feature/your-feature-name +``` + +### 3. Make Changes & Commit + +```bash +# Follow conventional commits +git commit -m "feat: add pivot table export to Excel functionality" +``` + +### 4. Push & Create Pull Request + +```bash +git push origin feature/your-feature-name +``` + +### Code Style Guidelines + +- โœ… Follow Angular style guide: https://angular.io/guide/styleguide +- โœ… Use TypeScript strict mode +- โœ… Include meaningful variable names +- โœ… Add JSDoc comments for complex functions +- โœ… Write unit tests for new features + +### Commit Message Format + +``` +(): + + + +