2 | 
3 |
6 |
7 |
8 |
9 |
10 |
11 |
12 |
15 |
16 |
17 |
18 |
Tiny utility (365B) to create DOM elements with manner.
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 fixes 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 (365 bytes gzipped) 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 | 62 | ``` 63 | 64 | 65 | ## Usage 66 | 67 | ```js 68 | import f from 'facon'; 69 | 70 | // Create a DOM element 71 | let node = f`Hello World`; 72 | document.body.appendChild(node); 73 | 74 | // Create nested elements, and extract references 75 | let node = f` 76 |
77 |
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`Hello World`;
88 | let parent = f`Façon
78 |Create nested DOM elements with manner
79 |${child}
`;
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 = f`Hello World`;
105 | let node = f`${myNode}
`;
106 |
107 | // or this way
108 | let myNode = document.createElement('div');
109 | let node = f`${myNode}
`;
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 |
121 |
Hello world!
122 |-
123 |
- One 124 |
- Two 125 |
- Three 126 |
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`
138 | Default: `ref` 139 | 140 | Attribute name used for collecting references. 141 | 142 | #### options.keepAttribute 143 | Type: `Boolean`
144 | Default: `false` 145 | 146 | Keep `ref` attributes on elements after collecting the references. Defaults to `false`. 147 | 148 | #### options.to 149 | Type: `Object`
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 through `this`. E.g: 155 | ```js 156 | class MyElement extends Component { 157 | 158 | view() { 159 | const view = f` 160 |`), '');
38 | });
39 |
40 | test('facon: collect', async t => {
41 | t.plan(2);
42 | let el = f`hello`;
43 | let obj = el.collect();
44 | t.is('test' in obj, true);
45 | t.is(s(el), 'hello');
46 | });
47 |
48 | test('facon: collect - array', async t => {
49 | t.plan(5);
50 | let el = f`${i} `), true);
57 | });
58 |
59 | test('facon: collect - keep attribute', async t => {
60 | t.plan(7);
61 | let el = f`hello`;
62 | let obj = el.collect({keepAttribute:true});
63 | t.is('test' in obj, true);
64 | t.is(s(el), `hello`);
65 |
66 | el = f`${i} `), true);
73 | });
74 |
75 | test('facon: collect - custom attribute', async t => {
76 | t.plan(14);
77 | let el = f`hello`;
78 | let obj = el.collect({attr:'lol'});
79 | t.is('test' in obj, true);
80 | t.is(s(el), `hello`);
81 |
82 | el = f`hello`
83 | obj = el.collect({attr:'lol', keepAttribute:true});
84 | t.is('test' in obj, true);
85 | t.is(s(el), `hello`);
86 |
87 | el = f`${i} `), true);
94 |
95 | el = f`${i} `), true);
102 | });
103 |
104 | test('facon: collect - to', async t => {
105 | t.plan(8);
106 | let el = f`hello`;
107 | let to = {};
108 | el.collect({to});
109 | t.is('test' in to, true);
110 | t.is(s(el), `hello`);
111 |
112 | el = f`${i} `), true);
120 | });
121 |
122 | test('facon: append element', async t => {
123 | let node = window.document.createElement('div');
124 | let el = f`
138 | Default: `ref` 139 | 140 | Attribute name used for collecting references. 141 | 142 | #### options.keepAttribute 143 | Type: `Boolean`
144 | Default: `false` 145 | 146 | Keep `ref` attributes on elements after collecting the references. Defaults to `false`. 147 | 148 | #### options.to 149 | Type: `Object`
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 through `this`. E.g: 155 | ```js 156 | class MyElement extends Component { 157 | 158 | view() { 159 | const view = f` 160 |
161 |
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)
180 |
--------------------------------------------------------------------------------
/test/index.js:
--------------------------------------------------------------------------------
1 | import f from '../src';
2 | import test from 'tape';
3 | import { JSDOM } from 'jsdom';
4 |
5 | const { window } = new JSDOM(`...`);
6 | global.document = window.document;
7 | global.HTMLElement = window.HTMLElement;
8 |
9 | let parent = document.createElement('div');
10 |
11 | const s = el => {
12 | parent.innerHTML = '';
13 | parent.appendChild(el);
14 | return parent.innerHTML;
15 | }
16 |
17 | test('facon: standard', async t => {
18 | t.plan(1);
19 | t.is(typeof f, 'function', 'constructor is a typeof function');
20 | });
21 |
22 | test('facon: awkward boundary conditions', async t => {
23 | t.plan(5);
24 | let subst = 100;
25 | t.is(s(f``), '', 'empty string');
26 | t.is(s(f`${subst}`), '100', 'just arg');
27 | t.is(s(f`${subst}left`), '100left', 'arg on far left');
28 | t.is(s(f`right${subst}`), 'right100', 'arg on far right');
29 | t.is(s(f`${subst}mid${subst}`), '100mid100', 'args on either end')
30 | });
31 |
32 | test('facon: build element', async t => {
33 | t.plan(4);
34 | t.is(s(f`hello`), 'hello');
35 | t.is(s(f`hello`), 'hello');
36 | t.is(s(f`hello`), 'hello');
37 | t.is(s(f`Façon
162 |Create nested DOM elements with manner
163 |Hello
How Are you?
Hello
How Are you?
- 0
- 1
- 2
- 0
- 1
- 2
- 0
- 1
- 2
- 0
- 1
- 2
- 0
- 1
- 2
- 0
- 1
- 2
- 0
- 1
- 2
- 0
- 1
- 2
- 0
- 1
- 2
- 0
- 1
- 2
${node}
`;
125 | t.is(s(el), ``);
126 | t.end();
127 | });
128 |
129 | test('facon: append string', async t => {
130 | let str = 'Hello';
131 | let el = f`
${str}
`;
132 | t.is(s(el), `Hello
`);
133 | t.end();
134 | });
135 |
136 | test('facon: append number', async t => {
137 | let number = 0;
138 | let el = f`${number}
`;
139 | t.is(s(el), `0
`);
140 | t.end();
141 | });
142 |
143 | test('facon: append multiple', async t => {
144 | let number = 0;
145 | let string = 'Hello';
146 | let el = f`${number} - ${string}
`;
147 | t.is(s(el), `0 - Hello
`);
148 | t.end();
149 | });
150 |
151 | test('facon: example', async t => {
152 | let count = 0;
153 | const counter = f`
154 |
155 | Count: ${count}
156 |
160 |
161 | `;
162 | const {value, increment, decrement} = counter.collect();
163 | t.is(counter.nodeType, 11);
164 | t.is(value.nodeType, 1);
165 | t.is(increment.nodeType, 1);
166 | t.is(decrement.nodeType, 1);
167 | t.end();
168 | });
169 |
170 |
171 |
172 |
173 |
--------------------------------------------------------------------------------