@memberjunction/ng-entity-communications 4.0.0 → 4.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +121 -167
  2. package/package.json +11 -11
package/README.md CHANGED
@@ -1,17 +1,34 @@
1
1
  # @memberjunction/ng-entity-communications
2
2
 
3
- This Angular component package provides a user interface for selecting message templates, previewing communications, and sending messages to entity recipients within the MemberJunction framework. It enables users to preview how templates will look when applied to real data before sending communications.
4
-
5
- ## Features
6
-
7
- - **Template Selection**: Browse and select from available active message templates
8
- - **Message Preview**: Preview messages with actual entity data before sending
9
- - **Multi-recipient Support**: Preview communications for multiple recipients with navigation controls
10
- - **Dialog Integration**: Includes a dialog wrapper component for easy modal integration
11
- - **Navigation Controls**: VCR-style controls to browse through multiple preview messages
12
- - **Template Filtering**: Filter templates based on SQL expressions
13
- - **Real-time Template Processing**: Integrates with MemberJunction's template engine for dynamic content
14
- - **Provider Integration**: Works with communication providers like SendGrid
3
+ Angular components for selecting message templates, previewing communications with live entity data, and sending messages to recipients within the MemberJunction framework.
4
+
5
+ ## Overview
6
+
7
+ The `@memberjunction/ng-entity-communications` package provides a two-step communication workflow: first, users browse and select from available message templates; then they preview how those templates render against actual entity data before sending. The package includes both an inline preview component and a dialog wrapper for modal presentation.
8
+
9
+ ```mermaid
10
+ flowchart TD
11
+ subgraph Phase1["Template Selection"]
12
+ TS[Browse Active Templates] --> TF[Apply Template Filter]
13
+ TF --> TC[User Selects Template]
14
+ end
15
+
16
+ subgraph Phase2["Preview & Send"]
17
+ TC --> PG[Generate Previews]
18
+ PG --> NAV[Navigate Messages]
19
+ NAV --> SEND[Confirm / Cancel]
20
+ end
21
+
22
+ subgraph Integration["MJ Integration"]
23
+ ECC[EntityCommunicationsEngineClient] --> PG
24
+ RV[RunView - Entity Data] --> PG
25
+ TE[Template Engine] --> PG
26
+ end
27
+
28
+ style Phase1 fill:#2d6a9f,stroke:#1a4971,color:#fff
29
+ style Phase2 fill:#7c5295,stroke:#563a6b,color:#fff
30
+ style Integration fill:#2d8659,stroke:#1a5c3a,color:#fff
31
+ ```
15
32
 
16
33
  ## Installation
17
34
 
@@ -27,46 +44,37 @@ npm install @memberjunction/ng-entity-communications
27
44
  import { EntityCommunicationsModule } from '@memberjunction/ng-entity-communications';
28
45
 
29
46
  @NgModule({
30
- imports: [
31
- EntityCommunicationsModule,
32
- // other imports
33
- ],
34
- // ...
47
+ imports: [EntityCommunicationsModule]
35
48
  })
36
49
  export class YourModule { }
37
50
  ```
38
51
 
39
- ### Basic Component Usage
52
+ ### Inline Preview Component
40
53
 
41
54
  ```html
42
- <!-- Use the preview component directly -->
43
55
  <mj-entity-communications-preview
44
56
  [entityInfo]="entityInfo"
45
57
  [runViewParams]="runViewParams"
46
- [templateFilter]="'TemplateType = ''Email''' "
58
+ [templateFilter]="'TemplateType = ''Email'''"
47
59
  (templateSelected)="onTemplateSelected($event)">
48
60
  </mj-entity-communications-preview>
49
61
  ```
50
62
 
51
- ### Dialog Component Usage
63
+ ### Dialog Component
52
64
 
53
65
  ```html
54
- <!-- Use the preview in a dialog window -->
55
- <button kendoButton (click)="showPreviewDialog()">
56
- Preview Communications
57
- </button>
58
-
59
- <mj-entity-communications-preview-window
60
- *ngIf="previewDialogVisible"
61
- [entityInfo]="entityInfo"
62
- [runViewParams]="runViewParams"
63
- [DialogVisible]="previewDialogVisible"
64
- [Title]="'Email Preview'"
65
- (DialogClosed)="onPreviewDialogClosed($event)">
66
- </mj-entity-communications-preview-window>
66
+ @if (showPreview) {
67
+ <mj-entity-communications-preview-window
68
+ [entityInfo]="customerEntityInfo"
69
+ [runViewParams]="customerViewParams"
70
+ [DialogVisible]="showPreview"
71
+ [Title]="'Customer Email Preview'"
72
+ (DialogClosed)="onPreviewClosed($event)">
73
+ </mj-entity-communications-preview-window>
74
+ }
67
75
  ```
68
76
 
69
- ### TypeScript Component Example
77
+ ### Complete Example
70
78
 
71
79
  ```typescript
72
80
  import { Component } from '@angular/core';
@@ -76,184 +84,130 @@ import { TemplateEntityExtended } from '@memberjunction/templates-base-types';
76
84
  @Component({
77
85
  selector: 'app-customer-communication',
78
86
  template: `
79
- <button kendoButton (click)="previewCustomerEmails()">
80
- Preview Customer Emails
81
- </button>
82
-
83
- <mj-entity-communications-preview-window
84
- *ngIf="showPreview"
85
- [entityInfo]="customerEntityInfo"
86
- [runViewParams]="customerViewParams"
87
- [DialogVisible]="showPreview"
88
- [Title]="'Customer Email Preview'"
89
- (DialogClosed)="onPreviewClosed($event)">
90
- </mj-entity-communications-preview-window>
87
+ <button (click)="showPreview = true">Preview Customer Emails</button>
88
+
89
+ @if (showPreview) {
90
+ <mj-entity-communications-preview-window
91
+ [entityInfo]="customerEntityInfo"
92
+ [runViewParams]="customerViewParams"
93
+ [DialogVisible]="showPreview"
94
+ [Title]="'Customer Email Preview'"
95
+ (DialogClosed)="onPreviewClosed($event)">
96
+ </mj-entity-communications-preview-window>
97
+ }
91
98
  `
92
99
  })
93
100
  export class CustomerCommunicationComponent {
94
101
  showPreview = false;
95
102
  customerEntityInfo: EntityInfo;
96
103
  customerViewParams: RunViewParams;
97
-
104
+
98
105
  constructor() {
99
- // Initialize metadata and entity info
100
106
  const md = new Metadata();
101
107
  this.customerEntityInfo = md.Entities.find(e => e.Name === 'Customers')!;
102
-
103
- // Set up view parameters to get active customers who haven't been contacted recently
104
108
  this.customerViewParams = {
105
109
  EntityName: 'Customers',
106
- ExtraFilter: 'IsActive = 1 AND LastContactDate < DATEADD(month, -3, GETDATE())',
110
+ ExtraFilter: 'IsActive = 1',
107
111
  OrderBy: 'LastContactDate ASC',
108
112
  ResultType: 'entity_object'
109
113
  };
110
114
  }
111
-
112
- previewCustomerEmails() {
113
- this.showPreview = true;
114
- }
115
-
115
+
116
116
  onPreviewClosed(confirmed: boolean) {
117
117
  this.showPreview = false;
118
-
119
118
  if (confirmed) {
120
- // User confirmed - you could initiate the actual sending here
121
119
  console.log('User confirmed sending emails');
122
120
  }
123
121
  }
124
-
125
- onTemplateSelected(template: TemplateEntityExtended) {
126
- console.log('Selected template:', template.Name);
127
- }
128
122
  }
129
123
  ```
130
124
 
131
125
  ## API Reference
132
126
 
133
- ### EntityCommunicationsPreviewComponent
127
+ ### EntityCommunicationsPreviewComponent (`mj-entity-communications-preview`)
134
128
 
135
- This is the main component for displaying the template selection and preview interface.
129
+ Main component for template selection and message preview.
136
130
 
137
131
  #### Inputs
138
132
 
139
- - `entityInfo`: EntityInfo - Information about the entity for which communications will be sent
140
- - `runViewParams`: RunViewParams - Parameters for running a view to retrieve entity data
141
- - `templateFilter`: string - SQL filter expression to filter available templates
133
+ | Input | Type | Description |
134
+ |-------|------|-------------|
135
+ | `entityInfo` | `EntityInfo` | Entity metadata for the communication recipients |
136
+ | `runViewParams` | `RunViewParams` | Parameters for loading entity data |
137
+ | `templateFilter` | `string` | SQL filter expression for available templates |
142
138
 
143
139
  #### Outputs
144
140
 
145
- - `templateSelected`: EventEmitter<TemplateEntityExtended> - Emitted when a template is selected
141
+ | Output | Type | Description |
142
+ |--------|------|-------------|
143
+ | `templateSelected` | `EventEmitter<TemplateEntityExtended>` | Emitted when a template is selected |
146
144
 
147
- ### EntityCommunicationsPreviewWindowComponent
145
+ ### EntityCommunicationsPreviewWindowComponent (`mj-entity-communications-preview-window`)
148
146
 
149
- This component wraps the preview component in a Kendo dialog window.
147
+ Dialog wrapper around the preview component.
150
148
 
151
149
  #### Inputs
152
150
 
153
- - `DialogVisible`: boolean - Controls the visibility of the dialog
154
- - `Title`: string - Title of the dialog window (default: 'Communications Preview')
155
- - `Width`: number - Width of the dialog (default: 650)
156
- - `Height`: number - Height of the dialog (default: 600)
157
- - `MinWidth`: number - Minimum width of the dialog (default: 400)
158
- - `MinHeight`: number - Minimum height of the dialog (default: 350)
159
- - `Resizable`: boolean - Whether the dialog is resizable (default: true)
160
- - `entityInfo`: EntityInfo - Information about the entity
161
- - `runViewParams`: RunViewParams - Parameters for running a view
151
+ | Input | Type | Default | Description |
152
+ |-------|------|---------|-------------|
153
+ | `DialogVisible` | `boolean` | - | Controls dialog visibility |
154
+ | `Title` | `string` | `'Communications Preview'` | Dialog title |
155
+ | `Width` | `number` | `650` | Dialog width in pixels |
156
+ | `Height` | `number` | `600` | Dialog height in pixels |
157
+ | `MinWidth` | `number` | `400` | Minimum dialog width |
158
+ | `MinHeight` | `number` | `350` | Minimum dialog height |
159
+ | `Resizable` | `boolean` | `true` | Whether the dialog can be resized |
160
+ | `entityInfo` | `EntityInfo` | - | Entity metadata |
161
+ | `runViewParams` | `RunViewParams` | - | View parameters for data loading |
162
162
 
163
163
  #### Outputs
164
164
 
165
- - `DialogClosed`: EventEmitter<boolean> - Emitted when the dialog is closed (true if confirmed, false if canceled)
166
-
167
- ## Component Features
168
-
169
- ### Template Loading
170
- - Templates are loaded with their content from the database
171
- - Only active templates are shown (based on `IsActive` flag and `ActiveAt` date)
172
- - Additional filtering can be applied via the `templateFilter` input
173
- - Template content entities are loaded and associated with each template
174
-
175
- ### Message Preview Generation
176
- - Uses the EntityCommunicationsEngineClient to generate previews
177
- - Integrates with communication providers (e.g., SendGrid)
178
- - Processes templates against entity data to show real previews
179
- - Supports both HTML body and subject line templates
180
- - Runs in preview-only mode without actually sending messages
181
-
182
- ### Navigation Controls
183
- - VCR-style navigation buttons (first, previous, next, last)
184
- - Current position indicator showing "X of Y" messages
185
- - Buttons are automatically disabled at boundaries
186
- - Font Awesome icons for navigation buttons
165
+ | Output | Type | Description |
166
+ |--------|------|-------------|
167
+ | `DialogClosed` | `EventEmitter<boolean>` | `true` if confirmed, `false` if canceled |
187
168
 
188
169
  ## Process Flow
189
170
 
190
- 1. **Template Selection Phase**:
191
- - Component loads all active templates filtered by the `templateFilter` expression
192
- - User sees a list of available templates
193
- - Clicking a template moves to the preview phase
194
-
195
- 2. **Preview Generation Phase**:
196
- - Selected template is processed against the entity data from `runViewParams`
197
- - EntityCommunicationsEngineClient generates preview messages for each record
198
- - Loading indicator shows during processing
199
-
200
- 3. **Preview Navigation Phase**:
201
- - User can navigate through all generated preview messages
202
- - Each preview shows the processed subject and HTML body
203
- - Back button returns to template selection
171
+ 1. **Template Selection** -- Component loads active templates filtered by the `templateFilter` expression. User browses and selects a template.
172
+ 2. **Preview Generation** -- The selected template is processed against entity data from `runViewParams` using `EntityCommunicationsEngineClient`. A loading indicator shows during processing.
173
+ 3. **Preview Navigation** -- VCR-style controls (first, previous, next, last) let the user browse through all generated preview messages, viewing processed subject lines and HTML bodies.
174
+ 4. **Confirmation** (dialog mode) -- OK/Cancel buttons control the dialog, with `DialogClosed` emitting the user's choice.
204
175
 
205
- 4. **Dialog Interaction** (when using window component):
206
- - OK/Cancel buttons control the dialog
207
- - DialogClosed event indicates user's choice
208
-
209
- ## Styling
176
+ ## Dependencies
210
177
 
211
- The component includes CSS styling with the following key classes:
212
- - `.step-1`: Template selection view styling
213
- - `.step-2`: Preview display view styling
214
- - `.vcr-controls`: Navigation button container
215
- - `.template-preview`: Preview content container
216
- - `.subject-line`: Email subject preview styling
217
- - `.preview-body`: Email body preview styling
178
+ ### Runtime Dependencies
179
+
180
+ | Package | Description |
181
+ |---------|-------------|
182
+ | `@memberjunction/core` | Metadata, entity framework, view execution |
183
+ | `@memberjunction/core-entities` | Entity type definitions |
184
+ | `@memberjunction/global` | Global utilities and event system |
185
+ | `@memberjunction/communication-types` | Message types and communication engine interfaces |
186
+ | `@memberjunction/entity-communications-base` | EntityCommunicationParams interface |
187
+ | `@memberjunction/entity-communications-client` | Client-side communication processing engine |
188
+ | `@memberjunction/templates-base-types` | Template engine and extended template types |
189
+ | `@memberjunction/ng-container-directives` | Container directive utilities |
190
+ | `@memberjunction/ng-shared` | Shared Angular utilities |
191
+ | `@memberjunction/ng-shared-generic` | Shared generic components |
192
+
193
+ ### Peer Dependencies
194
+
195
+ - `@angular/common` ^21.x
196
+ - `@angular/core` ^21.x
197
+ - `@angular/forms` ^21.x
198
+ - `@angular/router` ^21.x
199
+ - `@progress/kendo-angular-buttons` ^22.x
200
+ - `@progress/kendo-angular-dialog` ^22.x
201
+ - `@progress/kendo-angular-listbox` ^22.x
202
+ - `@progress/kendo-angular-indicators` ^22.x
203
+
204
+ ## Build
218
205
 
219
- These styles can be customized or overridden in your application.
206
+ ```bash
207
+ cd packages/Angular/Generic/entity-communication
208
+ npm run build
209
+ ```
220
210
 
221
- ## Dependencies
211
+ ## License
222
212
 
223
- ### Core Dependencies
224
- - `@memberjunction/core`: Metadata, entity framework, and view execution
225
- - `@memberjunction/core-entities`: Entity type definitions including TemplateContentEntity
226
- - `@memberjunction/global`: Global utilities and event system
227
- - `@memberjunction/communication-types`: Message types, communication engines, and providers
228
- - `@memberjunction/entity-communications-base`: EntityCommunicationParams interface
229
- - `@memberjunction/entity-communications-client`: Client-side communication processing engine
230
- - `@memberjunction/templates-base-types`: Template engine and extended template types
231
- - `@memberjunction/ng-container-directives`: Container directive utilities
232
- - `@memberjunction/ng-shared`: Shared Angular utilities
233
-
234
- ### Angular Dependencies
235
- - `@angular/common`: Angular common module (v18.0.2)
236
- - `@angular/core`: Angular core framework (v18.0.2)
237
- - `@angular/forms`: Form support (v18.0.2)
238
- - `@angular/router`: Routing support (v18.0.2)
239
-
240
- ### Kendo UI Dependencies
241
- - `@progress/kendo-angular-buttons`: Button components (v16.2.0)
242
- - `@progress/kendo-angular-dialog`: Dialog/window components (v16.2.0)
243
- - `@progress/kendo-angular-listbox`: Listbox component (v16.2.0)
244
- - `@progress/kendo-angular-indicators`: Loading indicators (v16.2.0)
245
-
246
- ## Important Notes
247
-
248
- ### Current Limitations
249
- - The component currently hardcodes the SendGrid provider and Email message type
250
- - Subject template is hardcoded to 'Test Subject Template'
251
- - From address is hardcoded in the preview generation
252
-
253
- ### Future Enhancements
254
- Consider making the following configurable:
255
- - Communication provider selection
256
- - Message type selection
257
- - From address configuration
258
- - Subject template selection
259
- - Support for text body templates in addition to HTML
213
+ ISC
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@memberjunction/ng-entity-communications",
3
- "version": "4.0.0",
3
+ "version": "4.1.0",
4
4
  "description": "MemberJunction: Angular Components to allow a user to select templates, preview the messages with those tempaltes, and send them",
5
5
  "main": "./dist/public-api.js",
6
6
  "typings": "./dist/public-api.d.ts",
@@ -29,16 +29,16 @@
29
29
  "@progress/kendo-angular-indicators": "22.0.1"
30
30
  },
31
31
  "dependencies": {
32
- "@memberjunction/communication-types": "4.0.0",
33
- "@memberjunction/core": "4.0.0",
34
- "@memberjunction/core-entities": "4.0.0",
35
- "@memberjunction/entity-communications-base": "4.0.0",
36
- "@memberjunction/entity-communications-client": "4.0.0",
37
- "@memberjunction/global": "4.0.0",
38
- "@memberjunction/ng-container-directives": "4.0.0",
39
- "@memberjunction/ng-shared": "4.0.0",
40
- "@memberjunction/ng-shared-generic": "4.0.0",
41
- "@memberjunction/templates-base-types": "4.0.0",
32
+ "@memberjunction/communication-types": "4.1.0",
33
+ "@memberjunction/core": "4.1.0",
34
+ "@memberjunction/core-entities": "4.1.0",
35
+ "@memberjunction/entity-communications-base": "4.1.0",
36
+ "@memberjunction/entity-communications-client": "4.1.0",
37
+ "@memberjunction/global": "4.1.0",
38
+ "@memberjunction/ng-container-directives": "4.1.0",
39
+ "@memberjunction/ng-shared": "4.1.0",
40
+ "@memberjunction/ng-shared-generic": "4.1.0",
41
+ "@memberjunction/templates-base-types": "4.1.0",
42
42
  "tslib": "^2.8.1"
43
43
  },
44
44
  "sideEffects": false,