Skip to content

Commit be5a1c1

Browse files
thewebartisan7thewebartisan7
committed
Updated docs
1 parent 9a89c02 commit be5a1c1

File tree

3 files changed

+177
-125
lines changed

3 files changed

+177
-125
lines changed

‎docs-src/md/introduction.md

+47-47
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ npm i -D posthtml-component
99
## Introduction
1010

1111
This PostHTML plugin provides an HTML-friendly syntax for write components in your templates.
12-
If you are familiar with Blade, you will find similar syntax as this plugin was inspired by it.
12+
If you are familiar with Blade, you will find similar syntax as this plugin is inspired by it.
1313
See below a basic example, as code is worth a thousand words.
1414

1515
> This plugin is still in early stage of development and the current API may change.
@@ -61,13 +61,11 @@ Result:
6161
</html>
6262
```
6363

64-
You may ask yourself many questions about this basic examples, and you will find most if not all answers in this readme. In case is missing something, feel free to ask via discussions.
64+
You may notice that our `src/button.html` component has a `type` and `class` attribute, and when we use the component in `src/index.html` we add type and class attribute.
65+
The result is that `type` is override, and `class` is merged.
6566

66-
But I want to explain a few things now.
67-
68-
First you may notice that our `src/button.html` component has a `type` and `class` attribute, and when we use the component in `src/index.html` we add type and class attribute. The result is that `type` is override, and `class` is merged.
69-
70-
By default `class` and `style` attributes are merged, while all others attribute are override. You can also override class and style attribute by prepending `override:` to the class attribute. Example:
67+
By default `class` and `style` attributes are merged, while all others attribute are override.
68+
You can also override class and style attribute by prepending `override:` to the class attribute. Example:
7169

7270
```html
7371
<x-button override:class="btn-custom">Submit</x-button>
@@ -76,41 +74,43 @@ By default `class` and `style` attributes are merged, while all others attribute
7674
<button type="button" class="btn-custom">Submit</button>
7775
```
7876

79-
All attributes you pass to the component will be added to the first root element of your component, and only if they are not defined as `props` via `<script props>`. More details on this later.
80-
81-
Second you may notice a `<yield>` tag.
82-
83-
This is where your content will be injected.
77+
All attributes you pass to the component will be added to the first node of your component or to the node with an attribute names `attributes`,
78+
and only if they are not defined as `props` via `<script props>`. More details on this in [Attributes](#attributes) section.
8479

85-
In next section you can find all available options and then more examples.
80+
The `<yield>` tag is where your content will be injected.
81+
In next section you can find all available options and then examples for each features.
8682

87-
See also the `docs-src` folder. You can run `npm run build` to compile them.
83+
See also the `docs-src` folder where you can find more examples. You can run `npm run build` to compile them.
8884

8985
## Options
9086

91-
| Option | Default | Description |
92-
|:----------------------:|:----------------------------:|:--------------------------------------------------------------------------------------------------------------------------------|
93-
| **root** | `'./'` | String value as root path for components lookup. |
94-
| **folders** | `['']` | Array of additional multi folders path from `options.root` or any defined namespaces root, fallback or custom. |
95-
| **tagPrefix** | `x-` | String for tag prefix. The plugin will use RegExp with this string. |
96-
| **tag** | `false` | String or boolean value for component tag. Use this with `options.attribute`. Boolean only false. |
97-
| **attribute** | `src` | String value for component attribute for set path. |
98-
| **namespaces** | `[]` | Array of namespace's root path, fallback path and custom path for override. |
99-
| **namespaceSeparator** | `::` | String value for namespace separator to be used with tag name. Example `<x-namespace::button>` |
100-
| **fileExtension** | `html` | String value for file extension of the components used for retrieve x-tag file. |
101-
| **yield** | `yield` | String value for `<yield>` tag name. Where main content of component is injected. |
102-
| **slot** | `slot` | String value for `<slot>` tag name. Used with RegExp by appending `:` (example `<slot:slot-name>`). |
103-
| **fill** | `fill` | String value for `<fill>` tag name. Used with RegExp by appending `:` (example `<fill:slot-name>`). |
104-
| **slotSeparator** | `:` | String value used for separate `<slot>` and `<fill>` tag from their names. |
105-
| **push** | `push` | String value for `<push>` tag name. |
106-
| **stack** | `stack` | String value for `<stack>` tag name. |
107-
| **localsAttr** | `props` | String value used in `<script props>` parsed by the plugin to retrieve locals in the components. |
108-
| **expressions** | `{}` | Object to configure `posthtml-expressions`. You can pre-set locals or customize the delimiters for example. |
109-
| **plugins** | `[]` | PostHTML plugins to apply for every parsed components. |
110-
| **matcher** | `[{tag: options.tagPrefix}]` | Array of object used to match the tags. |
111-
| **attrsParserRules** | `{}` | Additional rules for attributes parser plugin. |
112-
| **strict** | `true` | Boolean value for enable or disable throw an exception. |
113-
| **mergeCustomizer** | `function` | Function callback passed to lodash `mergeWith` for merge `options.expressions.locals` and locals passed via attribute `locals`. |
87+
| Option | Default | Description |
88+
|:------------------------:|:--------------------------------------------:|:------------------------------------------------------------------------------------------------------------------------------|
89+
| **root** | `'./'` | String value as root path for components lookup. |
90+
| **folders** | `['']` | Array of additional multi folders path from `options.root` or any defined namespaces root, fallback or custom. |
91+
| **tagPrefix** | `x-` | String for tag prefix. The plugin will use RegExp with this string. |
92+
| **tag** | `false` | String or boolean value for component tag. Use this with `options.attribute`. Boolean only false. |
93+
| **attribute** | `src` | String value for component attribute for set path. |
94+
| **namespaces** | `[]` | Array of namespace's root path, fallback path and custom path for override. |
95+
| **namespaceSeparator** | `::` | String value for namespace separator to be used with tag name. Example `<x-namespace::button>` |
96+
| **fileExtension** | `html` | String value for file extension of the components used for retrieve x-tag file. |
97+
| **yield** | `yield` | String value for `<yield>` tag name. Where main content of component is injected. |
98+
| **slot** | `slot` | String value for `<slot>` tag name. Used with RegExp by appending `:` (example `<slot:slot-name>`). |
99+
| **fill** | `fill` | String value for `<fill>` tag name. Used with RegExp by appending `:` (example `<fill:slot-name>`). |
100+
| **slotSeparator** | `:` | String value used for separate `<slot>` and `<fill>` tag from their names. |
101+
| **push** | `push` | String value for `<push>` tag name. |
102+
| **stack** | `stack` | String value for `<stack>` tag name. |
103+
| **propsScriptAttribute** | `props` | String value used as attribute in `<script props>` parsed by the plugin to retrieve props of the component. |
104+
| **propsContext** | `props` | String value used as object name inside the script to process process before passed to the component. |
105+
| **propsAttribute** | `props` | String value for props attribute to define props as JSON. |
106+
| **propsSlot** | `props` | String value used to retrieve the props passed to slot via `$slots.slotName.props`. |
107+
| **expressions** | `{}` | Object to configure `posthtml-expressions`. You can pre-set locals or customize the delimiters for example. |
108+
| **plugins** | `[]` | PostHTML plugins to apply for every parsed components. |
109+
| **matcher** | `[{tag: options.tagPrefix}]` | Array of object used to match the tags. |
110+
| **attrsParserRules** | `{}` | Additional rules for attributes parser plugin. |
111+
| **strict** | `true` | Boolean value for enable or disable throw an exception. |
112+
| **mergeCustomizer** | `function` | Function callback passed to lodash `mergeWith` for merge `options.expressions.locals` and props passed via attribute `props`. |
113+
| **utilities** | `{merge: _.mergeWith, template: _.template}` | Object of utilities methods to be passed to `<script props>`. By default lodash `mergeWith` and `template`. |
114114

115115
## Features
116116

@@ -507,7 +507,7 @@ Create the component:
507507
<!-- src/my-component.html -->
508508
<script props>
509509
module.exports = {
510-
prop: locals.prop || 'Default prop value'
510+
prop: props.prop || 'Default prop value'
511511
}
512512
</script>
513513
<div>
@@ -548,17 +548,17 @@ The output will be:
548548
If you don't add the props in `<script props>` inside your component, all props will be added as attributes to the first node of your component or to the node with attribute `attributes`.
549549
More details on this in the next section.
550550

551-
So in the `<script props>` you have access to passed props via object `locals`, and you can add any logic you need inside of it.
551+
So in the `<script props>` you have access to passed props via object `props`, and you can add any logic you need inside it.
552552

553553
Create the component:
554554

555555
```html
556556
<!-- src/modal.html -->
557557
<script props>
558558
module.exports = {
559-
title: locals.title || 'Default title',
560-
size: locals.size ? `modal-${locals.size}` : '',
561-
items: Array.isArray(locals.items) ? locals.items.concat(['first', 'second']) : ['first', 'second']
559+
title: props.title || 'Default title',
560+
size: props.size ? `modal-${props.size}` : '',
561+
items: Array.isArray(props.items) ? props.items.concat(['first', 'second']) : ['first', 'second']
562562
}
563563
</script>
564564
<div class="modal {{ size }}">
@@ -595,7 +595,7 @@ The output will be:
595595

596596
You can also notice how the `class` attribute is merged with `class` attribute of the first node. Let's see in next section more about this.
597597

598-
You can change how attributes are merged with global locals defined via options by passing a callback function used by lodash method [mergeWith](https://lodash.com/docs/4.17.15#mergeWith).
598+
You can change how attributes are merged with global props defined via options by passing a callback function used by lodash method [mergeWith](https://lodash.com/docs/4.17.15#mergeWith).
599599

600600
By default, all props are scoped to the component, and are not available to nested components. You can however change this accordingly to your need.
601601
Let's see below example.
@@ -606,7 +606,7 @@ Create a component:
606606
<!-- src/child.html -->
607607
<script props>
608608
module.exports = {
609-
prop: locals.prop || 'Default prop value'
609+
prop: props.prop || 'Default prop value'
610610
}
611611
</script>
612612
<div>
@@ -621,7 +621,7 @@ Create another component that use the first one:
621621
<!-- src/parent.html -->
622622
<script props>
623623
module.exports = {
624-
prop: locals.prop || 'Default prop value'
624+
prop: props.prop || 'Default prop value'
625625
}
626626
</script>
627627
<div>
@@ -678,7 +678,7 @@ As already seen in basic example:
678678
<!-- src/button.html -->
679679
<script props>
680680
module.exports = {
681-
label: locals.label || 'A button'
681+
label: props.label || 'A button'
682682
}
683683
</script>
684684
<button type="button" class="btn">
@@ -911,7 +911,7 @@ You can also combine both way, and then use them with slots or with small compon
911911
</x-modal.body>
912912
</if>
913913
<if condition="$slots.footer?.filled">
914-
<x-modal.footer close="{{ $slots.footer?.locals.close }}">
914+
<x-modal.footer close="{{ $slots.footer?.props.close }}">
915915
<slot:footer></slot:footer>
916916
</x-modal.footer>
917917
</if>

0 commit comments

Comments
 (0)