1 | <p align="center">
|
2 | <img src="facon.png" alt="facon" width="300" />
|
3 | </p>
|
4 |
|
5 | <p align="center">
|
6 | <a href="https://npmjs.org/package/facon">
|
7 | <img src="https://badgen.now.sh/npm/v/facon" alt="version" />
|
8 | </a>
|
9 | <a href="https://codecov.io/gh/terkelg/facon">
|
10 | <img src="https://badgen.now.sh/codecov/c/github/terkelg/facon" alt="codecov" />
|
11 | </a>
|
12 |
|
13 | <img src="https://badgen.now.sh/npm/dm/facon" alt="downloads" />
|
14 | </a>-->
|
15 | <a href="https://packagephobia.now.sh/result?p=facon">
|
16 | <img src="https://packagephobia.now.sh/badge?p=facon" alt="install size" />
|
17 | </a>
|
18 | </p>
|
19 |
|
20 | <p align="center"><b>Tiny utility (295B) to create DOM elements with manner.</b></p>
|
21 |
|
22 | Manually creating DOM nested elements can be very troublesome and verbose.
|
23 | Facon is a tiny utility that makes it easy to create nested DOM elements using template literals and extract references.
|
24 |
|
25 |
|
26 | There's no magic nor restrictive template logic. All you get are dom references so that you can do whatever you like and take full advantage of the powerful native DOM API.
|
27 |
|
28 |
|
29 | > **TLDR**: Facon fix the tiring process of creating and assembling nested DOM elements or `.innerHTML` where you later have to query for references manually.
|
30 |
|
31 | **~~lack of~~ Features**
|
32 | - Tiny (295B)
|
33 | - Vanilla JS
|
34 | - Zero Dependencies
|
35 | - Fast
|
36 |
|
37 |
|
38 | ## Install
|
39 |
|
40 | ```
|
41 | $ npm install facon
|
42 | ```
|
43 |
|
44 | This module exposes three module definitions:
|
45 |
|
46 | * **ES Module**: `dist/facon.mjs`
|
47 | * **CommonJS**: `dist/facon.js`
|
48 | * **UMD**: `dist/facon.min.js`
|
49 |
|
50 | Include facon:
|
51 | ```js
|
52 | // ES6
|
53 | import f from 'facon'
|
54 |
|
55 | // CJS
|
56 | const f = require('facon');
|
57 | ```
|
58 |
|
59 | The script can also be directly included from [unpkg.com](https://unpkg.com):
|
60 | ```html
|
61 | <script src="https://unpkg.com/facon"></script>
|
62 | ```
|
63 |
|
64 |
|
65 | ## Usage
|
66 |
|
67 | ```js
|
68 | import f from 'facon';
|
69 |
|
70 | // Create a <b> DOM element
|
71 | let node = f`<b>Hello World</b>`;
|
72 | document.body.appendChild(node);
|
73 |
|
74 | // Create nested elements, and extract references
|
75 | let node = f`
|
76 | <div>
|
77 | <h1 ref="title">Façon</h1>
|
78 | <p ref="body">Create nested DOM elements with manner<p>
|
79 | </div>
|
80 | `;
|
81 | document.body.appendChild(node);
|
82 |
|
83 | let {title, body} = node.collect();
|
84 | title.textContent = 'Hello World';
|
85 |
|
86 | // DOM node appends
|
87 | let child = f`<b>Hello World</b>;
|
88 | let parent = f`<div>${child}</div>;
|
89 | ```
|
90 |
|
91 |
|
92 | ## API
|
93 |
|
94 | ### facon(string)
|
95 | Returns: `Element`
|
96 |
|
97 | Construct and returns a DOM `element`.
|
98 |
|
99 | The returned `element` has a special `collect` method that is used to collect references to all elements with a `ref` attribute. Multiple elements containing identical `ref` attribute values result in an array of DOM references.
|
100 |
|
101 | DOM Elements can be composed together/appended like this:
|
102 |
|
103 | ```js
|
104 | let myNode = document.createElement('div');
|
105 | let node = f`<div>${myNode}</div>`;
|
106 |
|
107 | // or this way
|
108 | let myNode = document.createElement('div');
|
109 | let node = f`<div>${myNode}</div>;
|
110 | ```
|
111 |
|
112 |
|
113 | ### node.collect(options)
|
114 | Returns: `Object`
|
115 |
|
116 | Method for extracting DOM references. E.g:
|
117 |
|
118 | ```js
|
119 | const node = f`
|
120 | <div>
|
121 | <h1 ref="title">Hello world!</h1>
|
122 | <ul ref="list">
|
123 | <li ref="items">One</li>
|
124 | <li ref="items">Two</li>
|
125 | <li ref="items">Three</li>
|
126 | </ul>
|
127 | <div>
|
128 | `;
|
129 | let {title, list, items} = node.collect();
|
130 | // ~> title is a dom reference to the inner h1 element.
|
131 | // ~> list is a dom reference to the inner ul element.
|
132 | // ~> items is an array of dom references to each li element.
|
133 | // ~> node is by default the outer most element.
|
134 | ```
|
135 |
|
136 | #### options.ref
|
137 | Type: `String`<br>
|
138 | Default: `ref`
|
139 |
|
140 | Attribute name used for collecting references.
|
141 |
|
142 | #### options.keepAttribute
|
143 | Type: `Boolean`<br>
|
144 | Default: `false`
|
145 |
|
146 | Keep `ref` attributes on elements after collecting the references. Defaults to `false`.
|
147 |
|
148 | #### options.to
|
149 | Type: `Object`<br>
|
150 | Default: `{}`
|
151 |
|
152 | Optional object reference to assign to.
|
153 |
|
154 | This can be handy if you have a component and want to be able to access references trough `this`. E.g:
|
155 | ```js
|
156 | class MyElement extends Component {
|
157 |
|
158 | view() {
|
159 | const view = f`
|
160 | <div>
|
161 | <h1 ref="title">Façon</h1>
|
162 | <p ref="body>Create nested DOM elements with manner<p>
|
163 | </div>
|
164 | `;
|
165 | view.collect({to:this});
|
166 | }
|
167 |
|
168 | // later ...
|
169 |
|
170 | update() {
|
171 | this.title = 'Hello World';
|
172 | this.body = 'test';
|
173 | }
|
174 | }
|
175 | ```
|
176 |
|
177 | ## License
|
178 |
|
179 | MIT © [Terkel Gjervig](https://terkel.com)
|