@memberjunction/ng-timeline 2.43.0 → 2.44.0

package/README.md

@@ -1,17 +1,17 @@
 # @memberjunction/ng-timeline
 
-The `@memberjunction/ng-timeline` package provides a comprehensive timeline component for chronological display of data from MemberJunction entities. The component leverages Kendo UI's Timeline component to render events in either horizontal or vertical orientation.
+The `@memberjunction/ng-timeline` package provides a comprehensive Angular component for displaying chronological data from MemberJunction entities in a timeline format. Built on top of Kendo UI's Timeline component, it offers a flexible and intuitive way to visualize time-based data from multiple entity sources.
 
 ## Features
 
-- Display data from multiple entity sources on a unified timeline
-- Support for both vertical and horizontal timeline orientations
-- Configurable data sources via entity views or direct entity arrays
-- Customizable event display with title, summary, and date fields
-- Support for custom icons and colors for different event groups
-- Collapsible event details
-- Ability to customize summary display with field values or custom functions
-- Dynamic refresh and loading control
+- **Multiple Data Sources**: Display data from multiple MemberJunction entities on a unified timeline
+- **Flexible Orientation**: Support for both vertical and horizontal timeline layouts
+- **Data Source Options**: Load data via entity views with filters or provide pre-loaded entity arrays
+- **Customizable Display**: Configure title, date, and summary fields for each timeline item
+- **Visual Customization**: Support for custom icons and colors for different event groups
+- **Interactive UI**: Collapsible event details with alternating layout mode
+- **Dynamic Content**: Custom summary generation via callback functions
+- **Refresh Control**: Manual control over data loading and refresh operations
 
 ## Installation
 
@@ -21,9 +21,12 @@ npm install @memberjunction/ng-timeline
 
 ## Requirements
 
-- Angular 18+
-- @memberjunction/core and related packages
-- Kendo UI Angular components (Layout, Buttons, Indicators)
+- Angular 18.0.2 or higher
+- @memberjunction/core and related MemberJunction packages
+- Kendo UI Angular components:
+  - @progress/kendo-angular-layout (v16.2.0)
+  - @progress/kendo-angular-buttons (v16.2.0)
+  - @progress/kendo-angular-indicators (v16.2.0)
 
 ## Usage
 
@@ -76,35 +79,36 @@ export class YourComponent {
 
 #### Using Multiple Data Sources
 
-You can display data from multiple entity types on the same timeline:
+Display data from multiple entity types on the same timeline with different visual treatments:
 
 ```typescript
 import { TimelineGroup } from '@memberjunction/ng-timeline';
-import { RunViewParams } from '@memberjunction/core';
+import { BaseEntity } from '@memberjunction/core';
 
 export class YourComponent implements OnInit {
   timelineGroups: TimelineGroup[] = [];
 
   async ngOnInit() {
-    // First group - Tasks
+    // First group - Tasks with custom icon and color
     const tasksGroup = new TimelineGroup();
     tasksGroup.EntityName = 'Tasks';
     tasksGroup.DataSourceType = 'entity';
     tasksGroup.TitleFieldName = 'Title';
     tasksGroup.DateFieldName = 'DueDate';
+    tasksGroup.Filter = "Status = 'Active'"; // Optional filter
     tasksGroup.DisplayIconMode = 'custom';
     tasksGroup.DisplayIcon = 'fa fa-tasks';
     tasksGroup.DisplayColorMode = 'manual';
     tasksGroup.DisplayColor = '#4287f5';
     
-    // Second group - Meetings
+    // Second group - Meetings with custom summary
     const meetingsGroup = new TimelineGroup();
     meetingsGroup.EntityName = 'Meetings';
     meetingsGroup.DataSourceType = 'entity';
     meetingsGroup.TitleFieldName = 'Subject';
     meetingsGroup.DateFieldName = 'StartTime';
     meetingsGroup.SummaryMode = 'custom';
-    meetingsGroup.SummaryFunction = (record) => {
+    meetingsGroup.SummaryFunction = (record: BaseEntity) => {
       return `<strong>Location:</strong> ${record.Get('Location')}<br/>
               <strong>Duration:</strong> ${record.Get('DurationMinutes')} minutes`;
     };
@@ -117,7 +121,7 @@ export class YourComponent implements OnInit {
 
 #### Using RunView Parameters
 
-You can create a TimelineGroup using the static FromView method:
+Create a TimelineGroup using pre-configured RunViewParams:
 
 ```typescript
 import { TimelineGroup } from '@memberjunction/ng-timeline';
@@ -127,25 +131,89 @@ export class YourComponent implements OnInit {
   timelineGroups: TimelineGroup[] = [];
 
   async ngOnInit() {
-    // Create RunViewParams
+    // Configure RunViewParams for data retrieval
     const params: RunViewParams = {
       EntityName: 'Tasks',
-      ExtraFilter: "Status = 'Open'",
+      ExtraFilter: "Status = 'Open' AND Priority = 'High'",
       Skip: 0,
-      Take: 25,
+      Take: 50,
       OrderBy: 'DueDate DESC'
     };
     
-    // Create TimelineGroup from view
+    // Create TimelineGroup from view parameters
     const tasksGroup = await TimelineGroup.FromView(params);
     tasksGroup.TitleFieldName = 'Title';
     tasksGroup.DateFieldName = 'DueDate';
+    tasksGroup.DisplayIconMode = 'custom';
+    tasksGroup.DisplayIcon = 'fa fa-exclamation-circle';
     
     this.timelineGroups.push(tasksGroup);
   }
 }
 ```
 
+#### Using Pre-loaded Entity Arrays
+
+For scenarios where you already have entity data loaded:
+
+```typescript
+import { TimelineGroup } from '@memberjunction/ng-timeline';
+import { BaseEntity } from '@memberjunction/core';
+
+export class YourComponent {
+  timelineGroups: TimelineGroup[] = [];
+
+  displayLoadedData(entities: BaseEntity[]) {
+    const group = new TimelineGroup();
+    group.EntityName = 'Custom Events';
+    group.DataSourceType = 'array'; // Use provided array instead of loading
+    group.EntityObjects = entities;
+    group.TitleFieldName = 'EventName';
+    group.DateFieldName = 'EventDate';
+    group.SummaryMode = 'field';
+    
+    this.timelineGroups = [group];
+  }
+}
+```
+
+#### Deferred Loading
+
+Control when the timeline loads data using the `AllowLoad` property:
+
+```typescript
+import { Component, ViewChild } from '@angular/core';
+import { TimelineComponent, TimelineGroup } from '@memberjunction/ng-timeline';
+
+@Component({
+  template: `
+    <mj-timeline 
+      #timeline
+      [Groups]="timelineGroups" 
+      [AllowLoad]="false">
+    </mj-timeline>
+    <button (click)="loadTimeline()">Load Timeline Data</button>
+  `
+})
+export class YourComponent {
+  @ViewChild('timeline') timeline!: TimelineComponent;
+  timelineGroups: TimelineGroup[] = [];
+
+  constructor() {
+    // Configure groups but don't load yet
+    const group = new TimelineGroup();
+    group.EntityName = 'Events';
+    group.TitleFieldName = 'Name';
+    group.DateFieldName = 'EventDate';
+    this.timelineGroups = [group];
+  }
+
+  async loadTimeline() {
+    // Manually trigger data loading
+    await this.timeline.Refresh();
+  }
+}
+
 ## API Reference
 
 ### TimelineComponent
@@ -181,7 +249,8 @@ export class YourComponent implements OnInit {
 | `DisplayColorMode` | `'auto' \| 'manual'` | `'auto'` | Color selection mode |
 | `DisplayColor` | `string` | (optional) | Manual color for events |
 | `SummaryMode` | `'field' \| 'custom' \| 'none'` | `'field'` | Mode for summary display |
-| `SummaryFunction` | `(record: any) => string` | (optional) | Function for custom summary generation |
+| `SummaryFieldName` | `string` | (optional) | Field name for summary when using 'field' mode (Note: Currently uses TitleFieldName) |
+| `SummaryFunction` | `(record: BaseEntity) => string` | (optional) | Function for custom summary generation |
 
 #### Static Methods
 
@@ -191,21 +260,85 @@ export class YourComponent implements OnInit {
 
 ## Styling
 
-The component uses Kendo UI's styling for the timeline display. You can customize the appearance by targeting the Kendo UI elements or creating custom CSS for your implementation.
+The component uses Kendo UI's Timeline styling with additional customization options:
+
+- The timeline component automatically applies alternating layout mode for better visual separation
+- Events are displayed with collapsible details for better space utilization
+- Custom CSS can be applied by targeting the `.wrapper` class or Kendo UI elements
+- Icon and color customization per group allows for visual categorization
+
+### CSS Example
+
+```css
+/* Custom timeline styling */
+mj-timeline .wrapper {
+  height: 100%;
+  padding: 20px;
+}
+
+/* Custom event styling */
+mj-timeline .k-timeline-event {
+  /* Your custom styles */
+}
+```
+
+## Integration with MemberJunction
+
+This component is designed to work seamlessly with the MemberJunction framework:
+
+- **Entity System**: Automatically loads and displays data from any MemberJunction entity
+- **Metadata Integration**: Leverages MJ's metadata system for entity field access
+- **View System**: Supports RunView parameters for flexible data retrieval
+- **Container Directives**: Uses `mjFillContainer` directive for responsive layouts
+- **Entity Form Dialog**: Can integrate with entity form dialogs for detailed views (future enhancement)
+
+## Performance Considerations
+
+- **Data Loading**: The component loads all data at once. For large datasets, consider using filters or pagination
+- **Multiple Groups**: Each group triggers a separate data query. Consolidate groups when possible
+- **Refresh Operations**: The `Refresh()` method reloads all groups. Use judiciously for performance
 
 ## Dependencies
 
-- @angular/common
-- @angular/core
-- @angular/forms
-- @angular/router
-- @memberjunction/core
-- @memberjunction/core-entities
-- @memberjunction/global
-- @memberjunction/ng-container-directives
-- @memberjunction/ng-entity-form-dialog
-- @memberjunction/ng-shared
-- @progress/kendo-angular-buttons
-- @progress/kendo-angular-layout
-- @progress/kendo-angular-indicators
-- @progress/kendo-angular-scheduler
+### Production Dependencies
+- @memberjunction/core (^2.43.0)
+- @memberjunction/core-entities (^2.43.0)
+- @memberjunction/global (^2.43.0)
+- @memberjunction/ng-container-directives (^2.43.0)
+- @memberjunction/ng-entity-form-dialog (^2.43.0)
+- @memberjunction/ng-shared (^2.43.0)
+- @progress/kendo-angular-buttons (^16.2.0)
+- @progress/kendo-angular-layout (^16.2.0)
+- @progress/kendo-angular-indicators (^16.2.0)
+- @progress/kendo-angular-scheduler (^16.2.0)
+- tslib (^2.3.0)
+
+### Peer Dependencies
+- @angular/common (^18.0.2)
+- @angular/core (^18.0.2)
+- @angular/forms (^18.0.2)
+- @angular/router (^18.0.2)
+
+## Building
+
+This package is part of the MemberJunction monorepo. To build:
+
+```bash
+# From the package directory
+npm run build
+
+# From the monorepo root
+turbo build --filter="@memberjunction/ng-timeline"
+```
+
+## Future Enhancements
+
+- Support for pagination and virtual scrolling for large datasets
+- Integration with entity form dialogs for inline editing
+- Custom event templates for advanced display scenarios
+- Export functionality for timeline data
+- Real-time updates via entity change notifications
+
+## License
+
+ISC

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memberjunction/ng-timeline",
-  "version": "2.43.0",
+  "version": "2.44.0",
   "description": "MemberJunction: Timeline Display UI component",
   "main": "./dist/public-api.js",
   "typings": "./dist/public-api.d.ts",
@@ -25,12 +25,12 @@
     "@angular/router": "18.0.2"
   },
   "dependencies": {
-    "@memberjunction/core-entities": "2.43.0",
-    "@memberjunction/global": "2.43.0",
-    "@memberjunction/core": "2.43.0",
-    "@memberjunction/ng-container-directives": "2.43.0",
-    "@memberjunction/ng-entity-form-dialog": "2.43.0",
-    "@memberjunction/ng-shared": "2.43.0",
+    "@memberjunction/core-entities": "2.44.0",
+    "@memberjunction/global": "2.44.0",
+    "@memberjunction/core": "2.44.0",
+    "@memberjunction/ng-container-directives": "2.44.0",
+    "@memberjunction/ng-entity-form-dialog": "2.44.0",
+    "@memberjunction/ng-shared": "2.44.0",
     "@progress/kendo-angular-buttons": "16.2.0",
     "@progress/kendo-angular-layout": "16.2.0",
     "@progress/kendo-angular-indicators": "16.2.0",