HelpNDoc includes JSON support in its scripting, template, and dynamic content libraries. JSON (JavaScript Object Notation) is a lightweight data-interchange format that is easy to read and write for humans and machines. This feature enables dynamic content generation, external data integration, and enhanced customization within HelpNDoc projects.

To access JSON content, use the JSON object which has the following function:

Function

Description

Parse(content: string)

Parses a JSON string into a JSONVariant.

Example:

var jsonData := JSON.Parse('{"name": "Alice", "age": 25}');
Print(jsonData.name);  // Outputs: Alice
Print(jsonData.age);   // Outputs: 25

NewObject()

Creates a new empty JSON object.

Example:

var obj := JSON.NewObject();
obj.name := "Bob";
obj.age := 30;

Print(JSON.Stringify(obj)); // Outputs: {"name":"Bob","age":30}

NewArray()

Creates a new empty JSON array.

Example:

var arr := JSON.NewArray();
arr.Add(5);
arr.Add(10);

Print(JSON.Stringify(arr)); // Outputs: [5,10]

Stringify(value)

Serializes a value into a JSON string.

Example:

var obj := JSON.NewObject();
obj.key := "value";

Print(JSON.Stringify(obj)); // Outputs: {"key":"value"}

PrettyStringify(value; indent: string)

Serializes a value into a pretty-printed JSON string.

Example:

var obj := JSON.NewObject();
obj.title := "Example";
obj.values := JSON.NewArray();
obj.values.Add(1);
obj.values.Add(2);

Print(JSON.PrettyStringify(obj, "  "));
// Outputs:
// {
//   "title": "Example",
//   "values": [
//     1,
//     2
//   ]
// }

Serialize(value)

Converts a value to a JSONVariant.

Example:

var simpleValue := 123;
var jsonVariant := JSON.Serialize(simpleValue);

Print(JSON.Stringify(jsonVariant)); // Outputs: 123

Add(value)

Adds a value to a JSON array.

Example:

var arr := JSON.NewArray();
arr.Add("Item1");
arr.Add(42);

Print(JSON.Stringify(arr)); // Outputs: ["Item1",42]

Delete(key or index)

Removes a key-value pair from a JSON object or an element from an array.

Example:

// Deleting from an object
var obj := JSON.Parse('{"name": "Alice", "age": 25}');
obj.Delete("age");
Print(JSON.Stringify(obj)); // Outputs: {"name":"Alice"}

// Deleting from an array
var arr := JSON.Parse('[10, 20, 30]');
arr.Delete(1);
Print(JSON.Stringify(arr)); // Outputs: [10,30]

Extend(object)

Merges properties from another JSON object.

Example:

var baseObj := JSON.Parse('{"key1": "value1"}');
var extraObj := JSON.Parse('{"key2": "value2"}');
baseObj.Extend(extraObj);

Print(JSON.Stringify(baseObj)); // Outputs: {"key1":"value1","key2":"value2"}

Clone()

Creates a deep copy of the JSON object or array.

Example:

// Accessing keys in an object
var obj := JSON.Parse('{"key": "value"}');
Print(obj.key); // Outputs: value

// Accessing indices in an array
var arr := JSON.Parse('[10, 20, 30]');
Print(arr[1]);  // Outputs: 20

Usage in scripts and templates

Example: Parsing and Accessing JSON Data

var jsonData := JSON.Parse('{"key": "value", "array": [1, 2, 3]}');
Print(jsonData.key);           // Outputs: value
Print(jsonData.array[0]);      // Outputs: 1
Print(jsonData.array.length);  // Outputs: 3

Example: Creating and Modifying JSON

var obj := JSON.NewObject();
obj.name := "John";
obj.age := 30;

var arr := JSON.NewArray();
arr.Add(10);
arr.Add(20);

Print(JSON.Stringify(obj)); // {"name":"John","age":30}
Print(JSON.Stringify(arr)); // [10,20]

Example: Merging JSON Objects

Merge two JSON objects dynamically.

var obj1 := JSON.Parse('{"name": "John", "role": "Developer"}');
var obj2 := JSON.Parse('{"department": "Engineering", "role": "Team Lead"}');

obj1.Extend(obj2);  // obj1 will now include properties from obj2.

Print(JSON.Stringify(obj1));
// Outputs:
// {
//   "name": "John",
//   "role": "Team Lead",  // Overwritten by obj2
//   "department": "Engineering"
// }

Example: Nested JSON Object

Create a JSON object with nested objects and arrays.

var obj := JSON.NewObject();
obj.name := "John Doe";
obj.age := 35;
obj.address := JSON.NewObject();
obj.address.street := "123 Main St";
obj.address.city := "Springfield";
obj.hobbies := JSON.NewArray();
obj.hobbies.Add("Reading");
obj.hobbies.Add("Cycling");
obj.hobbies.Add("Hiking");

Print(JSON.Stringify(obj));
// Outputs:
// {
//   "name": "John Doe",
//   "age": 35,
//   "address": {
//     "street": "123 Main St",
//     "city": "Springfield"
//   },
//   "hobbies": ["Reading", "Cycling", "Hiking"]
// }

Example: JSON with Mixed Types

Create a JSON object containing various data types.

var obj := JSON.NewObject();
obj.title := "Sample Data";
obj.active := true;
obj.count := 10;
obj.details := JSON.NewObject();
obj.details.created := "2024-12-03";
obj.details.size := 15.7;
obj.tags := JSON.NewArray();
obj.tags.Add("example");
obj.tags.Add("test");

Print(JSON.PrettyStringify(obj, "  "));
// Outputs:
// {
//   "title": "Sample Data",
//   "active": true,
//   "count": 10,
//   "details": {
//     "created": "2024-12-03",
//     "size": 15.7
//   },
//   "tags": ["example", "test"]
// }

Example: Dynamically Adding Properties

Dynamically extend an existing JSON object.

var obj := JSON.NewObject();
obj.initial := "Start";
obj.data := JSON.NewObject();

for var i := 1 to 3 do begin
    var key := "field" + i.ToString();
    obj.data[key] := i * 10;
end;

Print(JSON.Stringify(obj));
// Outputs:
// {
//   "initial": "Start",
//   "data": {
//     "field1": 10,
//     "field2": 20,
//     "field3": 30
//   }
// }

Example: JSON Arrays with Complex Elements

Create a JSON array containing objects and arrays.

var arr := JSON.NewArray();

var item1 := JSON.NewObject();
item1.type := "fruit";
item1.name := "Apple";
item1.quantity := 5;

var item2 := JSON.NewObject();
item2.type := "vegetable";
item2.name := "Carrot";
item2.quantity := 3;

arr.Add(item1);
arr.Add(item2);

Print(JSON.Stringify(arr));
// Outputs:
// [
//   {"type": "fruit", "name": "Apple", "quantity": 5},
//   {"type": "vegetable", "name": "Carrot", "quantity": 3}
// ]

Example: Combining Objects and Arrays

Combine objects and arrays for complex hierarchical structures.

var dashboard := JSON.NewObject();
dashboard.title := "Dashboard";

dashboard.stats := JSON.NewObject();
dashboard.stats.totalUsers := 150;
dashboard.stats.activeUsers := 45;

dashboard.reports := JSON.NewArray();
var report1 := JSON.NewObject();
report1.id := 101;
report1.title := "Monthly Sales";
report1.data := JSON.NewArray();
report1.data.Add(1000);
report1.data.Add(1200);
report1.data.Add(950);

var report2 := JSON.NewObject();
report2.id := 102;
report2.title := "User Engagement";
report2.data := JSON.NewArray();
report2.data.Add(75);
report2.data.Add(80);
report2.data.Add(85);

dashboard.reports.Add(report1);
dashboard.reports.Add(report2);

Print(JSON.PrettyStringify(dashboard, "  "));
// Outputs:
// {
//   "title": "Dashboard",
//   "stats": {
//     "totalUsers": 150,
//     "activeUsers": 45
//   },
//   "reports": [
//     {
//       "id": 101,
//       "title": "Monthly Sales",
//       "data": [1000, 1200, 950]
//     },
//     {
//       "id": 102,
//       "title": "User Engagement",
//       "data": [75, 80, 85]
//     }
//   ]
// }