@quandis/qbo4.configuration 4.0.1-CI-20240610-201642 → 4.0.1-CI-20240611-143233

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/package.json +1 -1
  2. package/readme.md +183 -5
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@quandis/qbo4.configuration",
3
- "version": "4.0.1-CI-20240610-201642",
3
+ "version": "4.0.1-CI-20240611-143233",
4
4
  "type": "module",
5
5
  "types": "./src/Program.d.ts",
6
6
  "exports": {
package/readme.md CHANGED
@@ -1,7 +1,15 @@
1
1
  # Overview
2
2
 
3
- The `@quandis/qbo4.Configuration.Web` package offers javascript classes to manage configuration settings for a web application.
4
- It is similar to Microsoft's `IConfiguration` patterns and extensions.
3
+ The `@quandis/qbo4.Configuration.Web` package offers:
4
+
5
+ - Management of options classes via dependency injection
6
+ - A `QboTemplate` web component base class that supports configuration driven rendering options
7
+
8
+
9
+ # Options Classes
10
+
11
+ Similar to Microsoft's `IConfiguration`, the `qbo4.Configuration` package's classes manage configuration settings
12
+ for a web application via dependency injection.
5
13
 
6
14
  Including the `qbo4.Configuration.js` script will provide:
7
15
 
@@ -11,7 +19,7 @@ Including the `qbo4.Configuration.js` script will provide:
11
19
 
12
20
  It provides for dependency injections via the `tsyringe` package.
13
21
 
14
- # Typescript Usage
22
+ ## Typescript Usage
15
23
 
16
24
  ```typescript
17
25
  import 'reflect-metadata';
@@ -35,7 +43,7 @@ const b = config.getSection('B').bind(OptionsB);
35
43
  expect(b.count).equal(27);
36
44
  ```
37
45
 
38
- # Browser Usage
46
+ ## Browser Usage
39
47
 
40
48
  ```html
41
49
  <html>
@@ -56,7 +64,7 @@ expect(b.count).equal(27);
56
64
  </html>
57
65
  ```
58
66
 
59
- # Example: ApplicationInsights Logger
67
+ ## Example: ApplicationInsights Logger
60
68
 
61
69
  Assume we want to inject an `ApplicationInsights` logger, where the `InstrumentationKey` is stored in the configuration settings.
62
70
 
@@ -83,3 +91,173 @@ export class ApplicationInsights {
83
91
  // Prepare the class for dependency injection
84
92
  export const ApplicationInsightsToken: InjectionToken<ApplicationInsights> = 'ApplicationInsights';
85
93
  ```
94
+
95
+ # QboTemplate Web Component
96
+
97
+ The `QboTemplate` web component enables power users to configure the rendering of a web component a runtime.
98
+ Assume we have a `Contact` web component that renders a contact's name, address, and other information,
99
+ and we choose to support different layouts based on a `type` attribute:
100
+
101
+ ```html
102
+ <qbo-contact type="fullname"></qbo-contact>
103
+ ```
104
+
105
+ should render:
106
+
107
+ ```html
108
+ <input name="first" placeholder="First name"/>
109
+ <input name="middle" placeholder="Middle name"/>
110
+ <input name="last" placeholder="Last name"/>
111
+ ```
112
+
113
+ Such a web component might look like this:
114
+
115
+ ```typescript
116
+ import { html } from 'lit';
117
+ import { customElement } from 'lit/decorators.js';
118
+
119
+ @customElement('qbo-contact')
120
+ export class ContactComponent extends LitElement {
121
+ jsonData: object = {
122
+ 'Contact': {
123
+ 'First': 'James',
124
+ 'Middle': 'Tiberious',
125
+ 'Last': 'Kirk'
126
+ }
127
+ }
128
+
129
+ render() {
130
+ return html`
131
+ <input name="first" placeholder="First name" value="${this.jsonData['Contact']['First']}"/>
132
+ <input name="middle" placeholder="Middle name" value="${this.jsonData['Contact']['Middle']}"/>
133
+ <input name="last" placeholder="Last name" value="${this.jsonData['Contact']['Last']}"/>
134
+ `;
135
+ }
136
+ }
137
+ ```
138
+
139
+ Futher assume that you want to allow a power user to configure the layout of the `qbo-contact` web component at runtime.
140
+ To accomplish this, shift the `ContactComponent` to derive from a `QboTemplate` class:
141
+
142
+ ```typescript
143
+ import { html } from 'lit';
144
+ import { customElement } from 'lit/decorators.js';
145
+ import { templates, TemplateFunction, QboTemplate } from '@quandis/qbo4.configuration';
146
+
147
+ export class ContactComponent extends QboTemplate {
148
+ constructor() {
149
+ super();
150
+ this.type ??= 'default';
151
+ }
152
+
153
+ jsonData: object = {
154
+ 'Contact': {
155
+ 'First': 'James',
156
+ 'Middle': 'Tiberious',
157
+ 'Last': 'Kirk'
158
+ }
159
+ }
160
+
161
+ // Notice: no render method here - see below.
162
+ }
163
+
164
+ const contactTemplates = new Map<string, TemplateFunction>();
165
+
166
+ contactTemplates.set('default', (component: any) => {
167
+ return html`<input name="first" placeholder="First name" value="${component.jsonData['Contact']['First']}"/>
168
+ <input name="middle" placeholder="Middle name" value="${component.jsonData['Contact']['Middle']}"/>
169
+ <input name="last" placeholder="Last name" value="${component.jsonData['Contact']['Last']}"/>`;
170
+ });
171
+
172
+ contactTemplates.set('reverse', (component: any) => {
173
+ return html`<input name="last" placeholder="Last name" value="${component.jsonData['Contact']['First']}"/>,
174
+ <input name="first" placeholder="Last name" value="${component.jsonData['Contact']['Last']}"/>
175
+ <input name="middle" placeholder="Middle name" value="${component.jsonData['Contact']['Middle']}"/>`
176
+ });
177
+
178
+ // template is a global variable set by the qbo4.configuration package
179
+ templates.set('ContactComponent', contactTemplates);
180
+ ```
181
+
182
+ Now you can render the `qbo-contact` web component with a `type` attribute:
183
+
184
+ ```html
185
+ <!-- This will render last name, first name, middle name -->
186
+ <qbo-contact type="reverse"></qbo-contact>
187
+
188
+ <!-- This will render first name, middle name, last name -->
189
+ <qbo-contact type="default"></qbo-contact>
190
+
191
+ <!-- So will this, because we set type = 'default' in the constructor -->
192
+ <qbo-contact></qbo-contact>
193
+ ```
194
+
195
+ > Note that the template functions accept a `component` parameter, which is the instance of the `ContactComponent` class.
196
+ Ensure you reference your component's properties via `component` rather than `this`.
197
+
198
+ Mapping `type` to different rendering functions is all well and good, but not particularly interesting.
199
+
200
+ The interesting part is allowing a power user to create new rendering functions (or edit existing ones) at runtime.
201
+
202
+ The `QboTemplate` class will listen for a `ctrl-dblclick` event if it is contained in an element with a `qbo-design` class
203
+ (indicating that we are in 'design' mode).
204
+
205
+ When the `ctrl-dblclick` event is triggered, a dialog will open, presenting the user with something like:
206
+
207
+ ---
208
+ **Edit Template**
209
+
210
+ | default &#8595; | <- *a datalist of available templates*
211
+
212
+ ```html
213
+ 1 <input name="first" placeholder="First name" value="${component.jsonData.Contact.First]}"/>
214
+ 2 <input name="middle" placeholder="Middle name" value="${component.jsonData.Contact.Middle]}"/>
215
+ 3 <input name="last" placeholder="Last name" value="${component.jsonData.Contact.Last}"/>
216
+ ```
217
+
218
+ ^ *an editor for editing the rendering function*
219
+
220
+ [ Save ] [ Cancel ]
221
+
222
+ ---
223
+
224
+ Feature include:
225
+
226
+ - As the power user modifies the template, the underlying UI will update in real-time.
227
+ - Any syntax errors will be trapped and displayed in the editor
228
+ - The editor can be dragged and resized as needed
229
+ - The `type` at the top can be selected from a `datalist`, and new types can be entered.
230
+ - Clicking `Save` will save the template in configuration (server-side), and be available for use.
231
+ - Clicking `Cancel` will discard any changes, reverting to the original rendering.
232
+
233
+ ## How it Works
234
+
235
+ Deployment of `@qbo4.Configuration` web components is paired with deployment of the `qbo4.Configuration.Web` Razor Class Library,
236
+ which includes server-side functionality to store are retrieve template code.
237
+ The `QboTemplate` class will interact with the server-side `/template` endpoint to store and retrieve templates.
238
+
239
+ The `QboTemplate` class will render the web component based on the `type` attribute, using the `templates` map.
240
+ If the `type` is not found in the `templates` map, the component will `fetch` templates stored in configuration
241
+ from the `/template/search/{ComponentClassName}` endpoint.
242
+
243
+ > If a component's `Typescript` class defines a `type` that also exists in configuration, the configuration will take precedence.
244
+
245
+ ## Spiderman Clause
246
+
247
+ With great power comes great responsibility. Only trusted user should be allowed to edit templates.
248
+ The ultimate control of this remains server-side with the authorization policies of the `/template` endpoints.
249
+ For the front-end, the `QboTemplate` class will only allow editing of templates if the containing element has a `qbo-design` class.
250
+ We recommend that the `qbo-design` class be added to the `body` for trusted power users only.
251
+ This will prevent accidental editing attempts of templates by regular users.
252
+
253
+ As with all qbo-based configuration, enable and test in a lower environment before deploying to production.
254
+
255
+ # RoadMap
256
+
257
+ - add intellisense to CodeMirror for component-specific properties (including Json data)
258
+ - shift the Editor to a separate web component
259
+ - enable custom Editors, to simplify changes to complex controls
260
+ - create a GUI designer that detects available web components via DI
261
+ - propagate changes to a components `type` property to parent components
262
+ - if a user creates a new `type` of an address control called `streetview`, and the address control is part of a property control, save the property control such that it uses `<qbo-address type="streetview">`
263
+ - add AI modifications to the default editor