Skip to content

Commit 4ea6fd1

Browse files
thewebartisan7thewebartisan7
committed
Added more docs
1 parent 77e8f62 commit 4ea6fd1

File tree

7 files changed

+503
-91
lines changed

7 files changed

+503
-91
lines changed

‎examples/dist/docs.html

+181-16
Original file line numberDiff line numberDiff line change
@@ -158,7 +158,7 @@
158158
</ul>
159159
</li>
160160
<li class="nav-item">
161-
<a class="nav-link" href="#tips-and-tricks">Tips and tricks</a>
161+
<a class="nav-link" href="#examples">Examples</a>
162162
<ul class="nav flex-column">
163163
<li class="nav-item">
164164
<a class="nav-link" href="#using-slots">Using slots</a>
@@ -173,6 +173,17 @@
173173
</li>
174174
<li class="nav-item">
175175
<a class="nav-link" href="#migration">Migration</a>
176+
<ul class="nav flex-column">
177+
<li class="nav-item">
178+
<a class="nav-link" href="#posthtml-include">PostHTML Include</a>
179+
</li>
180+
<li class="nav-item">
181+
<a class="nav-link" href="#posthtml-modules">PostHTML Modules</a>
182+
</li>
183+
<li class="nav-item">
184+
<a class="nav-link" href="#posthtml-extends">PostHTML Extends</a>
185+
</li>
186+
</ul>
176187
</li>
177188
</ul>
178189
</nav>
@@ -424,6 +435,21 @@ <h2 id="options" tabindex="-1">
424435
).
425436
</td>
426437
</tr>
438+
<tr>
439+
<td style="text-align:center">
440+
<strong>slotSeparator</strong>
441+
</td>
442+
<td style="text-align:center">
443+
<code>:</code>
444+
</td>
445+
<td style="text-align:left">
446+
String value used for separate
447+
<code>&lt;slot&gt;</code>
448+
and
449+
<code>&lt;fill&gt;</code>
450+
tag from their names.
451+
</td>
452+
</tr>
427453
<tr>
428454
<td style="text-align:center">
429455
<strong>push</strong>
@@ -949,20 +975,69 @@ <h3 id="props" tabindex="-1">
949975
<a href="https://github.com/posthtml/posthtml-expressions">posthtml-expressions</a>
950976
plugin, with feature to pass
951977
<code>props</code>
952-
via attributes, define default via
978+
(locals) via attributes, define default via
953979
<code>&lt;script props&gt;</code>
954980
, merge with default and use
955981
<code>&lt;script props&gt;</code>
956982
as computed.
957983
</p>
958-
<p>Let's see how it works with an example.</p>
984+
<p>Let's see how it works with a few examples starting with a basic one.</p>
985+
<p>Create the component:</p>
986+
<pre><code class="language-html">&lt;!-- src/my-component.html --&gt;
987+
&lt;script props&gt;
988+
module.exports = {
989+
prop: 'Default prop value'
990+
}
991+
&lt;/script&gt;
992+
&lt;div&gt;
993+
{{ prop }}
994+
&lt;/div&gt;</code></pre>
995+
<p>Use:</p>
996+
<pre><code class="language-html">&lt;x-my-component prop=&quot;Hello world!&quot;&gt;&lt;/x-my-component&gt;</code></pre>
997+
<p>The output will be:</p>
998+
<pre><code class="language-html">&lt;div&gt;
999+
Hello world!
1000+
&lt;/div&gt;</code></pre>
1001+
<p>
1002+
Without passing
1003+
<code>prop</code>
1004+
via attribute then the output would be
1005+
<code>Default prop value</code>
1006+
, as shown below.
1007+
</p>
1008+
<p>Use component without passing prop:</p>
1009+
<pre><code class="language-html">&lt;x-my-component&gt;&lt;/x-my-component&gt;</code></pre>
1010+
<p>The output will be:</p>
1011+
<pre><code class="language-html">&lt;div&gt;
1012+
Default prop value
1013+
&lt;/div&gt;</code></pre>
1014+
<p>
1015+
If you don't add the props in
1016+
<code>&lt;script props&gt;</code>
1017+
inside your component, all props will be added as attributes to the first node of your component or to the node with attribute
1018+
<code>attributes</code>
1019+
.
1020+
More details on this in the next section.
1021+
</p>
1022+
<p>
1023+
So by default
1024+
<code>&lt;script props&gt;</code>
1025+
act as default value, like the
1026+
<code>@props</code>
1027+
you define with Laravel Blade.
1028+
You can change this behaviour by prepending
1029+
<code>computed</code>
1030+
or
1031+
<code>merge</code>
1032+
to the attribute name like shown below.
1033+
</p>
9591034
<p>Create the component:</p>
9601035
<pre><code class="language-html">&lt;!-- src/modal.html --&gt;
9611036
&lt;script props&gt;
9621037
module.exports = {
963-
title: 'Default title',
964-
size: locals.size ? `modal-${locals.size}` : '',
965-
items: ['first', 'second']
1038+
title: 'Default title', // This will be the default value
1039+
size: locals.size ? `modal-${locals.size}` : '', // This will be a computed value, so it's always used
1040+
items: ['first', 'second'] // This will be merged
9661041
}
9671042
&lt;/script&gt;
9681043
&lt;div class=&quot;modal {{ size }}&quot;&gt;
@@ -998,13 +1073,20 @@ <h3 id="props" tabindex="-1">
9981073
And the prop
9991074
<code>items</code>
10001075
is merged and not override.
1076+
You can also notice how the
1077+
<code>class</code>
1078+
attribute is merged with
1079+
<code>class</code>
1080+
attribute of the first node. Let's see in next section more about this.
10011081
</p>
10021082
<h3 id="attributes" tabindex="-1">
10031083
<a class="header-anchor" href="#attributes">#</a>
10041084
Attributes
10051085
</h3>
10061086
<p>
1007-
Your can pass any attributes to your components and this will be added to the first element of your component.
1087+
Your can pass any attributes to your components and this will be added to the first node of your component, or to the node with an attribute named
1088+
<code>attributes</code>
1089+
.
10081090
By default
10091091
<code>class</code>
10101092
and
@@ -1013,11 +1095,11 @@ <h3 id="attributes" tabindex="-1">
10131095
<code>class</code>
10141096
and
10151097
<code>style</code>
1016-
attribute of the first element of your component.
1098+
attribute.
10171099
All others attributes are override by default.
10181100
Only attribute not defined as
10191101
<code>props</code>
1020-
will be processed.
1102+
will be used.
10211103
</p>
10221104
<p>As already seen in basic example:</p>
10231105
<pre><code class="language-html">&lt;!-- src/button.html --&gt;
@@ -1044,23 +1126,48 @@ <h3 id="attributes" tabindex="-1">
10441126
</p>
10451127
<p>If you are familiar with Laravel Blade, this is also how Blade handle this.</p>
10461128
<p>
1047-
As said early, class and style are merged by default, if you want to override them, just prepend
1129+
As said early,
1130+
<code>class</code>
1131+
and
1132+
<code>style</code>
1133+
are merged by default, if you want to override them, just prepend
10481134
<code>override:</code>
1049-
to the attributes:
1135+
to the attribute name:
10501136
</p>
10511137
<pre><code class="language-html">&lt;!-- src/index.html --&gt;
10521138
&lt;x-button type=&quot;submit&quot; override:class=&quot;btn-custom&quot; label=&quot;My button&quot;&gt;&lt;/x-button&gt;</code></pre>
10531139
<p>Result:</p>
10541140
<pre><code class="language-html">&lt;!-- dist/index.html --&gt;
10551141
&lt;button type=&quot;submit&quot; class=&quot;btn-custom&quot;&gt;My button&lt;/button&gt;</code></pre>
1142+
<p>
1143+
If you want to use another node for add such attributes, then you can add the attribute
1144+
<code>attributes</code>
1145+
like shown below.
1146+
</p>
1147+
<pre><code class="language-html">&lt;!-- src/my-component.html --&gt;
1148+
&lt;div class=&quot;first-node&quot;&gt;
1149+
&lt;div class=&quot;second-node&quot; attributes&gt;
1150+
Hello world!
1151+
&lt;/div&gt;
1152+
&lt;/div&gt;</code></pre>
1153+
<p>Use the component:</p>
1154+
<pre><code class="language-html">&lt;!-- src/index.html --&gt;
1155+
&lt;x-my-component class=&quot;my-class&quot;&gt;&lt;/x-my-component&gt;</code></pre>
1156+
<p>Result:</p>
1157+
<pre><code class="language-html">&lt;!-- dist/index.html --&gt;
1158+
&lt;div class=&quot;first-node&quot;&gt;
1159+
&lt;div class=&quot;second-node my-class&quot;&gt;
1160+
Hello world!
1161+
&lt;/div&gt;
1162+
&lt;/div&gt;</code></pre>
10561163
<p>
10571164
You can add custom rules how attributes are parsed, as behind the scene it's used
10581165
<a href="https://github.com/posthtml/posthtml-attrs-parser">posthtml-attrs-parser</a>
10591166
plugin.
10601167
</p>
1061-
<h2 id="tips-and-tricks" tabindex="-1">
1062-
<a class="header-anchor" href="#tips-and-tricks">#</a>
1063-
Tips and tricks
1168+
<h2 id="examples" tabindex="-1">
1169+
<a class="header-anchor" href="#examples">#</a>
1170+
Examples
10641171
</h2>
10651172
<p>
10661173
You can work with
@@ -1241,9 +1348,67 @@ <h2 id="migration" tabindex="-1">
12411348
and/or
12421349
<code>posthtml-modules</code>
12431350
then you can continue to keep them until you migrate all of your components.
1244-
For continue to use current code with this plugin without changing it, at the moment it's not yet fully supported, but it maybe comes in near future.
1245-
This because the new version has different logic to handle slots and locals, as well the yield content.
1351+
For continue to use current code with this plugin without changing it, see below examples. Any more updates on this will be added in this issue:
1352+
<a href="https://github.com/thewebartisan7/posthtml-components/issues/16">posthtml-components/issues/16</a>
1353+
.
1354+
</p>
1355+
<h3 id="posthtml-include" tabindex="-1">
1356+
<a class="header-anchor" href="#posthtml-include">#</a>
1357+
PostHTML Include
1358+
</h3>
1359+
<p>
1360+
PostHTML Include plugin can work when passed via
1361+
<code>options.plugins</code>
1362+
like below example:
12461363
</p>
1364+
<pre><code class="language-js">require(&quot;posthtml-component&quot;)({
1365+
root: &quot;./src&quot;,
1366+
folders: [&quot;components&quot;, &quot;layouts&quot;],
1367+
plugins: [
1368+
require(&quot;posthtml-include&quot;)({
1369+
encoding: &quot;utf8&quot;,
1370+
root: &quot;./src&quot;
1371+
}),
1372+
]
1373+
})</code></pre>
1374+
<h3 id="posthtml-modules" tabindex="-1">
1375+
<a class="header-anchor" href="#posthtml-modules">#</a>
1376+
PostHTML Modules
1377+
</h3>
1378+
<p>
1379+
At the moment doesn't work when nested inside PostHTML Components plugin since it use
1380+
<code>tree.match</code>
1381+
and even trying with something like PostHTML Include is doing here https://github.com/posthtml/posthtml-include/blob/master/lib/index.js#L16 doesn't work. But a workaround is to use PostHTML Components custom tag and attributes like below:
1382+
</p>
1383+
<pre><code class="language-js">require(&quot;posthtml-component&quot;)({
1384+
root: &quot;./src&quot;,
1385+
folders: [&quot;components&quot;, &quot;layouts&quot;],
1386+
tag: 'module',
1387+
attribute: 'href',
1388+
yield: 'content'
1389+
plugins: [
1390+
require(&quot;posthtml-include&quot;)({
1391+
encoding: &quot;utf8&quot;,
1392+
root: &quot;./src/www/posthtml-templates/&quot;
1393+
}),
1394+
]
1395+
})</code></pre>
1396+
<p>
1397+
NOTE: If you change
1398+
<code>&lt;yield&gt;</code>
1399+
tag to
1400+
<code>&lt;content&gt;</code>
1401+
to support your existing code, then you need to use it always. Maybe you can just replace all
1402+
<code>&lt;content&gt;</code>
1403+
with
1404+
<code>&lt;yield&gt;</code>
1405+
and it should works fine.
1406+
</p>
1407+
<h3 id="posthtml-extends" tabindex="-1">
1408+
<a class="header-anchor" href="#posthtml-extends">#</a>
1409+
PostHTML Extends
1410+
</h3>
1411+
<p>Not yet tested.</p>
12471412
</div>
12481413
</div>
12491414
</div>

‎examples/dist/demo.html ‎examples/dist/test.html

+3-3
Original file line numberDiff line numberDiff line change
@@ -48,8 +48,8 @@
4848
<div class="row">
4949
<div class="col-lg-8">
5050
<h1 class="display-1 fw-bold mb-4">Demo</h1>
51-
<div class="wrapper my-demo" something="alocal">
52-
<div class="demo">
51+
<div class="wrapper">
52+
<div class="demo my-demo" something="alocal">
5353
<h1>anObjectDefault</h1>
5454
<p>
5555
<strong>first</strong>
@@ -90,7 +90,7 @@ <h1>anObjectMerged</h1>
9090
: Fourth merged item
9191
</p>
9292
<h1>aStringDefault</h1>
93-
<p>My default string</p>
93+
<p></p>
9494
<h1>aStringOverride</h1>
9595
<p>My override string changed</p>
9696
<hr>

‎examples/src/components/demo.html ‎examples/src/components/test.html

+2-2
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@
5151
};
5252
</script>
5353
<div class="wrapper">
54-
<div class="demo">
54+
<div class="demo" attributes>
5555
<h1>anObjectDefault</h1>
5656
<each loop="o,i in anObjectDefault">
5757
<p><strong>{{ i }}</strong>: {{ o }}</p>
@@ -68,7 +68,7 @@ <h1>anObjectMerged</h1>
6868
</each>
6969

7070
<h1>aStringDefault</h1>
71-
<p>{{ aStringDefault }}</p>
71+
<p></p>
7272

7373
<h1>aStringOverride</h1>
7474
<p>{{ aStringOverride }}</p>

0 commit comments

Comments
 (0)