pHTML Define 
pHTML Define lets you use custom defined elements in HTML.
<!-- definitions.html -->
<define tag="pricing-tier">
<header>
<h1>$<slot name="price" /></h1>
<h2><slot name="name" /></h2>
</header>
<div class="features">
<slot name="features" />
</div>
</define>
<!-- index.html -->
<link rel="html" href="definitions.html" />
<pricing-tier slot-name="Basic">
<slot name="price">10</slot>
<ul slot="features">
<li>Unlimited foo</li>
</ul>
</pricing-tier>
<!-- becomes -->
<header>
<h1>$10</h1>
<h2>Basic</h2>
</header>
<div class="features">
<ul>
<li>Unlimited foo</li>
</ul>
</div>Definition elements (<define>) can exist on the same page they are being
referenced. Definition imports (<link rel="html" href>) can reference real URLs.
Slots
Slots are dynamically replaced elements and attribute values.
Within <define> elements, slots can referenced as elements or attribute
values. A <slot> element identifies its replacement with a name attribute —
e.g <slot name="some-id" /> — while a slot attribute value identifies its
replacement with a dollar sign ($), wrapping curly braces ({}), and a
slot prefix — e.g. ${slot-some-id}.
<!-- a slot element referencing "price" -->
<slot name="price" />
<!-- a slot element referencing "price" with a fallback value of "0" -->
<slot name="price">0</slot><!-- a slot attribute value referencing "src" -->
<img src="images/${slot-src}">
<!-- a slot attribute value referencing "src" with a fallback value of "default.jpg" -->
<img src="images/${slot-src,default.jpg}">Within custom elements, slots are populated by element or attribute.
<!-- populate a slot named "src" with image.jpg -->
<x-image slot-src="image.jpg" /><!-- populate a slot named "src" with image.jpg -->
<slot name="src">image.jpg</slot><!-- populate a slot named "features" with <p>I will run</p> -->
<p slot="features">I will run</p>Usage
Add pHTML Define to your project:
npm install @phtml/define --save-devUse pHTML Define to process your HTML:
const phtmlDefine = require('@phtml/define');
phtmlDefine.process(YOUR_HTML /*, processOptions, pluginOptions */);Or use it as a pHTML plugin:
const phtml = require('phtml');
const phtmlDefine = require('@phtml/define');
phtml([
phtmlDefine(/* pluginOptions */)
]).process(YOUR_HTML /*, processOptions */);pHTML Define runs in all Node environments, with special instructions for:
| Node | CLI | Eleventy | Gulp | Grunt |
|---|
Options
preserve
The preserve option determines whether all custom element containers should remain. By default, custom element containers are not preserve. However when
custom elements are preserved, their original children are moved into a
<template> element.
// preserve all custom elements
phtmlInclude({ preserve: true });<link rel="html" href="definitions.html" />
<pricing-tier slot-name="Basic">
<slot name="price">10</slot>
<ul slot="features">
<li>Unlimited foo</li>
</ul>
</pricing-tier>
<!-- becomes -->
<link rel="html" href="definitions.html" />
<pricing-tier slot-name="Basic">
<template>
<slot name="price">10</slot>
<ul slot="features">
<li>Unlimited foo</li>
</ul>
</template>
<header>
<h1>$10</h1>
<h2>Basic</h2>
</header>
<div class="features">
<ul>
<li>Unlimited foo</li>
</ul>
</div>
</pricing-tier>cwd
The cwd option defines and overrides the current working directory of
<link rel="html" href>.
// resolve all relative html links to /some/absolute/path
phtmlInclude({ cwd: '/some/absolute/path' });
