0
# Template Rendering
1

2
Core template rendering functionality that transforms JSON data into HTML using JavaScript template objects with support for embedded events, string interpolation, and complex data structures.
3

4
## Capabilities
5

6
### Render Function
7

8
Transforms JSON objects into HTML using template objects with JavaScript-based template syntax.
9

10
```javascript { .api }
11
/**
12
 * Renders JSON object to HTML string using template
13
 * @param {object|string|array} obj - JSON object, array, or JSON string to render
14
 * @param {object|array} template - json2html template (object/array/JSON string)
15
 * @param {object} [options] - Optional configuration
16
 * @param {object} [options.props] - Properties for template rendering (accessible via @property)
17
 * @param {object} [options.components] - Local component definitions (name:template pairs)
18
 * @param {string} [options.output="html"] - Output type: "html" (string) or "ihtml" (object)
19
 * @returns {string|iHTML} Rendered HTML string or iHTML object based on output option
20
 */
21
function render(obj, template, options);
22
```
23

24
**Usage Examples:**
25

26
```javascript
27
const json2html = require('node-json2html');
28

29
// Simple object rendering
30
const user = { name: "Alice", age: 30 };
31
const template = { "<>": "div", "text": "Name: ${name}, Age: ${age}" };
32
const html = json2html.render(user, template);
33
// Result: <div>Name: Alice, Age: 30</div>
34

35
// Array rendering
36
const users = [
37
  { name: "Alice", age: 30 },
38
  { name: "Bob", age: 25 }
39
];
40
const listTemplate = { "<>": "li", "text": "${name} (${age})" };
41
const html = json2html.render(users, listTemplate);
42
// Result: <li>Alice (30)</li><li>Bob (25)</li>
43

44
// Complex nested templates
45
const complexTemplate = {
46
  "<>": "div",
47
  "class": "user-card",
48
  "html": [
49
    { "<>": "h2", "text": "${name}" },
50
    { "<>": "p", "text": "Age: ${age}" },
51
    { "<>": "button", "text": "Edit", "onclick": function(e) { alert("Edit " + this.name); } }
52
  ]
53
};
54

55
// Using properties
56
const propsTemplate = { "<>": "div", "text": "${name} - ${@title}" };
57
const html = json2html.render(
58
  { name: "Alice" },
59
  propsTemplate,
60
  { props: { title: "Administrator" } }
61
);
62
// Result: <div>Alice - Administrator</div>
63
```
64

65
### Template Syntax
66

67
json2html uses a JavaScript object-based template syntax with special properties:
68

69
```javascript { .api }
70
/**
71
 * Template object structure with special properties
72
 */
73
interface Template {
74
  /** HTML element tag name */
75
  "<>"?: string;
76
  
77
  /** Object or function for data transformation */
78
  "{}"?: object | function;
79
  
80
  /** Component reference by name */
81
  "[]"?: string;
82
  
83
  /** Text content (HTML-encoded) */
84
  "text"?: string | function;
85
  
86
  /** HTML content (raw or nested templates) */
87
  "html"?: string | function | object[];
88
  
89
  /** Two-way data binding for form elements */
90
  ">>"?: string;
91
  
92
  /** Refresh/update trigger ID */
93
  "#"?: string;
94
  
95
  /** Event handlers (onclick, onchange, etc.) */
96
  [key: `on${string}`]: function;
97
  
98
  /** Standard HTML attributes */
99
  [attribute: string]: any;
100
}
101
```
102

103
**Template Property Examples:**
104

105
```javascript
106
// HTML element with attributes
107
{ "<>": "div", "class": "container", "id": "main" }
108
// Result: <div class="container" id="main"></div>
109

110
// Text content (HTML-encoded)
111
{ "<>": "p", "text": "${message}" }
112
// Input: { message: "<script>alert('xss')</script>" }
113
// Result: <p>&lt;script&gt;alert('xss')&lt;/script&gt;</p>
114

115
// HTML content (raw)
116
{ "<>": "div", "html": "<strong>Bold text</strong>" }
117
// Result: <div><strong>Bold text</strong></div>
118

119
// Nested templates
120
{
121
  "<>": "article",
122
  "html": [
123
    { "<>": "h1", "text": "${title}" },
124
    { "<>": "p", "text": "${content}" }
125
  ]
126
}
127

128
// Event handlers
129
{
130
  "<>": "button",
131
  "text": "Click me",
132
  "onclick": function(e) {
133
    console.log("Button clicked!", this, e);
134
  }
135
}
136

137
// Two-way data binding
138
{
139
  "<>": "input",
140
  "type": "text",
141
  "value": "${name}",
142
  ">>": "name"  // Updates the name property when input changes
143
}
144

145
// Component reference
146
{ "[]": "user-card", "user": "${.}", "theme": "dark" }
147
```
148

149
### String Interpolation
150

151
Template strings support `${path}` syntax for accessing object properties and array indices:
152

153
```javascript { .api }
154
/**
155
 * String interpolation patterns
156
 */
157
// Object property access
158
"${name}"           // obj.name
159
"${user.name}"      // obj.user.name
160
"${user.address.city}" // obj.user.address.city
161

162
// Array access patterns
163
"${0}"              // array[0] (for literal arrays)
164
"${items.0.name}"   // obj.items[0].name
165

166
// Properties access (prefix with @)
167
"${@theme}"         // options.props.theme
168
"${@config.mode}"   // options.props.config.mode
169

170
// Special values for literal arrays
171
"${value}"          // The literal value when rendering arrays of primitives
172
"${index}"          // The current array index
173
```
174

175
**Interpolation Examples:**
176

177
```javascript
178
// Object property interpolation
179
const data = { 
180
  user: { 
181
    name: "Alice", 
182
    profile: { city: "New York" } 
183
  } 
184
};
185
const template = { "<>": "span", "text": "${user.name} from ${user.profile.city}" };
186
// Result: <span>Alice from New York</span>
187

188
// Array literal rendering
189
const numbers = [1, 2, 3];
190
const template = { "<>": "li", "text": "Item ${index}: ${value}" };
191
// Result: <li>Item 0: 1</li><li>Item 1: 2</li><li>Item 2: 3</li>
192

193
// Properties interpolation
194
const template = { "<>": "div", "class": "${@theme}-container" };
195
const html = json2html.render({}, template, { props: { theme: "dark" } });
196
// Result: <div class="dark-container"></div>
197
```
198

199
### Function Templates
200

201
Templates support JavaScript functions for dynamic content generation and data transformation:
202

203
```javascript { .api }
204
/**
205
 * Function-based template properties
206
 * @param {object} obj - Current data object being rendered
207
 * @param {number} index - Current array index (if rendering array)
208
 * @param {object} props - Properties object from options.props
209
 * @param {string} [html] - Inner HTML content (for html property functions)
210
 * @returns {any} Value to use for the template property
211
 */
212
function templateFunction(obj, index, props, html);
213
```
214

215
**Function Examples:**
216

217
```javascript
218
// Dynamic text generation
219
const template = {
220
  "<>": "div",
221
  "text": function(obj, index, props) {
222
    return `User ${obj.name} is ${obj.age >= 18 ? 'adult' : 'minor'}`;
223
  }
224
};
225

226
// Dynamic HTML generation
227
const template = {
228
  "<>": "div",
229
  "html": function(obj, index, props) {
230
    if (obj.isAdmin) {
231
      return [
232
        { "<>": "h2", "text": "Admin: ${name}" },
233
        { "<>": "button", "text": "Admin Panel" }
234
      ];
235
    }
236
    return { "<>": "span", "text": "${name}" };
237
  }
238
};
239

240
// Data transformation with {} property
241
const template = {
242
  "{}": function(obj, index, props) {
243
    return {
244
      ...obj,
245
      displayName: `${obj.firstName} ${obj.lastName}`,
246
      isActive: obj.status === 'active'
247
    };
248
  },
249
  "<>": "div",
250
  "text": "${displayName} (${isActive})"
251
};
252
```
253

254
### Output Modes
255

256
The render function supports two output modes controlled by the `options.output` parameter:
257

258
```javascript { .api }
259
// HTML string output (default)
260
const html = json2html.render(data, template);
261
// Returns: string
262

263
// iHTML object output (for browser usage with events)
264
const ihtml = json2html.render(data, template, { output: "ihtml" });
265
// Returns: iHTML object with html, events, and triggers properties
266
```
267

268
**iHTML Output Example:**
269

270
```javascript
271
const template = {
272
  "<>": "button",
273
  "text": "Click me",
274
  "onclick": function(e) { alert("Clicked!"); }
275
};
276

277
const ihtml = json2html.render({}, template, { output: "ihtml" });
278
console.log(ihtml.html);      // "<button>Click me</button>"
279
console.log(ihtml.events);    // { "randomId": { type: "click", action: function... } }
280
console.log(ihtml.triggers);  // {}
281
```