From 2201df27fc81b01275f7cb2c6fa87d39c196cb78 Mon Sep 17 00:00:00 2001 From: Damir Date: Sat, 15 Oct 2022 05:43:46 +0200 Subject: [PATCH] More readme --- readme.md | 162 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 160 insertions(+), 2 deletions(-) diff --git a/readme.md b/readme.md index 540d88d..2b686a0 100644 --- a/readme.md +++ b/readme.md @@ -92,9 +92,167 @@ Result: | **matcher** | `[]` | Array of object used to match the tags. Useful if you are migrating from extend and modules. | | **strict** | `true` | Boolean value for enable or disable throw an exception. | -## Feature +## Features -TODO... +### Tag names and x-tags + +You can use the components in multiple ways, or also a combination of them. +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. + +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: + +``` html + + + + Submit + + +``` + +Init PostHTML: + +```js +// index.js +const { readFileSync, writeFileSync } = require('fs') + +const posthtml = require('posthtml') +const components = require('posthtml-components') + +posthtml(components({ root: './src', tagName: 'component', attribute: 'src' })) + .process(readFileSync('src/index.html', 'utf8')) + .then((result) => writeFileSync('dist/index.html', result.html, 'utf8')) +``` + +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. + +Init PostHTML with multiple tag names and attributes: + +``` html + + + + Submit + Submit + + +``` + +```js +// index.js + +const options = { + root: './src', + tagNames: ['extends', 'module'], + attribute: ['src', 'href'] +}; + +require('posthtml')(require('posthtml-components')(options)) + .process(/* ... */) + .then(/* ... */) +``` + +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: + +```js +// index.js + +const options = { + root: './src', + matcher: [{tag: 'a-tag'}, {tag: 'another-one'}, {tag: new RegExp(`^app-`, 'i')}] +}; + +require('posthtml')(require('posthtml-components')(options)) + .process(/* ... */) + .then(/* ... */) +``` + +With `posthtml-components` you don't need to specify the path name when you are using `x-tag-name` syntax. See below example. + +Setup PostHTML: + +```js +// index.js + +const options = { + root: './src', + tagPrefix: 'x-' +}; + +require('posthtml')(require('posthtml-components')(options)) + .process(/* ... */) + .then(/* ... */) +``` + +Use: + +``` html + + + + Submit + + +``` + +If your components are in a subfolder then you can use `dot` to access it, example: + +``` html + +Submit +``` + +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. +Please see below example to understand better. + +``` html + +Submit + + +Submit +``` + +### Multiple roots + +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. +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`. +You can setup the plugin like below: + +```js +// index.js + +const options = { + root: './src', + roots: ['components', 'layouts'] +}; + +require('posthtml')(require('posthtml-components')(options)) + .process(/* ... */) + .then(/* ... */) +``` + +### Namespaces + +With namespaces you can define a top level root path to your components like shown in below example: + +``` html + + + + Submit + Submit + + +``` + +### Slots + +### Props + +### Matcher + +## Migration from posthtml-extend and posthtml-modules ## Contributing