@memberjunction/templates-base-types 2.42.1 → 2.44.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 +245 -0
  2. package/package.json +4 -4
package/README.md ADDED
@@ -0,0 +1,245 @@
1
+ # @memberjunction/templates-base-types
2
+
3
+ Base types and core functionality for the MemberJunction templating system. This package provides the foundational classes, types, and metadata management for templates that can be used in both client and server environments.
4
+
5
+ ## Overview
6
+
7
+ This package serves as the foundation for the MemberJunction templating system, providing:
8
+
9
+ - **Base template engine class** for metadata management and caching
10
+ - **Extended template entity** with additional functionality
11
+ - **Core type definitions** for template rendering results
12
+ - **Template metadata access** through a singleton pattern
13
+
14
+ ## Installation
15
+
16
+ ```bash
17
+ npm install @memberjunction/templates-base-types
18
+ ```
19
+
20
+ ## Core Components
21
+
22
+ ### TemplateEngineBase
23
+
24
+ The `TemplateEngineBase` class provides a singleton engine for managing template metadata, including templates, content variations, parameters, and categories.
25
+
26
+ ```typescript
27
+ import { TemplateEngineBase } from '@memberjunction/templates-base-types';
28
+
29
+ // Get the singleton instance
30
+ const templateEngine = TemplateEngineBase.Instance;
31
+
32
+ // Load template metadata (required before use)
33
+ await templateEngine.Config();
34
+
35
+ // Access templates
36
+ const templates = templateEngine.Templates;
37
+
38
+ // Find a specific template by name (case-insensitive)
39
+ const template = templateEngine.FindTemplate('Welcome Email');
40
+ ```
41
+
42
+ ### TemplateEntityExtended
43
+
44
+ An enhanced version of the base `TemplateEntity` that includes associated content and parameters as properties, along with utility methods.
45
+
46
+ ```typescript
47
+ import { TemplateEntityExtended } from '@memberjunction/templates-base-types';
48
+
49
+ // Access template content and parameters
50
+ const template: TemplateEntityExtended = templateEngine.FindTemplate('Invoice Template');
51
+
52
+ // Get all content for the template
53
+ const allContent = template.Content;
54
+
55
+ // Get content by type
56
+ const htmlContent = template.GetContentByType('HTML');
57
+ const plainTextContent = template.GetContentByType('PlainText');
58
+
59
+ // Get the highest priority content
60
+ const primaryContent = template.GetHighestPriorityContent();
61
+ const primaryHtmlContent = template.GetHighestPriorityContent('HTML');
62
+
63
+ // Validate input data against template parameters
64
+ const validationResult = template.ValidateTemplateInput({
65
+ customerName: 'John Doe',
66
+ invoiceNumber: '12345'
67
+ });
68
+
69
+ if (!validationResult.Success) {
70
+ console.error('Validation errors:', validationResult.Errors);
71
+ }
72
+ ```
73
+
74
+ ### TemplateRenderResult
75
+
76
+ A simple class representing the result of a template rendering operation.
77
+
78
+ ```typescript
79
+ import { TemplateRenderResult } from '@memberjunction/templates-base-types';
80
+
81
+ // Typically returned by rendering operations
82
+ const result: TemplateRenderResult = {
83
+ Success: true,
84
+ Output: '<html>Rendered content...</html>',
85
+ Message: undefined // Optional, typically used for error messages
86
+ };
87
+ ```
88
+
89
+ ## API Reference
90
+
91
+ ### TemplateEngineBase
92
+
93
+ #### Properties
94
+
95
+ - `Templates: TemplateEntityExtended[]` - All loaded templates
96
+ - `TemplateContentTypes: TemplateContentTypeEntity[]` - Available content types
97
+ - `TemplateCategories: TemplateCategoryEntity[]` - Template categories
98
+ - `TemplateContents: TemplateContentEntity[]` - All template content records
99
+ - `TemplateParams: TemplateParamEntity[]` - All template parameters
100
+
101
+ #### Methods
102
+
103
+ - `static get Instance(): TemplateEngineBase` - Get the singleton instance
104
+ - `async Config(forceRefresh?: boolean, contextUser?: UserInfo, provider?: IMetadataProvider)` - Load template metadata
105
+ - `FindTemplate(templateName: string): TemplateEntityExtended` - Find a template by name (case-insensitive)
106
+
107
+ ### TemplateEntityExtended
108
+
109
+ #### Properties
110
+
111
+ - `Content: TemplateContentEntity[]` - Associated content records
112
+ - `Params: TemplateParamEntity[]` - Associated parameter definitions
113
+
114
+ #### Methods
115
+
116
+ - `GetContentByType(type: string): TemplateContentEntity[]` - Get all content of a specific type
117
+ - `GetHighestPriorityContent(type?: string): TemplateContentEntity` - Get the highest priority content
118
+ - `ValidateTemplateInput(data: any): ValidationResult` - Validate input data against parameter requirements
119
+
120
+ ### TemplateRenderResult
121
+
122
+ #### Properties
123
+
124
+ - `Success: boolean` - Whether the rendering was successful
125
+ - `Output: string` - The rendered output
126
+ - `Message?: string` - Optional message (typically for errors)
127
+
128
+ ## Usage Examples
129
+
130
+ ### Basic Template Metadata Access
131
+
132
+ ```typescript
133
+ import { TemplateEngineBase } from '@memberjunction/templates-base-types';
134
+
135
+ async function loadTemplates() {
136
+ const engine = TemplateEngineBase.Instance;
137
+
138
+ // Load metadata (only needed once)
139
+ await engine.Config();
140
+
141
+ // List all active templates
142
+ const activeTemplates = engine.Templates.filter(t => t.IsActive);
143
+
144
+ // Find templates by category
145
+ const emailTemplates = engine.Templates.filter(t =>
146
+ t.CategoryID === engine.TemplateCategories.find(c => c.Name === 'Email')?.ID
147
+ );
148
+
149
+ console.log(`Found ${activeTemplates.length} active templates`);
150
+ console.log(`Found ${emailTemplates.length} email templates`);
151
+ }
152
+ ```
153
+
154
+ ### Working with Template Content
155
+
156
+ ```typescript
157
+ import { TemplateEngineBase, TemplateEntityExtended } from '@memberjunction/templates-base-types';
158
+
159
+ async function getTemplateContent(templateName: string, contentType: string) {
160
+ const engine = TemplateEngineBase.Instance;
161
+ await engine.Config();
162
+
163
+ const template = engine.FindTemplate(templateName);
164
+ if (!template) {
165
+ throw new Error(`Template "${templateName}" not found`);
166
+ }
167
+
168
+ // Get specific content type
169
+ const content = template.GetHighestPriorityContent(contentType);
170
+ if (!content) {
171
+ throw new Error(`No ${contentType} content found for template "${templateName}"`);
172
+ }
173
+
174
+ return content.TemplateText;
175
+ }
176
+ ```
177
+
178
+ ### Template Parameter Validation
179
+
180
+ ```typescript
181
+ import { TemplateEngineBase } from '@memberjunction/templates-base-types';
182
+
183
+ async function validateTemplateData(templateName: string, inputData: any) {
184
+ const engine = TemplateEngineBase.Instance;
185
+ await engine.Config();
186
+
187
+ const template = engine.FindTemplate(templateName);
188
+ if (!template) {
189
+ throw new Error(`Template "${templateName}" not found`);
190
+ }
191
+
192
+ const validation = template.ValidateTemplateInput(inputData);
193
+
194
+ if (!validation.Success) {
195
+ // Handle validation errors
196
+ validation.Errors.forEach(error => {
197
+ console.error(`Parameter ${error.Source}: ${error.Message}`);
198
+ });
199
+ throw new Error('Template validation failed');
200
+ }
201
+
202
+ // Data is valid, proceed with rendering
203
+ return true;
204
+ }
205
+ ```
206
+
207
+ ## Dependencies
208
+
209
+ This package depends on the following MemberJunction packages:
210
+
211
+ - `@memberjunction/core` - Core MemberJunction functionality and base classes
212
+ - `@memberjunction/core-entities` - Entity definitions for templates, content, and parameters
213
+ - `@memberjunction/global` - Global utilities and decorators
214
+
215
+ ## Integration with Other MJ Packages
216
+
217
+ This package serves as the foundation for:
218
+
219
+ - **`@memberjunction/templates-engine`** - The full template rendering engine that builds on these base types
220
+ - **Custom template extensions** - Third-party extensions can use these types for compatibility
221
+
222
+ The base types ensure consistent template handling across the entire MemberJunction ecosystem, whether templates are being managed, validated, or rendered.
223
+
224
+ ## Build and Development
225
+
226
+ ```bash
227
+ # Build the package
228
+ npm run build
229
+
230
+ # Watch for changes during development
231
+ npm run start
232
+ ```
233
+
234
+ The package is built using TypeScript and outputs to the `dist` directory. Type definitions are automatically generated during the build process.
235
+
236
+ ## Notes
237
+
238
+ - This package intentionally has minimal dependencies to ensure it can be used in various environments
239
+ - The `TemplateEngineBase` uses the singleton pattern to ensure consistent metadata access across an application
240
+ - Template metadata is loaded from the MemberJunction database using the dataset system
241
+ - The `@RegisterClass` decorator on `TemplateEntityExtended` ensures proper integration with the MJ entity system
242
+
243
+ ## License
244
+
245
+ ISC
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@memberjunction/templates-base-types",
3
- "version": "2.42.1",
3
+ "version": "2.44.0",
4
4
  "description": "MemberJunction Templating Base Types for Client/Server Use",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",
@@ -18,8 +18,8 @@
18
18
  "typescript": "^5.4.5"
19
19
  },
20
20
  "dependencies": {
21
- "@memberjunction/core": "2.42.1",
22
- "@memberjunction/core-entities": "2.42.1",
23
- "@memberjunction/global": "2.42.1"
21
+ "@memberjunction/core": "2.44.0",
22
+ "@memberjunction/core-entities": "2.44.0",
23
+ "@memberjunction/global": "2.44.0"
24
24
  }
25
25
  }