Skip to content
Use custom defined elements in HTML
JavaScript HTML
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
src
test
.editorconfig
.gitignore
.rollup.js
.tape.js
.travis.yml
CHANGELOG.md
CONTRIBUTING.md
INSTALL.md
LICENSE.md
README.md
package.json

README.md

pHTML Define pHTML

NPM Version Build Status Support Chat

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-dev

Use 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' });
You can’t perform that action at this time.