From 42efd2e2014bd6ceadc654ccf736848054e97010 Mon Sep 17 00:00:00 2001
From: Peter Conijn <p.conijn@dysel.com>
Date: Tue, 3 Sep 2024 12:13:46 +0200
Subject: [PATCH] #245 Added page for key strings

---
 .../string-value-tokens/index.md              | 72 +++++++++++++++++++
 1 file changed, 72 insertions(+)
 create mode 100644 content/docs/BestPractices/string-value-tokens/index.md

diff --git a/content/docs/BestPractices/string-value-tokens/index.md b/content/docs/BestPractices/string-value-tokens/index.md
new file mode 100644
index 00000000..585bd4cd
--- /dev/null
+++ b/content/docs/BestPractices/string-value-tokens/index.md
@@ -0,0 +1,72 @@
+---
+title: "String Values in Tokens"
+tags: ["AL","Readability", "Maintainability"]
+categories: ["Best Practice"]
+---
+
+_Created by Microsoft, Described by Peter Conijn_
+
+## Description
+In some cases, notably when storing or retrieving values in key/value objects like dictionaries, XML or JSON objects, you will require a key value. In order to keep these tags maintainable, these key values should never be hard-coded, but should be stored in locked labels. Such locked labels should - as per convention - have the suffix -Tok.
+
+## Example 1
+
+In this example, we show the wrong and right way to store values into a JSON object. These examples or course also applies to other key/value types. Do note that in these examples, as per JSON guidlines, the keys are in camelCase rather than PascalCase.
+
+### Bad code
+
+```al
+    local procedure AddValuesToJson(Customer: Record Customer) JObject: JsonObject
+    begin
+        JObject.Add('customerName', Customer.Name);
+        JObject.Add('customerAddress', Customer.Address);
+    end;
+```
+
+### Good code
+
+```al
+    var
+        NameKeyTok: Label 'customerName', Locked = true;
+        AddressKeyTok: Label 'customerAddress', Locked = true;
+
+    local procedure AddValuesToJson(Customer: Record Customer) JObject: JsonObject
+    begin
+        JObject.Add(NameKeyTok, Customer.Name);
+        JObject.Add(AddressKeyTok, Customer.Address);        
+    end;
+```
+
+## Example 2
+
+### Bad code
+
+```al
+    local procedure ParseJsonObject(JObject: JsonObject)
+    var
+        Customer: Record Customer;
+    begin
+        Customer.Init();
+        Customer.Name := GetJsonValueAsText(JObject, 'customerName');
+        Customer.Address := GetJsonValueAsText(JObject, 'customerAddress');
+        // ...More code...
+    end;
+```
+
+### Good code
+
+```al
+    var
+        NameKeyTok: Label 'customerName', Locked = true;
+        AddressKeyTok: Label 'customerAddress', Locked = true;
+
+    local procedure ParseJsonObject(JObject: JsonObject)
+    var
+        Customer: Record Customer;
+    begin
+        Customer.Init();
+        Customer.Name := GetJsonValueAsText(JObject, NameKeyTok);
+        Customer.Address := GetJsonValueAsText(JObject, AddressKeyTok);
+        // ...More code...
+    end;
+```
\ No newline at end of file