\n\n# Features\n\n- Write HTML with JavaScript using real HTML tag names.\n- Unique way of building WebComponents\n\n## Why?\n\n- String literals tend to get messy and unreadable\n- Maybe you don't want or need JSX\n- HyperScript is ok, but you would like to avoid manually writing HTML tag names\n- Make writing HTML in JavaScript feel almost like writing it in .html file\n- Make writing HTML in JavaScript dead simple and intuitive but keeping all the JavaScript's power\n\n## Install\n\n### github\n\n- Latest version:\n `npm install git+https://github.com/vsmid/htmlhammer.git --save`\n\n- Specific version:\n `npm install git+https://github.com/vsmid/htmlhammer.git\\#1.0.0 --save`\n\n### npmjs\n\n`npm i htmlhammer`\n\n### unpkg\n\n```html\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n```\n\nFor specific versions use url format: unpkg.com/:package@:version/:file. See [UNPKG](https://unpkg.com/) for more info.\n\n## Importing and using htmlhammer\n\n```javascript\n// In html\n;\nconst { div } = htmlhammer;\n\n// In modules\nconst { div, a, h1 } = require('htmlhammer').default;\nimport { div, a, h1 } from 'htmlhammer';\n```\n\n## Using htmlhammer\n\n## Supported HTML tags/elements\n\nSee the list on [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element). Tags/elements marked as\nobsolete/deprecated are not supported.\n\n## Signature\n\n```javascript\n// Function name htmltagname is one of supported HTML tag/elements, e.g. div, a, h1, table etc.\n// Since version 2.3.0 attributesAndProperties parameter is optional\nhtmltagname((attributesAndProperties = {}), ...children);\n```\n\nParameters:\n\n- attributesAndProperties - JSON object where key is the name of the element's attribute/property (e.g. id, name, style, onclick, or custom attribute/property etc. ) and value is the new attribute/property value.\n Difference between defining an attribute and property is that property value must always be one of function, instance of class, array or json object. This rule does not apply to [reserved element attributes/properties](#reserved-element-attributesproperties) and `style`.\n- children - element or elements to be appended to parent element. Can be string, number, another HTMLElement created regularly or by **htmlhammer**, function returning one of the previously stated types etc.\n\nReturns:\n\n- An array of HTMLElement or a single HTMLElement.\n\n### Code sample\n\n```javascript\nlet items = [{ value: 1 }, { value: 2 }];\n\ndocument.body.append(\n div(\n { style: { color: 'red' } },\n h1('I am the title'),\n a({ href: '#' }, 'Click me!'),\n table(tr({ $for: items }, item => td(item.value)))\n )\n);\n```\n\n### String as HTML\n\nIf you have HTML in string format and you would like for it to be added to element as HTML you should wrap it\nin `HtmlString` class. This is useful when you want to inject an already generated HTML in string format to an element (\ne.g. HTML content received from REST service).\n\n```javascript\nimport { div, HtmlString } from './esm/index.js';\n\nconst html = '
Hello World!
';\n\ndocument.body.append(\n div(new HtmlString(html)) // Without HTMLString wrapper, html content would be treated as text content hence text node would be created\n);\n```\n\nVersion 2.1.0 introduced a new attribute handler `$apply` which allows you to create inline element in any way you like.\n\n```javascript\nconst RawHtml = data => el => (el.innerHTML = data);\n\ndocument.body.append(\n div(span({ $apply: RawHtml('
Hello World!
') }))\n);\n```\n\nFor more complex and complete examples see [demo](https://github.com/vsmid/htmlhammer/tree/master/demo).\n\n### Reserved element attributes/properties\n\n#### `$for` - creating multiple elements of the same type\n\n```javascript\n// Creates three elements of type div,
1
,
2
,
3
\n// index parameter is optional\n// item = 1, index = 0\n// item = 2, index = 1\n// item = 3, index = 2\ndiv({ $for: [1, 2, 3] }, (item, index) => item);\n```\n\n#### `$if` - conditionally create element\n\n```javascript\ndiv({ $if: true }, 'I am created');\ndiv({ $if: () => true }, 'I am created');\n\n// Create only items with value > 2\ndiv({ $for: [1, 2, 3], $if: item => item > 2 }, item => item);\n```\n\n#### `$ref` - reference created element\n\nA key under which element will be stored must be an object!\n\n```javascript\nconst { div, ref, setRef } = htmlhammer;\n\n// Reference by object\nlet obj = {};\n\n// Prior to 2.2.0\nlet element = div({ $ref: setRef(obj) }, 'Hello World!');\n\n// Version 2.2.0 allows ref to be set just by passing an object reference\nlet element = div({ $ref: obj }, 'Hello World!');\n\nconsole.log(ref(obj) === element);\n\n// Manually assigning id if the same object is used for multiple references\nlet person = new Person('Lena', 0);\n\ndiv({ $ref: setRef(person, 'name') }, person.name);\ndiv({ $ref: setRef(person, 'age') }, person.age);\n\nconsole.log(ref(person, 'name'));\nconsole.log(ref(person, 'age'));\n\n// If used in combination with $for do not set object reference manually because it will automatically be set to the list item value\nelement = div(\n { $for: [{ v: 1 }, { v: 2 }, { v: 3 }], $ref: setRef },\n 'Hello World!'\n);\n```\n\n#### `$apply` - apply anything to an element\n\nUse this attribute to apply anything to an element. This gives you the full power of JavaScript Element API mixed\nwithin `htmlhammer's` inline element creation. This can also be ideal for sharing style, logic, event handlers etc.\nacross multiple components/elements. $apply can be given as a function which receives element or an array of such\nfunctions.\n\n```javascript\nconst RedText = el => (el.style.color = 'red');\n\n// Function which can replace new HtmlString(\"
Hello
\")\nconst HTMLContent = data => el => (el.innerHTML = data);\n\n// Valid usages\ndiv({ $apply: RedText });\ndiv({ $apply: [RedText, HTMLContent('
Hello
')] });\n```\n\n### Setting on-event actions\n\nEvent names are case-sensitive. For each event use corresponding element's event name.\n\n```javascript\n// Defines element's onclick event function\na({ onclick: e => alert('Clicked!') }, 'Click me');\n// Defines plain function on element, will not trigger on click\na({ onClick: e => alert('Clicked!') }, 'Click me');\n```\n\n### Setting CSS\n\nCSS is given in the form of JSON object when using element's style attribute or HTMLStyleElement when using HTML tag\nstyle.\n\n```javascript\n// Global, using HTMLStyleElement\ndocument.head.append(\n style(`\n body {\n font-size: 12px;\n }`)\n);\n\n// Inline, using style attribute\ndiv(\n { style: { color: 'red', fontSize: '12px' } },\n 'Hello World!'\n);\n```\n\nWhen setting style attribute values, use corresponding JavaScript CSS property names.\nSee [MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Properties_Reference).\n\n### Custom child appender\n\nVersion 2.0.0 introduced option to provide a custom way of how child element is appended to parent element. Use case for\nthis can be seen in `HtmlString` appender where raw html in the form of string needs to inserted to DOM element. For\nthis to happen, element's `insertAdjacentHTML` method is used instead of default `append` method. See how HtmlString\nappender is implemented in [appenders.js](https://github.com/vsmid/htmlhammer/blob/master/esm/appenders.js).\n\n### DocumentFragment\n\n`htmlhammer` provides support for creating `DocumentFragment` object by simply using `fragment` function just like any other html tag function already provided. Even though it is not a true html tag it is here as a convenience function.\n\n[See how it relates to fragment used by JSX](#relation-of-jsx--fragment-to-htmlhammers-fragment-function)\n\n```js\nimport { fragment, div } from './esm/index.js';\n\nfragment(div('1'), div('2'));\n```\n\n## Custom elements\n\n### Method signature\n\n`customElement(tagName, provider, type)`\n\n- `tagName` - custom element tag name\n- `provider` - plain JS object with lifecycle functions and properties. See under [Lifecycle and reserved properties](#lifecycle-and-reserved-properties).\n- `type` - optional, function reference to one of htmlhammer's functions (e.q. div, a, table etc.). Use when you want to\n extend existing html element, e.q. HTMLDivElement.\n\n### Lifecycle and reserved properties\n\n- postConstruct\n- connectedCallback\n- disconnectedCallback\n- attributeChangedCallback\n- adoptedCallback\n- observedAttributes\n\nDifferences to the specification:\n\n- `postConstruct` - think of it as a constructor.\n- `observedAttributes` - an array of strings (names of the observed attributes)\n\n### Define custom element\n\n- Using only htmlhammer\n\n```javascript\nconst { customElement } = htmlhammer; // or use ES6 import\n\n// Definition\nconst yetiCustom = customElement('yeti-custom', {\n connectedCallback() {\n console.log('Generic custom element created!');\n }\n});\n\n// Usage\ndocument.body.append(yetiCustom());\n```\n\n- Using htmlhammer and html\n\n```html\n\n\n\n\n```\n\n### Extending existing native element\n\nExamples below show how to extend existing [HTMLDivElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDivElement)\n\n- Using only htmlhammer\n\n```javascript\nconst { div, customElement } = htmlhammer; // or use ES6 import\n\n// Definition\nconst yetiDiv = customElement(\n 'yeti-div',\n {\n connectedCallback() {\n console.log('Generic custom element created!');\n }\n },\n div\n);\n\n// Usage\ndocument.body.append(div({ is: 'yeti-div' }));\n```\n\n- Using htmlhammer and html\n\n```html\n\n\n\n\n```\n\n### Setting shadow dom\n\n- Inside custom element\n\n```javascript\nconst { customElement } = htmlhammer; // or use ES6 import\n\nconst yetiCustom = customElement('yeti-custom', {\n connectedCallback() {\n this.attachShadow({ mode: 'open' });\n }\n});\n```\n\n- As htmlhammer attribute\n\n```javascript\nyetiCustom(\n { shadowRoot: { mode: 'open' } },\n 'Hello from Generic CustomElement'\n);\n```\n\n### Setting styles\n\n- Inside custom element\n\n```javascript\nconst { style, customElement } = htmlhammer; // or use ES6 import\n\nconst yetiCustom = customElement('yeti-custom', {\n connectedCallback() {\n this.attachShadow({ mode: 'open' });\n this.shadowRoot.append(style(`:host { font-weight: bold;}`));\n }\n});\n```\n\n- As htmlhammer attribute\n\n```javascript\nyetiCustom(\n {\n shadowRoot: {\n mode: 'open',\n stylesheets: [style(`:host {color: red;}`)]\n }\n },\n 'Hello from Generic CustomElement'\n);\n```\n\n### Provider's properties and structured cloning\n\nProperties of `provider` object(see under [Method signature](#method-signature)) will be created on each new custom element instance using `structuredClone` method to ensure that there is no object reference sharing between custom element instances of the same type.\n\nStructured cloning is skipped for functions.\n\n### Passing properties\n\nYou can pass objects, arrays, functions, class instances and existing dom element references from parent to child element as properties. Numbers, strings dates etc. are treated as attributes. Note that by 'passing' htmlhammer actually creates properties on the object.\n\n```javascript\n// Custom element\nlet element = customElement('my-element', {\n connectedCallback() {\n console.log(\n this.o,\n this.a,\n this.fn(),\n this.p,\n this.el(),\n this.getAttribute('v'),\n this.getAttribute('s')\n );\n }\n});\n\nclass Person {}\n\ndocument.body.append(\n element({\n o: { id: 1 }, // object\n a: [1], // array\n fn: () => 1, // function\n p: new Person(), // instance of class\n el: () => document.getElementById('id'), // dom element reference (pass it as a function)\n v: 1, // number\n s: 'string' // string\n })\n);\n```\n\n### Conventions\n\nConventions apply only to the provider(see under [Method signature](#method-signature)).\n\n- Function starting with capital letter - binds function to context (custom element instance)\n- Property starting with capital letter - receives get/set methods\n- Property not starting with capital letter - receives only get method\n- Property is named the same as observed attribute - property will reflect attribute\n\n### Counter web component example\n\nThese examples demonstrate how you can use this library to build web component with simple state management and a few action buttons. It also shows you a cool way of how you can set and assign any node you would like to reference at any time during component's life. This feature is basically a consequence of building html with javascript which htmlhammer is all about.\n\n#### Basic implementation\n\nThis example shows how you can create counter web component using dedicated action buttons to change counter's state.\n\n```javascript\nconst Counter = customElement('my-counter', {\n Count: 0,\n connectedCallback() {\n this.append(\n button({ id: 'dec', onclick: this.Dec }, '-'),\n (this.CounterDisplay = span(this.Count)), // Cool way to set and assign html element\n button({ id: 'inc', onclick: this.Inc }, '+')\n );\n },\n observedAttributes: ['count'],\n attributeChangedCallback(n, ov, nv) {\n // Each time Count changes a new console log is written\n console.log(`Counter change: ${ov} -> ${nv}`);\n },\n Inc() {\n this.Update(++this.Count);\n },\n Dec() {\n this.Update(--this.Count);\n },\n Update(count) {\n this.CounterDisplay.textContent = count; // Assigned html element referenced\n }\n});\n```\n\n#### Advanced implementation\n\nThis example shows how you can create the same counter web component using\n`attributeChangedCallback` function to change counter's state.\n\n```javascript\nconst Counter = customElement('my-counter-advanced', {\n Count: 0,\n observedAttributes: ['count'],\n attributeChangedCallback(attrName, ov, nv) {\n if (attrName === 'count') {\n this.CounterDisplay.textContent = this.Count;\n }\n },\n connectedCallback() {\n this.attachShadow({ mode: 'open' });\n this.shadowRoot.append(\n button({ id: 'dec', onclick: () => --this.Count }, '-'),\n (this.CounterDisplay = span(this.Count)),\n button({ id: 'inc', onclick: () => ++this.Count }, '+')\n );\n }\n});\n```\n\nSee both counter web component examples in action by checking [live demo](https://vsmid.github.io/htmlhammer/).\n\n### Live demo\n\nDemo is basically `index.html` file found in the root of the project served as a github page.\n\n[live demo](https://vsmid.github.io/htmlhammer/)\n\n## JSX\n\nAs of version 4.0.0 `htmlhammer` provides experimental `JSX` support.\n\n### hhjsx function\n\n`htmlhammer` provides `hhjsx` function which will be used by the compiler to replace `JSX` elements.\n\n```js Example\n// Below JSX snippet will be replaced by the compiler with hhjsx('a', {anchor: 'anchor'})\n\n```\n\n`hhjsx` function can be imported from `index.js`.\n\nDo note that `hhjsx` needs to be available to each `.js(x)` module. Either attach this function to the `window` when the application is started or import it to each `.js(x)` module.\n\n```html\n\n\n \n \n \n HtmlHammer JSX\n \n\n \n \n \n\n```\n\n### Compiling JSX\n\nIn order to use `JSX` with `htmlhammer` you need to use a compiler that is able to transform `JSX` syntax into a function calls. Here, we are using `Babel`.\n\n#### Adding `Babel` support to your project\n\n```bash\nnpm install --save-dev @babel/core @babel/cli @babel/preset-env @babel/preset-react\n```\n\n#### Adding `babel.config.json` file to your project\n\n```json\n{\n \"presets\": [\n [\n \"@babel/preset-react\",\n {\n \"pragma\": \"hhjsx\",\n \"runtime\": \"classic\"\n }\n ],\n [\n \"@babel/preset-env\",\n {\n \"modules\": false\n }\n ]\n ]\n}\n```\n\nExample of babel command which compiles all files in the `src` directory using `react` and `env` presets.\n\n```bash\n# Run compiler from the root of the project\n./node_modules/.bin/babel src --out-dir target\n```\n\n### Relation of `JSX` <> (fragment) to `htmlhammer's` fragment function\n\nCurrently, `htmlhammer` uses \\ instead <>.\n\n```js\n\n \n \n\n\n// is equivalent to\n\nfragment(\n div(),\n div()\n)\n```\n\n### Example\nYou can find an implementation of the working example in the project's [demo/jsx](https://github.com/vsmid/htmlhammer/blob/master/demo/jsx) directory.\n\nSee [live demo](https://vsmid.github.io/htmlhammer/).\n\n## CoffeeScript & htmlhammer\n\nUsing [CoffeeScript](https://coffeescript.org/) and `htmlhammer` for creating HTML templates is a great match. If offers visually very expressive form. HTML-like syntax at a reduced cost.\n\n```coffeescript\nimport { div, h1, h2, hr, span, a, br } from \"https://unpkg.com/htmlhammer?module\"\n\nMovie = ({title, creators, stars, about, imdb}) ->\n [\n h1 title\n hr style:\n height: \"2px\"\n backgroundColor: \"grey\"\n h2 \"Creators\"\n div name for name in creators\n h2 \"Info\"\n span [\n div \"Year: #{about.year}\"\n div \"Stars: #{about.stars}\"\n div \"Genres: #{about.genres.join \", \"}\"\n ]\n h2 \"Stars\"\n div name for name in stars\n br\n a href: imdb, \"IMDb\"\n ]\n```\n\n## Project's NPM scripts\n\n### `test` - run tests\n\n```script\nnpm test\n```\n\n### `coverage` - create and print test coverage report to console\n\n```script\nnpm run coverage\n```\n\n### `coverage:file` - create and print test coverage report to test-coverage-report.txt file\n\n```script\nnpm run coverage:file\n```\n\n### `build` - build project\n\n```script\nnpm run build\n```\n\n### `jsx` - compile jsx\n\n```script\nnpm run jsx\n```\n\n## [Current version test coverage report](https://github.com/vsmid/htmlhammer/blob/master/test-coverage-report.txt)\n\n## Special thanks\n\nBig thanks to [JetBrains](https://www.jetbrains.com/) for granting me a free license :)\n\n\n","readmeFilename":"README.md"}
![\"logo\"](\"https://github.com/vsmid/htmlhammer/blob/master/htmlhammer.png\")
\n![](\"https://badge.fury.io/js/htmlhammer.svg\"){kind=icon}
\n \n ![\"htmlhammer](\"https://img.shields.io/badge/license-ISC-green.svg\"){kind=icon}
\n \n