Update implement-custom-segment-parameters.md

Author: dtng95

16/umbraco-engage/marketers-and-editors/personalization/extending-personalization/implement-custom-segment-parameters.md

@@ -5,20 +5,21 @@ description: >-
 
 # Implement your own segment parameters
 
-Umbraco Engage comes with various built-in segment parameters to build a segment, such as "Customer Journey" and "Time of Day". However, you may want to build segments with custom rules that are not part of Engage by default. We've got you covered; you can add your own custom segment parameters to the Engage.
+Umbraco Engage comes with built-in parameters to build a segment, such as "Customer Journey" and "Time of Day". 
+However, you may want to build segments with custom rules that are not part of Engage by default. We've got you covered; you can add your own custom segment parameters to Engage.
 
 The following guide will explain how this can be done. Note this is aimed at developers.
 There are 3 steps, 2 of which are mandatory and the 3rd is optional:
 
 1. C# definition
-2. AngularJS definition
-3. (optional) Cockpit visualization
+2. Web component definition
+3. Cockpit visualization (optional)
 
 This guide will use concrete code samples to add a "Day of week" segment parameter where you can select a single day of the week. If a pageview happens on that day the segment parameter will be satisfied.
 
 ## 1. C# definition
 
-Your custom segment parameter will need to be defined in C# in order for the Engage to use it.
+Your custom segment parameter will need to be defined in C# in order for Engage to use it.
 In code we refer to a segment parameter as a "segment rule".
 
 A segment rule is not much more than this:
@@ -70,7 +71,8 @@ public class DayOfWeekSegmentRuleFactory : ISegmentRuleFactory
 }
 ```
 
-We are using the class DayOfWeekSegmentRuleConfig as a representation of the configuration of the rule, which is not strictly necessary but makes it easier. The configuration is stored as a string in the database but in code we like to have intellisense so we parse the stored configuration to this class:
+We are using the class DayOfWeekSegmentRuleConfig to represent the rule configuration. This is not strictly necessary but makes it easier. 
+The configuration is stored as a string in the database. In code we like to have intellisense so we parse the stored configuration to this class:
 
 ```c#
 //Generating config schema on client side.
@@ -83,19 +85,87 @@ public class DayOfWeekSegmentRuleConfig
 
 That's the C# part of the custom segment parameter.
 
-## 2. Lit definition
+## 2. Web component definition
 
-We have implemented the business logic for the segment parameter in the previous step, but the parameter cannot be added to your segments in the backoffice yet. In this step we will add a Lit element to enable you to add and configure your segments in the Engage segment builder.
+We have implemented the business logic for the segment parameter, but the parameter cannot be used in the backoffice yet. In this step we will add a web component to render the new rule in the Engage segment builder.
 
 These steps will once again show concrete code samples that belong to our demo parameter "Day of week".
+You can create a folder to manage new files. Those files look like this:
+* segment-rule-base.ts
+    * Type declaration for UeSegmentRuleBaseElement from Umbraco Engage. This is a temporary declaration until Umbraco Engage provides an npm package.
+* segment-rule-day-of-week.ts
+    * Declaration for your web component using Lit.
+* index.ts
+    * Exporting all your elements.
+* manifest.ts
+    * Declares your element as a backoffice extension and register it  in the Extension Registry. Read more about Extension Manifest [here](../../../../umbraco-cms/customizing/extending-overview/extension-registry/extension-manifest.md/).
 
 First, re-generate the DayOfWeek config type on client side using the below command
 
 ```text
 npm run generate:api
 ```
 
-Then, create a new Lit element, implemeting new "Day of week" segment.
+**segment-rule-base.ts**
+
+```typescript
+enum RuleDirection {
+  INCLUDE = "include",
+  EXCLUDE = "exclude",
+}
+
+export interface UeSegmentRuleParameterConfig<ValueType> {
+  isNegation: boolean;
+  config: ValueType;
+}
+
+export class UeSegmentRuleBaseElement<UeSegmentRuleParameterConfig> extends UmbLitElement {
+  abstract renderReadOnly();
+  abstract renderEditor();
+  value: UeSegmentRuleParameterConfig;
+  initialized: Promise<void>;
+
+  @property({ type: Boolean, attribute: true, reflect: true })
+  readonly?: boolean;
+
+  updateParameterValue(value: any, key: keyof ValueType) {
+    if (!this.value?.config) return;
+
+    const config = { ...(this.value.config ?? {}), ...{ [key]: value } };
+    this.pending = assignToFrozenObject(this.value, { config });
+    this.renderReadOnly();
+  }
+
+  render() {
+    return this.readonly ? this.#renderReadOnly() : this.#renderEditor();
+  }
+
+  #renderReadOnly() {
+    return html`
+        <div id="readonly" .title=${this.manifest?.meta.name ?? ""}>
+            <uui-icon .name=${this.manifest?.meta.icon ?? "icon-document"}></uui-icon>
+            ${this.renderReadOnly()}
+        </div>
+    `;
+  }
+
+  #renderEditor() {
+    return html`
+        <div id="editorHeader">
+        <h3>${this.manifest?.meta.name}</h3>
+        <ue-button-group
+          .values=${Object.values(RuleDirection)}
+          .value=${this.value?.isNegation
+            ? RuleDirection.EXCLUDE
+            : RuleDirection.INCLUDE}
+        ></ue-button-group>
+      </div>
+      <div id="editor">${this.renderEditor()}</div>
+    `;
+  }
+}
+
+```
 
 **segment-rule-day-of-week.ts**
 
@@ -163,27 +233,40 @@ declare global {
 
 ```
 
-Then, register this element in a manifest file.
+**index.ts**
+
+```text
+export { UeSegmentRuleDayOfWeekElement } from "./segment-rule-day-of-week.js";
+export { UeSegmentRuleBaseElement } from "./segment-rule-base.js";
+```
 
 **manifest.ts**
 
 ```json
 {
-    name: "Day of week",
-    type: "DayOfWeek",
-    icon: "icon-calendar",
-    elementName: "day-of-week",
-    config: { dayOfWeek: "Sunday" },
+    type: ENGAGE_SEGMENT_RULE_EXTENSION_TYPE,
+    name: 'Engage Day of Week Segment Rule',
+    alias: 'Engage.Segment.Rule.DayOfWeek',
+    elementName: 'ue-segment-rule-day-of-week',
+    weight: 100,
+    meta: {
+        name: 'Day of week',
+        icon: 'icon-calendar',
+        type: 'DayOfWeek',
+        config: { dayOfWeek: 'Sunday' },
+    },
 }
 ```
 
 That's it. If all went well you will see your custom parameter editor show up in the segment builder:
 
 <figure><img src="../../../.gitbook/assets/engage-tutorials-personalized-segments-v16.png" alt="Day of week Segment."><figcaption><p>Day of week Segment.</p></figcaption></figure>
 
-## 3. (optional) Cockpit visualization
+## 3. Cockpit visualization (optional)
+
+The new segment parameter will show up automatically in the Cockpit that is part of our package. The cockpit is a live view of Engage data for the current visitor. This includes active segments of the current visitor, and therefore your new segment parameter can also show up in the cockpit. 
 
-The new segment parameter will show up automatically in the Cockpit that is part of our package. The cockpit is a live view of Engage data for the current visitor. This includes active segments of the current visitor, and therefore your new segment parameter can also show up in the cockpit. By default it will simply display the the raw configuration of the parameter as stored in the database ("{ dayOfWeek: Thursday }" in our example), and if you hover over it you will see the rule identifier "DayOfWeek" rather than a friendly name.
+By default it will simply display the the raw configuration of the parameter as stored in the database ("{ dayOfWeek: Thursday }" in our example), and if you hover over it you will see the rule identifier "DayOfWeek" rather than a friendly name.
 
 <figure><img src="../../../.gitbook/assets/engage-tutorials-personalized-segments-cockpit-v16.png"></figure>