0
# json2html
1

2
json2html is a pure JavaScript templating library that transforms JSON objects into HTML using JavaScript template objects. It provides both client-side and server-side rendering capabilities with embedded event handling, reusable components, dynamic template updates, and inline JavaScript functions for complex logic.
3

4
## Package Information
5

6
- **Package Name**: node-json2html
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install node-json2html`
10

11
## Core Imports
12

13
```javascript
14
const json2html = require('node-json2html');
15
```
16

17
For TypeScript:
18

19
```typescript
20
import json2html from 'node-json2html';
21
const { render, component } = json2html;
22
```
23

24
## Basic Usage
25

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

29
// Basic template rendering
30
const data = [
31
  {"name": "Sasha", "age": 27},
32
  {"name": "Bobby", "age": 45}
33
];
34

35
const template = {
36
  "<>": "li", 
37
  "html": [
38
    {"<>": "span", "text": "${name} (${age} years old)"}
39
  ]
40
};
41

42
const html = json2html.render(data, template);
43
console.log(html);
44
// Output: <li><span>Sasha (27 years old)</span></li><li><span>Bobby (45 years old)</span></li>
45
```
46

47
## Architecture
48

49
json2html is built around several key components:
50

51
- **Template Engine**: Core rendering system that processes JSON templates and data objects
52
- **Interactive HTML (iHTML)**: Internal object type that combines HTML with event handlers and triggers
53
- **Component System**: Reusable template components with registration and retrieval
54
- **Event System**: Embedded event handling within templates for client-side interactivity
55
- **String Interpolation**: `${property}` syntax for dynamic data binding
56
- **Browser Extensions**: jQuery and native DOM integration for client-side usage
57

58
## Capabilities
59

60
### Template Rendering
61

62
Core template rendering functionality that transforms JSON data into HTML using JavaScript template objects.
63

64
```javascript { .api }
65
/**
66
 * Renders JSON object to HTML string using template
67
 * @param {object|string} obj - JSON object, array, or JSON string to render
68
 * @param {object} template - json2html template (object/array/JSON string)
69
 * @param {object} [options] - Optional configuration
70
 * @param {object} [options.props] - Properties for template rendering
71
 * @param {object} [options.components] - Local component definitions
72
 * @param {string} [options.output="html"] - Output type: "html" or "ihtml"
73
 * @returns {string|iHTML} Rendered HTML string or iHTML object
74
 */
75
function render(obj, template, options);
76
```
77

78
[Template Rendering](./rendering.md)
79

80
### Component Management
81

82
System for creating and managing reusable template components that can be referenced by name in templates.
83

84
```javascript { .api }
85
/**
86
 * Add a single component or multiple components
87
 * @param {string|object} name - Component name or object with name:template pairs
88
 * @param {object} [template] - Template object (required when name is string)
89
 */
90
function add(name, template);
91

92
/**
93
 * Retrieve a component template by name
94
 * @param {string} name - Component name
95
 * @returns {object|undefined} Component template or undefined if not found
96
 */
97
function get(name);
98
```
99

100
[Component Management](./components.md)
101

102
### Browser Integration
103

104
Client-side DOM manipulation and jQuery integration for interactive web applications.
105

106
```javascript { .api }
107
/**
108
 * Render template and append/prepend/replace DOM element content
109
 * @param {object} obj - JSON object to render
110
 * @param {object} template - json2html template
111
 * @param {object} [options] - Options including method: "append", "prepend", "replace"
112
 * @returns {Element} The element for chaining
113
 */
114
Element.prototype.json2html(obj, template, options);
115

116
/**
117
 * jQuery version of render with DOM manipulation
118
 * @param {object} obj - JSON object to render
119
 * @param {object} template - json2html template
120
 * @param {object} [options] - Options including method for DOM insertion
121
 * @returns {jQuery} jQuery object for chaining
122
 */
123
$.fn.json2html(obj, template, options);
124
```
125

126
[Browser Integration](./browser-integration.md)
127

128
### Utility Functions
129

130
Helper functions for text encoding, DOM hydration, and component updates.
131

132
```javascript { .api }
133
/**
134
 * Encodes HTML string to text by escaping HTML entities
135
 * @param {string} html - HTML string to encode
136
 * @returns {string} Text with HTML entities escaped
137
 */
138
function toText(html);
139

140
/**
141
 * Hydrates DOM elements with their events and update triggers
142
 * @param {Element|Element[]} parent - Element(s) to hydrate
143
 * @param {object} events - Event handlers object
144
 * @param {object} triggers - Update triggers object
145
 * @returns {object} this for chaining
146
 */
147
function hydrate(parent, events, triggers);
148

149
/**
150
 * Triggers component update by ID
151
 * @param {string} id - ID of component to update
152
 * @param {object} [obj] - Optional object to use for update
153
 */
154
function refresh(id, obj);
155
```
156

157
[Utility Functions](./utilities.md)
158

159
## Types
160

161
```javascript { .api }
162
/**
163
 * Interactive HTML object that contains HTML and associated events/triggers
164
 */
165
class iHTML {
166
  constructor(html);
167
  
168
  /** HTML content string */
169
  html: string;
170
  
171
  /** Associated event handlers */
172
  events: object;
173
  
174
  /** Associated update triggers */
175
  triggers: object;
176
  
177
  /**
178
   * Append another iHTML object or HTML string
179
   * @param {iHTML|string} obj - Object to append
180
   * @returns {iHTML} This object for chaining
181
   */
182
  append(obj): iHTML;
183
  
184
  /**
185
   * Append HTML string to content
186
   * @param {string} html - HTML string to append
187
   * @returns {iHTML} This object for chaining
188
   */
189
  appendHTML(html): iHTML;
190
  
191
  /**
192
   * Returns object representation
193
   * @returns {object} Object with html, events, and triggers
194
   */
195
  toJSON(): object;
196
}
197
```