0
# Component Management
1

2
System for creating and managing reusable template components that can be referenced by name in templates. Components provide modularity and reusability across different templates and rendering contexts.
3

4
## Capabilities
5

6
### Add Components
7

8
Register single or multiple reusable template components that can be referenced by name in templates.
9

10
```javascript { .api }
11
/**
12
 * Add a single component with name and template
13
 * @param {string} name - Component name for referencing
14
 * @param {object} template - Template object defining the component
15
 */
16
function add(name, template);
17

18
/**
19
 * Add multiple components from an object
20
 * @param {object} components - Object with name:template pairs
21
 */
22
function add(components);
23
```
24

25
**Usage Examples:**
26

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

30
// Add a single component
31
json2html.component.add('user-card', {
32
  "<>": "div",
33
  "class": "user-card",
34
  "html": [
35
    { "<>": "h3", "text": "${name}" },
36
    { "<>": "p", "text": "Age: ${age}" },
37
    { "<>": "span", "class": "status", "text": "${status}" }
38
  ]
39
});
40

41
// Add multiple components at once
42
json2html.component.add({
43
  'header': {
44
    "<>": "header",
45
    "class": "page-header",
46
    "html": { "<>": "h1", "text": "${title}" }
47
  },
48
  'footer': {
49
    "<>": "footer",
50
    "class": "page-footer", 
51
    "html": { "<>": "p", "text": "© ${year} ${company}" }
52
  },
53
  'button': {
54
    "<>": "button",
55
    "class": "${@theme} btn",
56
    "text": "${label}",
57
    "onclick": function(e) {
58
      if (this.onClick) this.onClick(e);
59
    }
60
  }
61
});
62
```
63

64
### Get Components
65

66
Retrieve registered component templates by name for inspection or programmatic usage.
67

68
```javascript { .api }
69
/**
70
 * Retrieve a component template by name
71
 * @param {string} name - Component name
72
 * @returns {object|undefined} Component template object or undefined if not found
73
 */
74
function get(name);
75
```
76

77
**Usage Examples:**
78

79
```javascript
80
// Retrieve a component
81
const userCardTemplate = json2html.component.get('user-card');
82
console.log(userCardTemplate);
83
// Returns: { "<>": "div", "class": "user-card", "html": [...] }
84

85
// Check if component exists
86
const buttonTemplate = json2html.component.get('button');
87
if (buttonTemplate) {
88
  console.log('Button component is registered');
89
} else {
90
  console.log('Button component not found');
91
}
92

93
// Get non-existent component
94
const missing = json2html.component.get('non-existent');
95
console.log(missing); // undefined
96
```
97

98
### Using Components in Templates
99

100
Reference registered components in templates using the `"[]"` property and pass data through other properties.
101

102
```javascript { .api }
103
/**
104
 * Component reference template structure
105
 */
106
interface ComponentTemplate {
107
  /** Component name reference */
108
  "[]": string;
109
  
110
  /** Inner HTML content for the component (optional) */
111
  "html"?: object[] | object;
112
  
113
  /** Any other properties are passed as data to the component */
114
  [property: string]: any;
115
}
116
```
117

118
**Component Usage Examples:**
119

120
```javascript
121
// Register a flexible card component
122
json2html.component.add('card', {
123
  "<>": "div",
124
  "class": "card ${@variant}",
125
  "html": [
126
    { "<>": "div", "class": "card-header", "html": "${title}" },
127
    { "<>": "div", "class": "card-body", "html": "${html}" },
128
    { "<>": "div", "class": "card-footer", "text": "${footer}" }
129
  ]
130
});
131

132
// Use the component in templates
133
const template = {
134
  "<>": "div",
135
  "class": "container",
136
  "html": [
137
    {
138
      "[]": "card",
139
      "title": "Welcome",
140
      "footer": "Last updated: ${lastUpdated}",
141
      "html": [
142
        { "<>": "p", "text": "Hello ${name}!" },
143
        { "<>": "button", "text": "Get Started" }
144
      ]
145
    }
146
  ]
147
};
148

149
const data = { name: "Alice", lastUpdated: "2023-12-01" };
150
const html = json2html.render(data, template, { 
151
  props: { variant: "primary" } 
152
});
153
```
154

155
### Component Properties and Context
156

157
Components receive data through template properties and can access the current rendering context.
158

159
```javascript { .api }
160
/**
161
 * Component context and data flow
162
 */
163
// Properties passed to component template:
164
// - All properties except "[]" and "html" are available as data
165
// - "html" property provides nested content accessible via ${html}
166
// - Parent object data is available through normal interpolation
167
// - Global properties available via @property syntax
168
```
169

170
**Component Context Examples:**
171

172
```javascript
173
// Register a list item component
174
json2html.component.add('list-item', {
175
  "<>": "li",
176
  "class": "${@itemClass}",
177
  "data-id": "${id}",
178
  "html": [
179
    { "<>": "span", "class": "label", "text": "${label}" },
180
    { "<>": "div", "class": "content", "html": "${html}" }
181
  ]
182
});
183

184
// Use component with various data sources
185
const template = {
186
  "<>": "ul",
187
  "html": [
188
    {
189
      "[]": "list-item",
190
      "id": "${id}",           // From current data object
191
      "label": "${name}",      // From current data object  
192
      "html": [
193
        { "<>": "p", "text": "${description}" },
194
        { "<>": "small", "text": "Created: ${@currentDate}" }  // From props
195
      ]
196
    }
197
  ]
198
};
199

200
const items = [
201
  { id: 1, name: "Task 1", description: "Complete the project" },
202
  { id: 2, name: "Task 2", description: "Review the code" }
203
];
204

205
const html = json2html.render(items, template, {
206
  props: { 
207
    itemClass: "task-item",
208
    currentDate: new Date().toLocaleDateString()
209
  }
210
});
211
```
212

213
### Local vs Global Components
214

215
Components can be defined globally (available across all renders) or locally (specific to a single render call).
216

217
```javascript { .api }
218
// Global components (persistent across renders)
219
json2html.component.add('global-header', { "<>": "h1", "text": "${title}" });
220

221
// Local components (specific to single render)
222
const html = json2html.render(data, template, {
223
  components: {
224
    'local-badge': { 
225
      "<>": "span", 
226
      "class": "badge ${@color}", 
227
      "text": "${count}" 
228
    }
229
  }
230
});
231
```
232

233
**Local Component Priority:**
234

235
```javascript
236
// Global component
237
json2html.component.add('button', {
238
  "<>": "button",
239
  "class": "btn-default",
240
  "text": "${label}"
241
});
242

243
// Local component overrides global for this render
244
const html = json2html.render(
245
  { label: "Save" },
246
  { "[]": "button" },
247
  {
248
    components: {
249
      'button': {  // This overrides the global button component
250
        "<>": "button",
251
        "class": "btn-primary",
252
        "text": "${label}",
253
        "type": "submit"
254
      }
255
    }
256
  }
257
);
258
// Uses the local button component definition
259
```
260

261
### Dynamic Component References
262

263
Component names can be dynamic using string interpolation, allowing for conditional component selection.
264

265
```javascript { .api }
266
// Dynamic component selection
267
const template = {
268
  "[]": "${componentType}",  // Dynamic component name
269
  "data": "${.}"             // Pass current object as data
270
};
271

272
const data = [
273
  { componentType: "user-card", name: "Alice", type: "user" },
274
  { componentType: "admin-card", name: "Bob", type: "admin" }
275
];
276

277
// Register different components for different types
278
json2html.component.add('user-card', {
279
  "<>": "div", "class": "user", "text": "${name}"
280
});
281

282
json2html.component.add('admin-card', {
283
  "<>": "div", "class": "admin", "text": "Admin: ${name}"
284
});
285

286
const html = json2html.render(data, template);
287
// Renders different components based on componentType property
288
```