Skip to content

Commit

Permalink
Added more docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@thewebartisan7
thewebartisan7 committed Oct 23, 2022
1 parent 77e8f62 commit 4ea6fd1
Show file tree
Hide file tree
Showing 7 changed files with 503 additions and 91 deletions.
197 changes: 181 additions & 16 deletions examples/dist/docs.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -158,7 +158,7 @@
</ul>
</li>
<li class="nav-item">
<a class="nav-link" href="#tips-and-tricks">Tips and tricks</a>
<a class="nav-link" href="#examples">Examples</a>
<ul class="nav flex-column">
<li class="nav-item">
<a class="nav-link" href="#using-slots">Using slots</a>
Expand All @@ -173,6 +173,17 @@
</li>
<li class="nav-item">
<a class="nav-link" href="#migration">Migration</a>
<ul class="nav flex-column">
<li class="nav-item">
<a class="nav-link" href="#posthtml-include">PostHTML Include</a>
</li>
<li class="nav-item">
<a class="nav-link" href="#posthtml-modules">PostHTML Modules</a>
</li>
<li class="nav-item">
<a class="nav-link" href="#posthtml-extends">PostHTML Extends</a>
</li>
</ul>
</li>
</ul>
</nav>
Expand Down Expand Up @@ -424,6 +435,21 @@ <h2 id="options" tabindex="-1">
).
</td>
</tr>
<tr>
<td style="text-align:center">
<strong>slotSeparator</strong>
</td>
<td style="text-align:center">
<code>:</code>
</td>
<td style="text-align:left">
String value used for separate
<code>&lt;slot&gt;</code>
and
<code>&lt;fill&gt;</code>
tag from their names.
</td>
</tr>
<tr>
<td style="text-align:center">
<strong>push</strong>
Expand Down Expand Up @@ -949,20 +975,69 @@ <h3 id="props" tabindex="-1">
<a href="https://github.com/posthtml/posthtml-expressions">posthtml-expressions</a>
plugin, with feature to pass
<code>props</code>
via attributes, define default via
(locals) via attributes, define default via
<code>&lt;script props&gt;</code>
, merge with default and use
<code>&lt;script props&gt;</code>
as computed.
</p>
<p>Let's see how it works with an example.</p>
<p>Let's see how it works with a few examples starting with a basic one.</p>
<p>Create the component:</p>
<pre><code class="language-html">&lt;!-- src/my-component.html --&gt;
&lt;script props&gt;
module.exports = {
prop: 'Default prop value'
}
&lt;/script&gt;
&lt;div&gt;
{{ prop }}
&lt;/div&gt;</code></pre>
<p>Use:</p>
<pre><code class="language-html">&lt;x-my-component prop=&quot;Hello world!&quot;&gt;&lt;/x-my-component&gt;</code></pre>
<p>The output will be:</p>
<pre><code class="language-html">&lt;div&gt;
Hello world!
&lt;/div&gt;</code></pre>
<p>
Without passing
<code>prop</code>
via attribute then the output would be
<code>Default prop value</code>
, as shown below.
</p>
<p>Use component without passing prop:</p>
<pre><code class="language-html">&lt;x-my-component&gt;&lt;/x-my-component&gt;</code></pre>
<p>The output will be:</p>
<pre><code class="language-html">&lt;div&gt;
Default prop value
&lt;/div&gt;</code></pre>
<p>
If you don't add the props in
<code>&lt;script props&gt;</code>
inside your component, all props will be added as attributes to the first node of your component or to the node with attribute
<code>attributes</code>
.
More details on this in the next section.
</p>
<p>
So by default
<code>&lt;script props&gt;</code>
act as default value, like the
<code>@props</code>
you define with Laravel Blade.
You can change this behaviour by prepending
<code>computed</code>
or
<code>merge</code>
to the attribute name like shown below.
</p>
<p>Create the component:</p>
<pre><code class="language-html">&lt;!-- src/modal.html --&gt;
&lt;script props&gt;
module.exports = {
title: 'Default title',
size: locals.size ? `modal-${locals.size}` : '',
items: ['first', 'second']
title: 'Default title', // This will be the default value
size: locals.size ? `modal-${locals.size}` : '', // This will be a computed value, so it's always used
items: ['first', 'second'] // This will be merged
}
&lt;/script&gt;
&lt;div class=&quot;modal {{ size }}&quot;&gt;
Expand Down Expand Up @@ -998,13 +1073,20 @@ <h3 id="props" tabindex="-1">
And the prop
<code>items</code>
is merged and not override.
You can also notice how the
<code>class</code>
attribute is merged with
<code>class</code>
attribute of the first node. Let's see in next section more about this.
</p>
<h3 id="attributes" tabindex="-1">
<a class="header-anchor" href="#attributes">#</a>
Attributes
</h3>
<p>
Your can pass any attributes to your components and this will be added to the first element of your component.
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
<code>attributes</code>
.
By default
<code>class</code>
and
Expand All @@ -1013,11 +1095,11 @@ <h3 id="attributes" tabindex="-1">
<code>class</code>
and
<code>style</code>
attribute of the first element of your component.
attribute.
All others attributes are override by default.
Only attribute not defined as
<code>props</code>
will be processed.
will be used.
</p>
<p>As already seen in basic example:</p>
<pre><code class="language-html">&lt;!-- src/button.html --&gt;
Expand All @@ -1044,23 +1126,48 @@ <h3 id="attributes" tabindex="-1">
</p>
<p>If you are familiar with Laravel Blade, this is also how Blade handle this.</p>
<p>
As said early, class and style are merged by default, if you want to override them, just prepend
As said early,
<code>class</code>
and
<code>style</code>
are merged by default, if you want to override them, just prepend
<code>override:</code>
to the attributes:
to the attribute name:
</p>
<pre><code class="language-html">&lt;!-- src/index.html --&gt;
&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>
<p>Result:</p>
<pre><code class="language-html">&lt;!-- dist/index.html --&gt;
&lt;button type=&quot;submit&quot; class=&quot;btn-custom&quot;&gt;My button&lt;/button&gt;</code></pre>
<p>
If you want to use another node for add such attributes, then you can add the attribute
<code>attributes</code>
like shown below.
</p>
<pre><code class="language-html">&lt;!-- src/my-component.html --&gt;
&lt;div class=&quot;first-node&quot;&gt;
&lt;div class=&quot;second-node&quot; attributes&gt;
Hello world!
&lt;/div&gt;
&lt;/div&gt;</code></pre>
<p>Use the component:</p>
<pre><code class="language-html">&lt;!-- src/index.html --&gt;
&lt;x-my-component class=&quot;my-class&quot;&gt;&lt;/x-my-component&gt;</code></pre>
<p>Result:</p>
<pre><code class="language-html">&lt;!-- dist/index.html --&gt;
&lt;div class=&quot;first-node&quot;&gt;
&lt;div class=&quot;second-node my-class&quot;&gt;
Hello world!
&lt;/div&gt;
&lt;/div&gt;</code></pre>
<p>
You can add custom rules how attributes are parsed, as behind the scene it's used
<a href="https://github.com/posthtml/posthtml-attrs-parser">posthtml-attrs-parser</a>
plugin.
</p>
<h2 id="tips-and-tricks" tabindex="-1">
<a class="header-anchor" href="#tips-and-tricks">#</a>
Tips and tricks
<h2 id="examples" tabindex="-1">
<a class="header-anchor" href="#examples">#</a>
Examples
</h2>
<p>
You can work with
Expand Down Expand Up @@ -1241,9 +1348,67 @@ <h2 id="migration" tabindex="-1">
and/or
<code>posthtml-modules</code>
then you can continue to keep them until you migrate all of your components.
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.
This because the new version has different logic to handle slots and locals, as well the yield content.
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:
<a href="https://github.com/thewebartisan7/posthtml-components/issues/16">posthtml-components/issues/16</a>
.
</p>
<h3 id="posthtml-include" tabindex="-1">
<a class="header-anchor" href="#posthtml-include">#</a>
PostHTML Include
</h3>
<p>
PostHTML Include plugin can work when passed via
<code>options.plugins</code>
like below example:
</p>
<pre><code class="language-js">require(&quot;posthtml-component&quot;)({
root: &quot;./src&quot;,
folders: [&quot;components&quot;, &quot;layouts&quot;],
plugins: [
require(&quot;posthtml-include&quot;)({
encoding: &quot;utf8&quot;,
root: &quot;./src&quot;
}),
]
})</code></pre>
<h3 id="posthtml-modules" tabindex="-1">
<a class="header-anchor" href="#posthtml-modules">#</a>
PostHTML Modules
</h3>
<p>
At the moment doesn't work when nested inside PostHTML Components plugin since it use
<code>tree.match</code>
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:
</p>
<pre><code class="language-js">require(&quot;posthtml-component&quot;)({
root: &quot;./src&quot;,
folders: [&quot;components&quot;, &quot;layouts&quot;],
tag: 'module',
attribute: 'href',
yield: 'content'
plugins: [
require(&quot;posthtml-include&quot;)({
encoding: &quot;utf8&quot;,
root: &quot;./src/www/posthtml-templates/&quot;
}),
]
})</code></pre>
<p>
NOTE: If you change
<code>&lt;yield&gt;</code>
tag to
<code>&lt;content&gt;</code>
to support your existing code, then you need to use it always. Maybe you can just replace all
<code>&lt;content&gt;</code>
with
<code>&lt;yield&gt;</code>
and it should works fine.
</p>
<h3 id="posthtml-extends" tabindex="-1">
<a class="header-anchor" href="#posthtml-extends">#</a>
PostHTML Extends
</h3>
<p>Not yet tested.</p>
</div>
</div>
</div>
Expand Down
6 changes: 3 additions & 3 deletions examples/dist/demo.html → examples/dist/test.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -48,8 +48,8 @@
<div class="row">
<div class="col-lg-8">
<h1 class="display-1 fw-bold mb-4">Demo</h1>
<div class="wrapper my-demo" something="alocal">
<div class="demo">
<div class="wrapper">
<div class="demo my-demo" something="alocal">
<h1>anObjectDefault</h1>
<p>
<strong>first</strong>
Expand Down Expand Up @@ -90,7 +90,7 @@ <h1>anObjectMerged</h1>
: Fourth merged item
</p>
<h1>aStringDefault</h1>
<p>My default string</p>
<p></p>
<h1>aStringOverride</h1>
<p>My override string changed</p>
<hr>
Expand Down
4 changes: 2 additions & 2 deletions examples/src/components/demo.html → examples/src/components/test.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@
};
</script>
<div class="wrapper">
<div class="demo">
<div class="demo" attributes>
<h1>anObjectDefault</h1>
<each loop="o,i in anObjectDefault">
<p><strong>{{ i }}</strong>: {{ o }}</p>
Expand All @@ -68,7 +68,7 @@ <h1>anObjectMerged</h1>
</each>

<h1>aStringDefault</h1>
<p>{{ aStringDefault }}</p>
<p></p>

<h1>aStringOverride</h1>
<p>{{ aStringOverride }}</p>
Expand Down
Loading

0 comments on commit 4ea6fd1

Please sign in to comment.