Skip to content

Commit 2201df2

Browse files
thewebartisan7thewebartisan7
committed
More readme
1 parent c78d53b commit 2201df2

File tree

1 file changed

+160
-2
lines changed

1 file changed

+160
-2
lines changed

‎readme.md

+160-2
Original file line numberDiff line numberDiff line change
@@ -92,9 +92,167 @@ Result:
9292
| **matcher** | `[]` | Array of object used to match the tags. Useful if you are migrating from extend and modules. |
9393
| **strict** | `true` | Boolean value for enable or disable throw an exception. |
9494

95-
## Feature
95+
## Features
9696

97-
TODO...
97+
### Tag names and x-tags
98+
99+
You can use the components in multiple ways, or also a combination of them.
100+
Like with `posthtml-extend` and `posthtml-modules` you can define a tag name or multiples tag name in combination with an attribute name or multiple attributes name for set the path to the components.
101+
102+
For example for the same button component `src/button.html` in the basic example we can define the tag name and attribute name and then use it in this way:
103+
104+
``` html
105+
<!-- src/index.html -->
106+
<html>
107+
<body>
108+
<component src="button.html">Submit</component>
109+
</body>
110+
</html>
111+
```
112+
113+
Init PostHTML:
114+
115+
```js
116+
// index.js
117+
const { readFileSync, writeFileSync } = require('fs')
118+
119+
const posthtml = require('posthtml')
120+
const components = require('posthtml-components')
121+
122+
posthtml(components({ root: './src', tagName: 'component', attribute: 'src' }))
123+
.process(readFileSync('src/index.html', 'utf8'))
124+
.then((result) => writeFileSync('dist/index.html', result.html, 'utf8'))
125+
```
126+
127+
We can also set multiple tag names by passing an array of component name and an array of attribute name, this is useful if you need to migrate from `posthtml-extend` and `posthtml-modules` where you are using different tag name.
128+
129+
Init PostHTML with multiple tag names and attributes:
130+
131+
``` html
132+
<!-- src/index.html -->
133+
<html>
134+
<body>
135+
<extends src="button.html">Submit</extends>
136+
<module href="button.html">Submit</module>
137+
</body>
138+
</html>
139+
```
140+
141+
```js
142+
// index.js
143+
144+
const options = {
145+
root: './src',
146+
tagNames: ['extends', 'module'],
147+
attribute: ['src', 'href']
148+
};
149+
150+
require('posthtml')(require('posthtml-components')(options))
151+
.process(/* ... */)
152+
.then(/* ... */)
153+
```
154+
155+
If you need more control over how to match the tags, you can pass directly an array of matcher or single object via `options.matcher` like shown in below example:
156+
157+
```js
158+
// index.js
159+
160+
const options = {
161+
root: './src',
162+
matcher: [{tag: 'a-tag'}, {tag: 'another-one'}, {tag: new RegExp(`^app-`, 'i')}]
163+
};
164+
165+
require('posthtml')(require('posthtml-components')(options))
166+
.process(/* ... */)
167+
.then(/* ... */)
168+
```
169+
170+
With `posthtml-components` you don't need to specify the path name when you are using `x-tag-name` syntax. See below example.
171+
172+
Setup PostHTML:
173+
174+
```js
175+
// index.js
176+
177+
const options = {
178+
root: './src',
179+
tagPrefix: 'x-'
180+
};
181+
182+
require('posthtml')(require('posthtml-components')(options))
183+
.process(/* ... */)
184+
.then(/* ... */)
185+
```
186+
187+
Use:
188+
189+
``` html
190+
<!-- src/index.html -->
191+
<html>
192+
<body>
193+
<x-button>Submit</x-button>
194+
</body>
195+
</html>
196+
```
197+
198+
If your components are in a subfolder then you can use `dot` to access it, example:
199+
200+
``` html
201+
<!-- Supposing your button component is located in ./src/components/forms/button.html -->
202+
<x-forms.button>Submit</x-forms.button>
203+
```
204+
205+
If your components are in a sub-folder with multiple files, then for avoid to type the main file you can use `index.html` without specify it.
206+
Please see below example to understand better.
207+
208+
``` html
209+
<!-- Supposing your modal component is located in ./src/components/modals/index.html -->
210+
<x-modal.index>Submit</x-modal.index>
211+
212+
<!-- You can omit "index" part since the file is named "index.html" -->
213+
<x-modal>Submit</x-modal>
214+
```
215+
216+
### Multiple roots
217+
218+
You have full control where to place your components. Once you set the main root path of your components, you can then set multiple roots.
219+
For example let's suppose your main root is `./src` and then you have several folders where you have your components, for example `./src/components` and `./src/layouts`.
220+
You can setup the plugin like below:
221+
222+
```js
223+
// index.js
224+
225+
const options = {
226+
root: './src',
227+
roots: ['components', 'layouts']
228+
};
229+
230+
require('posthtml')(require('posthtml-components')(options))
231+
.process(/* ... */)
232+
.then(/* ... */)
233+
```
234+
235+
### Namespaces
236+
237+
With namespaces you can define a top level root path to your components like shown in below example:
238+
239+
``` html
240+
<!-- src/index.html -->
241+
<html>
242+
<body>
243+
<x-theme-dark::button>Submit</theme-dark::button>
244+
<x-theme-light::button>Submit</theme-light::button>
245+
</body>
246+
</html>
247+
```
248+
249+
### Slots
250+
251+
### Props
252+
253+
### Matcher
254+
255+
## Migration from posthtml-extend and posthtml-modules
98256

99257
## Contributing
100258

0 commit comments

Comments
 (0)