ht-pipe directive

`ht-pipe` directive reference

Overview

The ht-pipe directive moves elements and element contents from one location in a document to another.

Example

The ht-pipe directive is a general purpose utility for relocating elements in an HTML document. In this example we're going to focus on one specific use case: generating page-specific CSS styles.

One of our favorite things about working with a true HTML templating system is the native support for CSS <style> elements. Authoring HTML component fragments is quite refreshing when you can co-locate component styles alongside the corresponding layout. Instead of jumping back and forth between partials/component-a.html and static/css/component-a.css, everything you need is in one place.

Let's use the following example fragment to illustrate this point:

fragments/example.html

1<section class='banner'>
2    <style css-component>
3        /* Banner Styles */
4        section.banner { background-color: light-dark(rgba(255,255,255,1.0), rgba(0,0,0,1.0)); }
5        section.banner h3 { font-size: 1.25rem; }
6    </style>
7    <h3 ht-apply>${ page.banner.heading, "Banner heading" }</h3>
8    <p ht-apply>${ page.banner.text, "Banner text." }</p>
9</section>

There are several challenges with this approach in most HTML templating systems. One simple challenge is that <style> elements are applied in the order they are included in the document, and including them in the wrong order can cause unexpected cascade issues.

The ht-pipe directive can be used to address many of these issues by collecting disparate <style> elements into a predetermined location. In the following example layout, the ht-pipe directive is used to collect elements matching the [css-component] attribute selector.

layouts/default.html

 1<!DOCTYPE html>
 2<html lang='en-US'>
 3    <head>
 4        <!-- standard head elements go here -->
 5        <style id='components' ht-pipe='from "[css-component]" as css'></style>
 6        <style id='layout'>
 7            /* Layout-specific component styles go here */
 8
 9            /* Use NYC-inspired light gray and '26 carbon black for the banner */
10            section.banner { background-color: light-dark(rgba(212,212,212,1.0), rgba(26,26,26,1.0)); }
11        </style>
12    </head>
13    <body>
14        <header ht-include='fragments/header.html'></header>
15        <main>
16            <section ht-include='fragments/banner.html'></section>
17            <section ht-include='fragments/example.html'></section>
18            <section ht-include='fragments/sample.html'></section>
19        </main>
20        <footer ht-include='fragments/footer.html'></footer>
21    </body>
22</html>

When HyperTemplates encounters an element with an ht-pipe directive, it uses the provided selector to query the document for matching element. If one or more matching elements are found, they are inserted into the ht-pipe element.

In the example above, the ht-pipe='from "[css-component]" as css' defines the [css-component] attribute selector (i.e. document.querySelectorAll("[css-component]")), and it inserts matching elements as css (see pipe types, below).

Example output index.html

The resulting document will always apply default component styles (in the styles#components element) before layout-specific styles (in the styles#layout element).

 1<!DOCTYPE html>
 2<html lang='en-US'>
 3    <head>
 4        <!-- standard head elements go here -->
 5        <style id='components'>
 6            /* Banner Styles */
 7            section.banner { background-color: light-dark(rgba(255,255,255,1.0), rgba(0,0,0,1.0)); }
 8            section.banner h3 { font-size: 1.25rem; }
 9        </style>
10        <style id='layout'>
11            /* Layout-specific component styles go here */
12
13            /* Use NYC-inspired light gray and '26 carbon black for the banner */
14            section.banner { background-color: light-dark(rgba(212,212,212,1.0), rgba(26,26,26,1.0)); }
15        </style>
16    </head>
17    <body>
18        <header>
19            <!-- included fragments/header.html content -->
20        </header>
21        <main>
22            <section class='banner'>
23                <h3>Hello CSS world</h3>
24                <p>Same CSS problems, different day.</p>
25            </section>
26            <section>
27                <!-- included fragments/example.html content -->
28            </section>
29            <section>
30                <!-- included fragments/sample.html content -->
31            </section>
32        </main>
33        <footer>
34            <!-- included fragments/footer.html content -->
35        </footer>
36    </body>
37</html>

Notice that the banner section's child <style> element has been removed, and its contents have been added to the style#components element.

Specification

Supported elements

The ht-pipe directive can be used with any HTML element.

Directive syntax

The ht-pipe directive provides content templating instructions, expressed as a single from "selector" as type expressions, where selector is any valid CSS selector. Selectors must be wrapped in quotes. The pipe type is optional.

Example

1<style id='components' ht-pipe='from "[css-component]" as css'></style>

In this example, an element pipe has been configured to append matching <style> elements with css-component attributes to a destination element.

Destination elements

An element containing an ht-pipe directive is a destination element. Destination elements are declarative indicators of where matching elements will be moved to.

Matching elements

An element that matches an ht-pipe directive selector is a matching element. Matching elements are removed from the document and inserted into destination elements.

Pipe types

The ht-pipe directive is used to move HTML elements. The manner in which elements are moved can be configured by providing a pipe "type" (see directive syntax). The currently supported types are element (default), text, css, js, and javascript. The css, js, and javascript pipe types are aliases for text.

Element pipes append the target HTML element to the destination element.
Text pipes append the target HTML element contents (as text nodes) to the destination element.

NOTE: Unsupported types are ignored, effectively resulting in the default behavior (element pipes).

Example

1<style id='components' ht-pipe='from "[css-component]" as css'></style>

In this example, we're creating a text pipe to move matching <style> element text contents to the style#components element. Text pipes make it possible to aggregate snippets of code from multiple layout fragments into a single element.