# HTML Encoder
[](https://travis-ci.org/odedshr/html-encoder-core)
[](https://github.com/odedshr/html-encoder/blob/master/LICENSE)
## The Main Gist
HTML-Encoder converts your template HTML file to JSON instructions that can be piped to a JavaScript/TypeScript function (henceforth JSNode).
The file can then be embedded in either server-side or client-side code. It's pretty much like [JSX](https://reactjs.org/docs/introducing-jsx.html) or [Svelete](https://svelte.dev/).
See a live example at the [showcase](https://odedshr.github.io/html-encoder-showcase/).
### Installing
```bash
npm install html-encoder
```
### Usage
```typescript
import htmlEncoder, { TargetType } from 'html-encoder';
const xmlString:string = '...';
const targetType?:TargetType = 'js';
const isServerSide?:boolean = false;
const codeFile:string = htmlEncoder(xmlString, targetType, isServerSide);
/**
* Generates a string of instructions how to recreate the provided XML
* @param string xmlString - can be simple text string, but it if it's XML (HTML or SVG, for example) it'll be parsed accordingly
* @param TargetType targetType - supported output type. Current available statuses are json, js (javascript), es ("js" file but in ES6 format), ts (typescript) or 'code' which outputs the actual function, ready to be used.
* @param boolean isServerSide - a flag indicating whether code should include additional comments that will help the file become dynamic once sent to the browser
* @return string - instructions to recreate the HTML.
*/
```
Standard JS output is [commonJS](https://medium.com/@cgcrutch18/commonjs-what-why-and-how-64ed9f31aa46#:~:text=CommonJS%20is%20a%20module%20formatting,heavily%20influenced%20NodeJS's%20module%20management.)-compliant; Should you wish to have a [ESNext](https://www.javascripttutorial.net/es-next/), you can use the type `es`.
A simple usage example:
```javascript
import htmlEncoder from 'html-encoder';
const Node = htmlEncoder('
Hello
','code');
document.appendChild(new Node({name:'World'}));
```
### How to use the output
Once the returned string is saved, you can then easily embed by importing it to your code and appending the node to the DOM tree:
```javascript
import { getNode } from 'login-screen.template.js';
document.appendChild(getNode());
```
## Dynamic Content Support
`HTML-encoder` supports dynamic content using [`XML-processing-instructions`](https://en.wikipedia.org/wiki/Processing_Instruction) and passing an object of data to the constructor (e.g. `getNode({divClass: 'highlighted', src: './portfolio.png' })`).
These instructions are applied to their preceding sibling tag or parent if no preceding tag available. For example for the data
```javascript
// => add css class to div
// => add `src` attribute to img
```
Let's see example in action:
template.html:
```html
```
### Content
- `` - Append a textNode with the html-safe content of the variable `text`.
- `` - Append a parsed node with the content of the variable `html`;
The input may be either a text or a pre-compiled node / HTML Element.
### Conditionals
- `xxx` - Add its content only if the variable `condition` is truthy.
- `xxx` - Add its content only if the variable `condition` is falsy.
### Loops
- `` - Iterate over an array allowing access to its elements.
- `
` - Iterate over an array allowing access to its elements and provide their index-number (starting from zero)
- `
` - Iterate over a key-value object.
### Attributes
- `` - Set the attribute `key` with the value of `varName`.
- `` - Set as many attributes as provided.
- `` - Set a collection of attributes described in the variable `map`, which should be key-value object (e.g. `{ val1: 'bar', val2: 'foo' }`)
- `` - Set attribute `key` only if the variable `condition` is truthy.
- `` - Set attribute `key` only if the variable `condition` is falsy.
- `` - Set a collection of attributes only if the variable `condition` is truthy.
- `` - Set a collection of attributes only if the variable `condition` is falsy.
### CSS Classes
- `` - Add the css-class or array-of-classes provided in `value` (i.e. `value: 'highlighted'` or `value: ['primary','pressed']`)
- `` - Add the css-class or array-of-classes provided in `value` if the variable `condition` is truthy.
## Sub-Templates
- `` - Use another template. For example:
liTemplate:
```html
```
ulTemplate:
```html
```
Javascript:
```javascript
import { Node as LiTemplate } from './liTemplate';
import { Node as UlTemplate } from './ulTemplate';
console.log(new UlTemplate({ items: ['a', 'b', 'c'], LiTemplate }).toString());
```
Output:
```html
a
b
c
```
- `` - embeds a file as part of the template. The file can be free-text or xml-based (HTML, XML, SVG) that will then be parsed automatically. Note that unlike other process-instruction, this PI is being handled at compile-time. For example:
```html
```
Output:
```xml
```
## Easy-access to Content
### Using id (``)
Any HTML elements with an `id` attribute can easily be access at `node.set[id]`, for example:
template.html:
```html