docs/index.html
<!doctype html>
<html class="default no-js">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<title>Aych</title>
<meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" href="assets/css/main.css">
</head>
<body>
<header>
<div class="tsd-page-toolbar">
<div class="container">
<div class="table-wrap">
<div class="table-cell" id="tsd-search" data-index="assets/js/search.js" data-base=".">
<div class="field">
<label for="tsd-search-field" class="tsd-widget search no-caption">Search</label>
<input id="tsd-search-field" type="text" />
</div>
<ul class="results">
<li class="state loading">Preparing search index...</li>
<li class="state failure">The search index is not available</li>
</ul>
<ul class="results-priority" style="display:none">
</ul>
<a href="index.html" class="title">Aych</a>
</div>
<div class="table-cell" id="tsd-widgets">
<div id="tsd-filter">
<a href="#" class="tsd-widget options no-caption" data-toggle="options">Options</a>
<div class="tsd-filter-group">
<div class="tsd-select" id="tsd-filter-visibility">
<span class="tsd-select-label">All</span>
<ul class="tsd-select-list">
<li data-value="public">Public</li>
<li data-value="protected">Public/Protected</li>
<li data-value="private" class="selected">All</li>
</ul>
</div>
<input type="checkbox" id="tsd-filter-inherited" checked />
<label class="tsd-widget" for="tsd-filter-inherited">Inherited</label>
</div>
</div>
<a href="#" class="tsd-widget menu no-caption" data-toggle="menu">Menu</a>
</div>
</div>
</div>
</div>
<div class="tsd-page-title">
<div class="container">
<ul class="tsd-breadcrumb">
</ul>
</div>
</div>
</header>
<div class="container container-main">
<div class="row">
<div class="col-3 col-menu menu-sticky-wrap menu-highlight">
<nav class="tsd-navigation outline primary">
<a style="margin-left:0em" href="globals.html">Globals</a>
<ul style="display:none">
{"Library":{"H":"_h_","Aych":"classes/_core_aych_.aych"},"Core":{"Piper":"classes/_core_piper_.piper","Renderable":"classes/_core_renderable_.renderable","StringLiteral":"classes/_core_stringliteral_.stringliteral"},"Elements":{"Element":"classes/_elements_element_.element","EmptyElement":"classes/_elements_emptyelement_.emptyelement","NestableElement":"classes/_elements_nestableelement_.nestableelement"},"Interfaces":{"Attributes":"interfaces/_interfaces_attributes_.attributes","RenderOptions":"interfaces/_interfaces_render_options_.renderoptions","SimpleObject":"interfaces/_interfaces_simple_object_.simpleobject"},"Structural":{"Each":"classes/_structural_each_.each","If":"classes/_structural_if_.if","Switch":"classes/_structural_switch_.switch","Group":"classes/_structural_group_.group"}}
</ul>
</nav>
</div>
<div class="col-7 offset-3 col-content">
<h1>Aych</h1>
<div class="tsd-panel tsd-typography">
<a href="#aych" id="aych" style="color: inherit; text-decoration: none;">
<h1>Ayc[H]</h1>
</a>
<p>A javascript library for writing eloquent HTML to create dynamic webpages without
the bells and whistles of a framework.</p>
<p><a href="https://travis-ci.com/github/shawnholman/Aych"><img src="https://travis-ci.com/shawnholman/Aych.svg?token=593S1dXVHUzTznXmMuYA&branch=master&status=created" alt="build"></a>
<a href="https://codecov.io/gh/shawnholman/Aych"><img src="https://img.shields.io/codecov/c/github/shawnholman/aych/master?token=XLW5V9O2CF" alt="coverage"></a>
<a href="https://codeclimate.com/github/shawnholman/Aych/maintainability"><img src="https://api.codeclimate.com/v1/badges/b154a8ee535354814515/maintainability" alt="Maintainability"></a></p>
<a href="#overview" id="overview" style="color: inherit; text-decoration: none;">
<h2>Overview</h2>
</a>
<p>Writing HTML inside of JavaScript has been a pain for many years for myself. With today’s
technologies, you are either stuck with a blob of HTML inside of your JavaScript, you rely
on heavy templating engines that hardly make anything better, or you use a framework.
Aych solves a decade old problem in a new way and
make dynamic HTML independent of large frameworks that do the heavy lifting. Aych provides
a micro-library to facilitate writing eloquent HTML inside of JavaScript.
It’s that simple, but very powerful.</p>
<a href="#example-usage" id="example-usage" style="color: inherit; text-decoration: none;">
<h2>Example Usage</h2>
</a>
<p>The following is an example of one way Aych can be used. See the <code>tests</code> (<a href="https://github.com/shawnholman/Aych/tree/master/tests">github/Aych/tests</a>) folder for a comprehensive set of examples.</p>
<a href="#using-aych" id="using-aych" style="color: inherit; text-decoration: none;">
<h4>Using Aych:</h4>
</a>
<pre><code class="language-javascript">H.$(({ div, row, $if, $eachIn, span }) => {
<span class="hljs-keyword">return</span> div(<span class="hljs-string">'#example.row.view-badge-info'</span>,
$if(!data.badge.isActive,
div(<span class="hljs-string">'.row.text-center.inactive-badge'</span>, <span class="hljs-string">'Disabled Badge'</span>)
),
div(<span class="hljs-string">'.col.col-xs-7.col-sm-7.col-md-7.text-left'</span>,
row(<span class="hljs-string">'Name'</span>, <span class="hljs-string">'{{user.name}}'</span>),
row(<span class="hljs-string">'Email'</span>, <span class="hljs-string">'{{user.email}}'</span>),
row(<span class="hljs-string">'Points'</span>, <span class="hljs-string">'{{user.points}}'</span>),
$eachIn(data.user.application,
row(<span class="hljs-string">'{{item[0]|unCamelCase}}'</span>, <span class="hljs-string">'{{item[1]}}'</span>)
)
),
div(<span class="hljs-string">'.col.col-xs-5.col-sm-5.col-md-5.text-right'</span>,
$eachIn(data.user.is, <span class="hljs-function">(<span class="hljs-params">[name, value]</span>) =></span>
row(
H.string(<span class="hljs-string">'{{name|unCamelCase}}'</span>).render({name}),
span(<span class="hljs-string">'.permission-circle'</span>, {<span class="hljs-attr">class</span>: [value, <span class="hljs-string">'+granted'</span>, <span class="hljs-string">'+denied'</span>]})
)
)
)
)
}, data);</code></pre>
<a href="#where-the-data-are" id="where-the-data-are" style="color: inherit; text-decoration: none;">
<h4>where the data are:</h4>
</a>
<pre><code class="language-javascript"><span class="hljs-keyword">const</span> data = {
<span class="hljs-attr">badge</span>: {
<span class="hljs-attr">isActive</span>: <span class="hljs-literal">false</span>,
},
<span class="hljs-attr">user</span>: {
<span class="hljs-attr">name</span>: <span class="hljs-string">'John Doe'</span>,
<span class="hljs-attr">email</span>: <span class="hljs-string">'john doe@gmail.com'</span>,
<span class="hljs-attr">points</span>: <span class="hljs-number">0</span>,
<span class="hljs-attr">application</span>: {
<span class="hljs-attr">school</span>: <span class="hljs-string">'UGA'</span>,
<span class="hljs-attr">grade</span>: <span class="hljs-string">'Freshman'</span>,
<span class="hljs-attr">hometown</span>: <span class="hljs-string">'Atlanta'</span>,
<span class="hljs-attr">gradePointAverage</span>: <span class="hljs-string">'4.0'</span>,
},
<span class="hljs-attr">is</span>: {
<span class="hljs-attr">admin</span>: <span class="hljs-literal">false</span>,
<span class="hljs-attr">volunteer</span>: <span class="hljs-literal">true</span>,
<span class="hljs-attr">organizer</span>: <span class="hljs-literal">true</span>,
<span class="hljs-attr">owner</span>: <span class="hljs-literal">false</span>,
},
},
};</code></pre>
<a href="#results-in-the-following-html" id="results-in-the-following-html" style="color: inherit; text-decoration: none;">
<h4>results in the following html:</h4>
</a>
<pre><code class="language-html"><span class="hljs-tag"><<span class="hljs-name">div</span> <span class="hljs-attr">id</span>=<span class="hljs-string">"example"</span> <span class="hljs-attr">class</span>=<span class="hljs-string">"row view-badge-info"</span>></span>
<span class="hljs-tag"><<span class="hljs-name">div</span> <span class="hljs-attr">class</span>=<span class="hljs-string">"row text-center inactive-badge"</span>></span>Disabled Badge<span class="hljs-tag"></<span class="hljs-name">div</span>></span>
<span class="hljs-tag"><<span class="hljs-name">div</span> <span class="hljs-attr">class</span>=<span class="hljs-string">"col col-xs-7 col-sm-7 col-md-7 text-left"</span>></span>
<span class="hljs-tag"><<span class="hljs-name">div</span> <span class="hljs-attr">class</span>=<span class="hljs-string">"row"</span>></span>
<span class="hljs-tag"><<span class="hljs-name">div</span> <span class="hljs-attr">class</span>=<span class="hljs-string">"col"</span>></span>
<span class="hljs-tag"><<span class="hljs-name">strong</span>></span>Name<span class="hljs-tag"></<span class="hljs-name">strong</span>></span>: John Doe
<span class="hljs-tag"></<span class="hljs-name">div</span>></span>
<span class="hljs-tag"></<span class="hljs-name">div</span>></span>
<span class="hljs-tag"><<span class="hljs-name">div</span> <span class="hljs-attr">class</span>=<span class="hljs-string">"row"</span>></span>
<span class="hljs-tag"><<span class="hljs-name">div</span> <span class="hljs-attr">class</span>=<span class="hljs-string">"col"</span>></span>
<span class="hljs-tag"><<span class="hljs-name">strong</span>></span>Email<span class="hljs-tag"></<span class="hljs-name">strong</span>></span>: johndoe@gmail.com
<span class="hljs-tag"></<span class="hljs-name">div</span>></span>
<span class="hljs-tag"></<span class="hljs-name">div</span>></span>
<span class="hljs-tag"><<span class="hljs-name">div</span> <span class="hljs-attr">class</span>=<span class="hljs-string">"row"</span>></span>
<span class="hljs-tag"><<span class="hljs-name">div</span> <span class="hljs-attr">class</span>=<span class="hljs-string">"col"</span>></span>
<span class="hljs-tag"><<span class="hljs-name">strong</span>></span>Points<span class="hljs-tag"></<span class="hljs-name">strong</span>></span>: 0
<span class="hljs-tag"></<span class="hljs-name">div</span>></span>
<span class="hljs-tag"></<span class="hljs-name">div</span>></span>
<span class="hljs-tag"><<span class="hljs-name">div</span> <span class="hljs-attr">class</span>=<span class="hljs-string">"row"</span>></span>
<span class="hljs-tag"><<span class="hljs-name">div</span> <span class="hljs-attr">class</span>=<span class="hljs-string">"col"</span>></span>
<span class="hljs-tag"><<span class="hljs-name">strong</span>></span>School<span class="hljs-tag"></<span class="hljs-name">strong</span>></span>: UGA
<span class="hljs-tag"></<span class="hljs-name">div</span>></span>
<span class="hljs-tag"></<span class="hljs-name">div</span>></span>
<span class="hljs-tag"><<span class="hljs-name">div</span> <span class="hljs-attr">class</span>=<span class="hljs-string">"row"</span>></span>
<span class="hljs-tag"><<span class="hljs-name">div</span> <span class="hljs-attr">class</span>=<span class="hljs-string">"col"</span>></span>
<span class="hljs-tag"><<span class="hljs-name">strong</span>></span>Grade<span class="hljs-tag"></<span class="hljs-name">strong</span>></span>: Freshman
<span class="hljs-tag"></<span class="hljs-name">div</span>></span>
<span class="hljs-tag"></<span class="hljs-name">div</span>></span>
<span class="hljs-tag"><<span class="hljs-name">div</span> <span class="hljs-attr">class</span>=<span class="hljs-string">"row"</span>></span>
<span class="hljs-tag"><<span class="hljs-name">div</span> <span class="hljs-attr">class</span>=<span class="hljs-string">"col"</span>></span>
<span class="hljs-tag"><<span class="hljs-name">strong</span>></span>Hometown<span class="hljs-tag"></<span class="hljs-name">strong</span>></span>: Atlanta
<span class="hljs-tag"></<span class="hljs-name">div</span>></span>
<span class="hljs-tag"></<span class="hljs-name">div</span>></span>
<span class="hljs-tag"><<span class="hljs-name">div</span> <span class="hljs-attr">class</span>=<span class="hljs-string">"row"</span>></span>
<span class="hljs-tag"><<span class="hljs-name">div</span> <span class="hljs-attr">class</span>=<span class="hljs-string">"col"</span>></span>
<span class="hljs-tag"><<span class="hljs-name">strong</span>></span>Grade Point Average<span class="hljs-tag"></<span class="hljs-name">strong</span>></span>: 4.0
<span class="hljs-tag"></<span class="hljs-name">div</span>></span>
<span class="hljs-tag"></<span class="hljs-name">div</span>></span>
<span class="hljs-tag"></<span class="hljs-name">div</span>></span>
<span class="hljs-tag"><<span class="hljs-name">div</span> <span class="hljs-attr">class</span>=<span class="hljs-string">"col col-xs-5 col-sm-5 col-md-5 text-right"</span>></span>
<span class="hljs-tag"><<span class="hljs-name">div</span> <span class="hljs-attr">class</span>=<span class="hljs-string">"row"</span>></span>
<span class="hljs-tag"><<span class="hljs-name">div</span> <span class="hljs-attr">class</span>=<span class="hljs-string">"col"</span>></span>
<span class="hljs-tag"><<span class="hljs-name">strong</span>></span>Admin<span class="hljs-tag"></<span class="hljs-name">strong</span>></span>: <span class="hljs-tag"><<span class="hljs-name">span</span> <span class="hljs-attr">class</span>=<span class="hljs-string">"permission-circle denied"</span>></span><span class="hljs-tag"></<span class="hljs-name">span</span>></span>
<span class="hljs-tag"></<span class="hljs-name">div</span>></span>
<span class="hljs-tag"></<span class="hljs-name">div</span>></span>
<span class="hljs-tag"><<span class="hljs-name">div</span> <span class="hljs-attr">class</span>=<span class="hljs-string">"row"</span>></span>
<span class="hljs-tag"><<span class="hljs-name">div</span> <span class="hljs-attr">class</span>=<span class="hljs-string">"col"</span>></span>
<span class="hljs-tag"><<span class="hljs-name">strong</span>></span>Volunteer<span class="hljs-tag"></<span class="hljs-name">strong</span>></span>: <span class="hljs-tag"><<span class="hljs-name">span</span> <span class="hljs-attr">class</span>=<span class="hljs-string">"permission-circle granted"</span>></span><span class="hljs-tag"></<span class="hljs-name">span</span>></span>
<span class="hljs-tag"></<span class="hljs-name">div</span>></span>
<span class="hljs-tag"></<span class="hljs-name">div</span>></span>
<span class="hljs-tag"><<span class="hljs-name">div</span> <span class="hljs-attr">class</span>=<span class="hljs-string">"row"</span>></span>
<span class="hljs-tag"><<span class="hljs-name">div</span> <span class="hljs-attr">class</span>=<span class="hljs-string">"col"</span>></span><span class="hljs-tag"><<span class="hljs-name">strong</span>></span>Organizer<span class="hljs-tag"></<span class="hljs-name">strong</span>></span>: <span class="hljs-tag"><<span class="hljs-name">span</span> <span class="hljs-attr">class</span>=<span class="hljs-string">"permission-circle granted"</span>></span><span class="hljs-tag"></<span class="hljs-name">span</span>></span>
<span class="hljs-tag"></<span class="hljs-name">div</span>></span>
<span class="hljs-tag"></<span class="hljs-name">div</span>></span>
<span class="hljs-tag"><<span class="hljs-name">div</span> <span class="hljs-attr">class</span>=<span class="hljs-string">"row"</span>></span>
<span class="hljs-tag"><<span class="hljs-name">div</span> <span class="hljs-attr">class</span>=<span class="hljs-string">"col"</span>></span>
<span class="hljs-tag"><<span class="hljs-name">strong</span>></span>Owner<span class="hljs-tag"></<span class="hljs-name">strong</span>></span>: <span class="hljs-tag"><<span class="hljs-name">span</span> <span class="hljs-attr">class</span>=<span class="hljs-string">"permission-circle denied"</span>></span><span class="hljs-tag"></<span class="hljs-name">span</span>></span>
<span class="hljs-tag"></<span class="hljs-name">div</span>></span>
<span class="hljs-tag"></<span class="hljs-name">div</span>></span>
<span class="hljs-tag"></<span class="hljs-name">div</span>></span>
<span class="hljs-tag"></<span class="hljs-name">div</span>></span></code></pre>
<a href="#downloading" id="downloading" style="color: inherit; text-decoration: none;">
<h2>Downloading</h2>
</a>
<p>In order to use Aych, download <a href="https://github.com/shawnholman/Aych/tree/master/dist">aych.min.js</a> from the dist folder and load with:</p>
<pre><code class="language-html"><span class="hljs-tag"><<span class="hljs-name">script</span> <span class="hljs-attr">type</span>=<span class="hljs-string">"text/javascript"</span> <span class="hljs-attr">src</span>=<span class="hljs-string">"aych.min.js"</span>></span><span class="hljs-tag"></<span class="hljs-name">script</span>></span></code></pre>
<p>#Documentation
Aych is a library that is meant to stay slim and simple. This documentation should give you a good understanding of
Aych.</p>
<ul>
<li><a href="#globals">Globals</a><ul>
<li><a href="#conflict">Conflict</a></li>
</ul>
</li>
<li><a href="#renderable">Renderable</a></li>
<li><a href="#tags">Tags</a><ul>
<li><a href="#attributes">Attributes</a><ul>
<li><a href="#identifier-string">Identifier String</a></li>
<li><a href="#other-attributes">Other Attributes</a> </li>
</ul>
</li>
<li><a href="#empty-elements">Empty Elements</a></li>
<li><a href="#nestable-elements">Nestable Elements</a></li>
<li><a href="#string-literals">String Literals</a></li>
</ul>
</li>
<li><a href="#rendering">Rendering</a><ul>
<li><a href="#rendertemplates-options">.render(templates, options)</a><ul>
<li><a href="#templating">Templating</a></li>
<li><a href="#options">Options</a></li>
</ul>
</li>
<li><a href="#r">.r</a></li>
<li><a href="#tostring">.toString()</a></li>
</ul>
</li>
<li><a href="#piper">Piper</a></li>
<li><a href="#statements">Statements</a><ul>
<li><a href="#-scope">$</a></li>
<li><a href="#if">$if</a></li>
<li><a href="#each">$each</a></li>
<li><a href="#eachin">$eachIn</a></li>
<li><a href="#repeat">$repeat</a></li>
<li><a href="#group">$group</a></li>
<li><a href="#switch--case">$switch / $case</a></li>
</ul>
</li>
<li><a href="#more-examples">More Examples</a></li>
</ul>
<a href="#globals" id="globals" style="color: inherit; text-decoration: none;">
<h2>Globals</h2>
</a>
<p>To start off, Aych has two exposed globals: <code>Aych</code> and <code>H</code>. These are homonyms. <code>Aych</code> is the core of the library
while <code>H</code> is an instantiation of <code>Aych</code>. Their purposes are different, though.</p>
<p><code>Aych</code> is used to:</p>
<ol>
<li>Add/Remove Tags</li>
<li>Add/Remove Compositions</li>
<li>Access Piper</li>
</ol>
<p><code>H</code> is used to:</p>
<ol>
<li>Create HTML Tags</li>
<li>Call Statements</li>
</ol>
<a href="#conflict" id="conflict" style="color: inherit; text-decoration: none;">
<h3>Conflict</h3>
</a>
<p>Because <code>H</code> is just an instantiation of <code>Aych</code>, you can easily reassign it. Likewise, you can reassign <code>Aych</code> itself.</p>
<a href="#renderable" id="renderable" style="color: inherit; text-decoration: none;">
<h2>Renderable</h2>
</a>
<p>The term renderable is very important in understanding the rest of the documentation. A renderable is the foundational
logic for renderable child class to inherit and use. A renderable, conceptually, is a class that has a render method
that can be called to get a string representation of that class. Almost all functions under <code>H</code> will return a
renderable which supports the following API:</p>
<ul>
<li>render(templates, options): Renders a renderable with templates and options set.</li>
<li>with(templates): Sets the templates of the renderable</li>
<li>when (condition): Turns on and off renderability of the renderable.</li>
<li>get r(): Getter that calls the render method without templates or options. </li>
<li>toString(): Called when the renderable is converted to a string. Also calls the render method without templates or
options. </li>
</ul>
<a href="#tags" id="tags" style="color: inherit; text-decoration: none;">
<h2>Tags</h2>
</a>
<p>At the core of Aych, you want to be able to create HTML Tags. These tags follow the same naming conventions as the HTML
tags themselves and live under <code>H</code>.</p>
<p>For example:</p>
<pre><code class="language-javascript">H.span().r; </code></pre>
<p>Produces:</p>
<pre><code class="language-html"><span class="hljs-tag"><<span class="hljs-name">span</span>></span><span class="hljs-tag"></<span class="hljs-name">span</span>></span></code></pre>
<p><code>H.span()</code> returns a renderable and such needs to be resolved to a string using one of three ways to render:</p>
<ol>
<li>.render();</li>
<li>.r; <strong>(unsed in the example above)</strong></li>
<li>.toString(); (or anything that would cause toString to automatically call such as <code>+ ""</code>;</li>
</ol>
<p>More on rendering later.</p>
<p>Of course, HTML is a bit more complicated than a single span. This section will cover how to add attributes and
children to the elements.</p>
<a href="#attributes" id="attributes" style="color: inherit; text-decoration: none;">
<h2>Attributes</h2>
</a>
<p>There are many attributes in HTML but are all formatted similarly. We wanted to give a simple and easy way to add
attributes while adding control.</p>
<a href="#identifier-string" id="identifier-string" style="color: inherit; text-decoration: none;">
<h3>Identifier String</h3>
</a>
<p>The first thing we discovered about HTML, is that by far the most used attributes are <code>id</code> and <code>class</code>. For this reason
we developed the identifier string which dissolves into these two attributes.</p>
<p>The identifier string is a string you apply to the first parameter of any element. The string itself should either
start with a <code>#</code> (for id) or <code>.</code> (for class) and be followed up by 0 or more class names. If an id is specified, it
must come first.</p>
<p><strong>Identifier string should always be defined as the first parameter, but it's not require.</strong></p>
<p>Valid:</p>
<pre><code class="language-javascript">H.span(<span class="hljs-string">"#example.hello.world"</span>); </code></pre>
<p>Produces:</p>
<pre><code class="language-html"><span class="hljs-tag"><<span class="hljs-name">span</span> <span class="hljs-attr">id</span>=<span class="hljs-string">"example"</span> <span class="hljs-attr">class</span>=<span class="hljs-string">"hello world"</span>></span><span class="hljs-tag"></<span class="hljs-name">span</span>></span></code></pre>
<p>Invalid:</p>
<pre><code class="language-javascript">H.span(<span class="hljs-string">"example.hello.world"</span>); <span class="hljs-comment">// does not start with "#" or "."</span>
H.span(<span class="hljs-string">".hello.world#example"</span>); <span class="hljs-comment">// id should come first</span></code></pre>
<p>In fact, those invalid examples would actually register the string as a literal which will result in this:</p>
<pre><code class="language-html"><span class="hljs-tag"><<span class="hljs-name">span</span>></span>example.hello.world<span class="hljs-tag"></<span class="hljs-name">span</span>></span>
<span class="hljs-tag"><<span class="hljs-name">span</span>></span>.hello.world#example<span class="hljs-tag"></<span class="hljs-name">span</span>></span></code></pre>
<a href="#other-attributes" id="other-attributes" style="color: inherit; text-decoration: none;">
<h3>Other attributes</h3>
</a>
<p>Every other attribute can be given in an object either in place of the identifier string or afterwards.</p>
<p><strong>This list should always come after the identifier string (if used) and before children.</strong></p>
<p>The following examples gives some cools ways that the attribute object can be used to help manipulate attributes.</p>
<p>For example:</p>
<pre><code class="language-javascript">H.span(<span class="hljs-string">"#example.hello.world"</span>, {
<span class="hljs-comment">// Add the style attribute with given value.</span>
<span class="hljs-string">"style"</span>: <span class="hljs-string">"color: red"</span>,
<span class="hljs-comment">// Append / remove classes (remove with '-' instead of '+')</span>
<span class="hljs-string">"class"</span>: <span class="hljs-string">'+awesome'</span>,
<span class="hljs-comment">// Add an attribute with a conditional value.</span>
<span class="hljs-string">"lang"</span>: [<span class="hljs-literal">true</span>, <span class="hljs-string">"en-US"</span>, <span class="hljs-string">'en-UK'</span>],
<span class="hljs-comment">// Conditionally append/remove classes</span>
<span class="hljs-string">"class"</span>: [<span class="hljs-literal">false</span>, <span class="hljs-string">'+cool'</span>, <span class="hljs-string">'-world'</span>],
<span class="hljs-comment">// Includes attribute:</span>
<span class="hljs-string">"title"</span>: [<span class="hljs-literal">true</span>, <span class="hljs-string">"a span"</span>],
<span class="hljs-comment">// Excluse attribute</span>
<span class="hljs-string">"data-attr"</span>: [<span class="hljs-literal">false</span>, <span class="hljs-string">"value"</span>],
}); </code></pre>
<p>Produces:</p>
<pre><code class="language-html"><span class="hljs-tag"><<span class="hljs-name">span</span> <span class="hljs-attr">id</span>=<span class="hljs-string">"example"</span> <span class="hljs-attr">class</span>=<span class="hljs-string">"hello awesome"</span> <span class="hljs-attr">style</span>=<span class="hljs-string">"color: red;"</span> <span class="hljs-attr">lang</span>=<span class="hljs-string">"en-US"</span> <span class="hljs-attr">title</span>=<span class="hljs-string">"a span"</span>></span><span class="hljs-tag"></<span class="hljs-name">span</span>></span></code></pre>
<a href="#empty-elements" id="empty-elements" style="color: inherit; text-decoration: none;">
<h3>Empty Elements</h3>
</a>
<p>An empty element cannot have nested elements inside of it. An example of this is the HTML tag: <code>input</code>. The tag cannot
accept children. Empty elements in Aych should be treated the same way.</p>
<pre><code class="language-javascript">H.input().r; </code></pre>
<p>Produces:</p>
<pre><code class="language-html"><span class="hljs-tag"><<span class="hljs-name">input</span>></span></code></pre>
<a href="#nestable-elements" id="nestable-elements" style="color: inherit; text-decoration: none;">
<h3>Nestable Elements</h3>
</a>
<p>A nestable element can have nested elements inside of it. The majority of HTML tags are nestable like: <code>span</code>, <code>div</code>,
<code>strong</code>, etc.</p>
<p>For example:</p>
<pre><code class="language-javascript">H.span(H.div(), H.strong()).r; </code></pre>
<p>Produces:</p>
<pre><code class="language-html"><span class="hljs-tag"><<span class="hljs-name">span</span>></span><span class="hljs-tag"><<span class="hljs-name">div</span>></span><span class="hljs-tag"></<span class="hljs-name">div</span>></span><span class="hljs-tag"><<span class="hljs-name">strong</span>></span><span class="hljs-tag"></<span class="hljs-name">strong</span>></span><span class="hljs-tag"></<span class="hljs-name">span</span>></span></code></pre>
<p>In this case, we have <code>div</code> and <code>strong</code> tags nested inside of the single span. This is reflected in Aych by using the
power of variable arguments. We could add any number of elements within these parentheses. </p>
<p>This more complex example:</p>
<pre><code class="language-javascript">H.span(<span class="hljs-string">".class1"</span>, { <span class="hljs-string">"data-value"</span>: <span class="hljs-string">"somevalue"</span> },
H.div(H.strong(<span class="hljs-string">"#id.class2"</span>, <span class="hljs-string">"Hi"</span>)),
H.strong(H.div(H.strong(<span class="hljs-string">"Buddy"</span>)))
).r; </code></pre>
<p>Produces:</p>
<pre><code class="language-html"><span class="hljs-tag"><<span class="hljs-name">span</span> <span class="hljs-attr">class</span>=<span class="hljs-string">"class1"</span> <span class="hljs-attr">data-value</span>=<span class="hljs-string">"somevalue"</span>></span>
<span class="hljs-tag"><<span class="hljs-name">div</span>></span><span class="hljs-tag"><<span class="hljs-name">strong</span> <span class="hljs-attr">id</span>=<span class="hljs-string">"id"</span> <span class="hljs-attr">class</span>=<span class="hljs-string">"class2"</span>></span>Hi<span class="hljs-tag"></<span class="hljs-name">strong</span>></span><span class="hljs-tag"></<span class="hljs-name">div</span>></span>
<span class="hljs-tag"><<span class="hljs-name">strong</span>></span><span class="hljs-tag"><<span class="hljs-name">div</span>></span><span class="hljs-tag"><<span class="hljs-name">strong</span>></span>Buddy<span class="hljs-tag"></<span class="hljs-name">strong</span>></span><span class="hljs-tag"></<span class="hljs-name">div</span>></span><span class="hljs-tag"></<span class="hljs-name">strong</span>></span>
<span class="hljs-tag"></<span class="hljs-name">span</span>></span></code></pre>
<p>As you can see, the parameters for every attribute is flexible and follows these rules:</p>
<ol>
<li>Identifier string has to be the first parameter and valid. Otherwise, it will be a literal.</li>
<li>Attribute has to follow identifier string but preceed children. </li>
<li>Children must come after identifier string and attributes.</li>
</ol>
<p><code>1</code> is very important because a malformed identifier string could lead to unexpected errors as it would be treated
as a child meaning that attributes followed by a child would lead to this error.</p>
<p>Maybe you can also tell that the children were not explicitly rendered using '.r'. Only the <code>span</code> is rendered.
This is by design as rendering bubbles down to the children. In fact, rendering the children will cause unexpected
results because the string returned by ".r" would be read as a literal, and the HTML produced by it escaped by the
parent.</p>
<a href="#string-literals" id="string-literals" style="color: inherit; text-decoration: none;">
<h3>String Literals</h3>
</a>
<p>Aych supports printing string literals within tags. Any stringable type can be used as a string literal including
numbers and arrays.</p>
<p>String literals can be used directly in Aych as children as they are considered renderable. You can also use
<code>Aych.string()</code> to create a string literal. String literals should not contain any HTML as it will be escaped
automatically. If you would like a string literal that does not have this functionality, you can use <code>Aych.unescape()</code>
in place of using a string literal or <code>Aych.string()</code>.</p>
<p>These string literals also support a simple templating that can pull data from the templates passed in through
the render method. More on that in the render section. However, this would look like this:</p>
<pre><code class="language-javascript">H.string(<span class="hljs-string">"{{name}}"</span>).render({ <span class="hljs-attr">name</span>: <span class="hljs-string">'John'</span> }); <span class="hljs-comment">// output: "John"</span></code></pre>
<a href="#rendering" id="rendering" style="color: inherit; text-decoration: none;">
<h2>Rendering</h2>
</a>
<p>Rendering in aych is the process of turning a function into it's HTML equivalence. Rendering can be done in three ways:</p>
<ol>
<li>.render(templates, options)</li>
<li>.r</li>
<li>.toString();</li>
</ol>
<a href="#rendertemplates-options" id="rendertemplates-options" style="color: inherit; text-decoration: none;">
<h3>.render(templates, options);</h3>
</a>
<p>The most powerful way to render is with the <code>render</code> method which allows you to pass in templates and options for the
rendering. Template data can be used inside of string literals to conveniently access data.</p>
<a href="#templating" id="templating" style="color: inherit; text-decoration: none;">
<h4>Templating</h4>
</a>
<p>Aych supports a very simple templating. One of the design goals was to keep this engine very simple. It supports
accessing data from the templating object, and it also supports piping. See the piping section for details.</p>
<p>You can access data inside of the template string using the <code>{{ }}</code> operators with the name of the data location. Aych
supports accessing nested objects and arrays.</p>
<pre><code class="language-javascript">H.div(<span class="hljs-string">"{{name.first[0]}} {{name.last[1]}}"</span>).render({
<span class="hljs-attr">name</span>: {
<span class="hljs-attr">first</span>: [<span class="hljs-string">'John'</span>, <span class="hljs-string">'Billy'</span>],
<span class="hljs-attr">last</span>: [<span class="hljs-string">'Hanks'</span>, <span class="hljs-string">'Doe'</span>]
}
}); <span class="hljs-comment">// output: "<div>John Doe</div>"</span></code></pre>
<p>As mentioned, there is also support for piping, or transforming the data using the pipe operator (<code>|</code>):</p>
<pre><code class="language-javascript">H.div(<span class="hljs-string">"{{name.first[0]|uppercase}} {{name.last[1]|substr(0, 1)}}"</span>).render({
<span class="hljs-attr">name</span>: {
<span class="hljs-attr">first</span>: [<span class="hljs-string">'John'</span>, <span class="hljs-string">'Billy'</span>],
<span class="hljs-attr">last</span>: [<span class="hljs-string">'Hanks'</span>, <span class="hljs-string">'Doe'</span>]
}
}); <span class="hljs-comment">// output: "<div>JOHN d</div>"</span></code></pre>
<p>As you can see, pipes can even have parameters! The substr pipe is using <code>String.prototype.substr</code>.</p>
<a href="#options" id="options" style="color: inherit; text-decoration: none;">
<h4>Options</h4>
</a>
<p>The options are part of an interface called the RenderOptions. You can checkout the API for details on each option.</p>
<a href="#r" id="r" style="color: inherit; text-decoration: none;">
<h3>.r</h3>
</a>
<p>The <code>.r</code> getter calls the <code>.render()</code> method without any templates or options.</p>
<pre><code class="language-javascript">H.div().r; <span class="hljs-comment">// output: "<div></div>"</span></code></pre>
<a href="#tostring" id="tostring" style="color: inherit; text-decoration: none;">
<h3>.toString()</h3>
</a>
<pre><code class="language-javascript">H.div() + <span class="hljs-string">""</span>; <span class="hljs-comment">// output: "<div></div>"</span>
<span class="hljs-comment">// equivalent to:</span>
H.div().toString();</code></pre>
<a href="#custom-tagscompositions" id="custom-tagscompositions" style="color: inherit; text-decoration: none;">
<h2>Custom Tags/Compositions</h2>
</a>
<p>Aych wants to remain flexible which means allowing developers to extend the library. Aych makes this possible through
the <code>Aych.create()</code> and <code>Aych.compose()</code>.</p>
<a href="#aychcreate" id="aychcreate" style="color: inherit; text-decoration: none;">
<h3>Aych.create()</h3>
</a>
<p><code>Aych.create()</code> allows you to define custom HTML tags to be used within H. You create a tag by specifying whether it's
nestable or empty and then naming it. These tags can be used just like any other renderable in Aych.</p>
<pre><code class="language-javascript">Aych.create(<span class="hljs-string">'custom'</span>, Aych.ElementType.NESTED);
Aych.create(<span class="hljs-string">'custom-element'</span>, Aych.ElementType.EMPTY);
H.custom(<span class="hljs-string">"#id"</span>).r; <span class="hljs-comment">// output: <custom id="id"></custom></span>
H.customElement().r <span class="hljs-comment">// output: <custom-element></custom-element></span></code></pre>
<p><strong>Note: The name of the tag should be a valid HTML tag name.</strong></p>
<a href="#aychcompose" id="aychcompose" style="color: inherit; text-decoration: none;">
<h3>Aych.compose()</h3>
</a>
<p>In Aych, a composition is a reusable set of HTML elements. A composition is created using the <code>compose</code> method under
<code>Aych</code>. The first parameter is the name of the composition while the second parameter is an anonymous function that
should return the renderable that represents the composition. The arguments injected into the anonymous function
will correspond to the arguments used in the composition call.</p>
<pre><code class="language-javascript">Aych.compose(<span class="hljs-string">'row'</span>, <span class="hljs-function">(<span class="hljs-params">title, value</span>) =></span>
H.div(<span class="hljs-string">'.row'</span>,
H.div(<span class="hljs-string">'.col'</span>,
H.strong(title),
H.unescaped(<span class="hljs-string">': '</span> + value)
<span class="hljs-comment">// If 'value' is a renderable then the concatination between ': ' and 'value' will cause </span>
<span class="hljs-comment">// 'value' to automatically render resulting in HTML (see the .toString() section). </span>
<span class="hljs-comment">// Without unescaped, the parent div would escape these HTML characters giving unexpected results.</span>
)
)
);
H.row(<span class="hljs-string">"Name"</span>, H.span(<span class="hljs-string">"John Doe"</span>)).r;</code></pre>
<p>Produces:</p>
<pre><code class="language-html"><span class="hljs-tag"><<span class="hljs-name">div</span> <span class="hljs-attr">class</span>=<span class="hljs-string">"row"</span>></span>
<span class="hljs-tag"><<span class="hljs-name">div</span> <span class="hljs-attr">class</span>=<span class="hljs-string">"col"</span>></span>
<span class="hljs-tag"><<span class="hljs-name">strong</span>></span>Name<span class="hljs-tag"></<span class="hljs-name">strong</span>></span>: <span class="hljs-tag"><<span class="hljs-name">span</span>></span>John Doe<span class="hljs-tag"></<span class="hljs-name">span</span>></span>
<span class="hljs-tag"></<span class="hljs-name">div</span>></span>
<span class="hljs-tag"></<span class="hljs-name">div</span>></span></code></pre>
<a href="#aychdestroy" id="aychdestroy" style="color: inherit; text-decoration: none;">
<h3>Aych.destroy()</h3>
</a>
<p>You can remove tags or compositions using the <code>destroy</code> method under Aych.</p>
<pre><code class="language-javascript">Aych.destroy(<span class="hljs-string">'div'</span>);
<span class="hljs-comment">// H.div().r // no longer is valid because it was removed.</span></code></pre>
<a href="#piper" id="piper" style="color: inherit; text-decoration: none;">
<h2>Piper</h2>
</a>
<p>Piper is the piping engine for Aych. Piper lives used <code>Aych.Piper</code> and allows you to register, deregister, or update
the pipes that you can use inside of string literals during templating. Pipes can take optional arguments which can
either be a string, number or boolean.</p>
<a href="#usage" id="usage" style="color: inherit; text-decoration: none;">
<h3>Usage</h3>
</a>
<p>Pipes are used within string literals to modify the data pass in. </p>
<pre><code class="language-javascript">H.string(<span class="hljs-string">"{{text|uppercase()}}"</span>).render({ <span class="hljs-attr">text</span>: <span class="hljs-string">'hello'</span> });
<span class="hljs-comment">// OR</span>
H.string(<span class="hljs-string">"{{text|uppercase}}"</span>).render({ <span class="hljs-attr">text</span>: <span class="hljs-string">'hello'</span> });
<span class="hljs-comment">// output: HELLO</span></code></pre>
<p>In the above example, the uppercase pipe takes in some text and turns it to uppercase. Using parentheses are optional
unless you want to specify parameters:</p>
<pre><code class="language-javascript">H.string(<span class="hljs-string">"{{text|substr(1, 3))}}"</span>).render({ <span class="hljs-attr">text</span>: <span class="hljs-string">'hello'</span> });
<span class="hljs-comment">// output: ell</span></code></pre>
<p>Piper does not require arguments even if you create a pipe with arguments. If you want these arguments to be required,
you will have to manually error handle the undefined arguments. See the <code>addLetter</code> example below.</p>
<a href="#register--deregister-pipe" id="register--deregister-pipe" style="color: inherit; text-decoration: none;">
<h3>Register / Deregister Pipe</h3>
</a>
<p>The way that you register a pipe is like this:</p>
<pre><code class="language-javascript">Aych.Piper.register(<span class="hljs-string">'PIPE NAME HERE'</span>, <span class="hljs-function">(<span class="hljs-params">str, optionalArg1, optionalArg2, ...</span>) =></span> {
<span class="hljs-comment">// Do something to str here.</span>
<span class="hljs-keyword">return</span> str;
});</code></pre>
<p>You can deregister a pipe using <code>Aych.Piper.deregister('PIPE NAME HERE')</code>.</p>
<p>Alternatively, if you simply want to update an existing pipe, you can use the update method. The signature used is
slightly modified. The previous pipe function will be given to you as the first argument:</p>
<pre><code class="language-javascript">Aych.Piper.update(<span class="hljs-string">'PIPE NAME HERE'</span>, <span class="hljs-function">(<span class="hljs-params">original, str, optionalArg1, optionalArg2, ...</span>) =></span> {
<span class="hljs-comment">// Do something to str here.</span>
<span class="hljs-keyword">return</span> original(str);
});</code></pre>
<p>An example with all these concepts:</p>
<pre><code class="language-javascript">Aych.Piper.register(<span class="hljs-string">'addLetter'</span>, <span class="hljs-function">(<span class="hljs-params">str, letter</span>) =></span> {
<span class="hljs-keyword">if</span> (letter === <span class="hljs-literal">undefined</span>) letter = <span class="hljs-string">'a'</span>;
<span class="hljs-keyword">return</span> str + letter;
});
H.div(<span class="hljs-string">'{{text|addLetter(!)}}'</span>).render({<span class="hljs-attr">text</span>: <span class="hljs-string">"Hello"</span>}); <span class="hljs-comment">// output: "Hello!"</span>
H.div(<span class="hljs-string">'{{text|addLetter}}'</span>).render({<span class="hljs-attr">text</span>: <span class="hljs-string">"Hello"</span>}); <span class="hljs-comment">// output: "Helloa" (missing argument uses letter 'a')</span>
Aych.Piper.update(<span class="hljs-string">'addLetter'</span>, <span class="hljs-function">(<span class="hljs-params">original, str, letter</span>) =></span> {
<span class="hljs-keyword">if</span> (letter === <span class="hljs-literal">undefined</span>) letter = <span class="hljs-string">'a'</span>;
<span class="hljs-keyword">return</span> letter + original(str, letter);
});
H.div(<span class="hljs-string">'{{text|addLetter(!)}}'</span>).render({<span class="hljs-attr">text</span>: <span class="hljs-string">"Hello"</span>}); <span class="hljs-comment">// output: "!Hello!"</span>
Aych.Piper.deregister(<span class="hljs-string">'addLetter'</span>);
<span class="hljs-comment">// Using addLetter as a pipe after this point will throw an error.</span></code></pre>
<a href="#statements" id="statements" style="color: inherit; text-decoration: none;">
<h2>Statements</h2>
</a>
<p>Statements are special renderable's that modify the way other renderables get rendered. Statements are the power that
Aych provides to write shorter code. Statements are all under the <code>H</code> variable and are all preceeded by a dollar sign
(<code>$</code>). Again, statements are renderable so they have <code>.render()</code> and <code>.r</code> methods and thus can be used as children just
like regular tags.</p>
<a href="#-scope" id="-scope" style="color: inherit; text-decoration: none;">
<h3>$ (scope)</h3>
</a>
<p>The <code>$</code> statement is called the scope statement. This statement is used to improved the readability of your Aych code
by scoping H within an anonymous function and restricting new pipes, new tags, and new creations within this anonymous
function. </p>
<pre><code class="language-javascript">H.$((H) => {
<span class="hljs-comment">// Use H here. Any new pipes, tags, or creations that are added will be removed </span>
<span class="hljs-comment">// after this anonymous function runs.</span>
<span class="hljs-keyword">return</span> H.div();
}); <span class="hljs-comment">// output: <div></div></span></code></pre>
<p>You may notice that the anonymous function injects <code>H</code> as the first parameter. While this is not required, it is
recommended to use destructuring to pull out the necessary tags or statements. You will also see that with this
statement you <code>return</code> the final element construction. <code>.r</code> is optional here as the scope statement will call it
automatically. However, if you want to include templates you need to explicitly call '.render()'</p>
<p>Full example:</p>
<pre><code class="language-javascript">H.$(({ $switch, $<span class="hljs-keyword">case</span>, input, html, body, title, head }) => {
<span class="hljs-keyword">const</span> type = <span class="hljs-string">'password'</span>;
<span class="hljs-keyword">return</span> html(
head(
title(<span class="hljs-string">'Some Title'</span>),
),
body(
$switch(type,
$<span class="hljs-keyword">case</span>(<span class="hljs-string">'text'</span>, input({ <span class="hljs-attr">type</span>: <span class="hljs-string">'text'</span> })),
$<span class="hljs-keyword">case</span>(<span class="hljs-string">'password'</span>, input({ <span class="hljs-attr">type</span>: <span class="hljs-string">'password'</span> })),
$<span class="hljs-keyword">case</span>(<span class="hljs-string">'hidden'</span>, input({ <span class="hljs-attr">type</span>: <span class="hljs-string">'hidden'</span> }))
),
)
)
});</code></pre>
<p>Produces:</p>
<pre><code class="language-html"><span class="hljs-tag"><<span class="hljs-name">html</span>></span>
<span class="hljs-tag"><<span class="hljs-name">head</span>></span>
<span class="hljs-tag"><<span class="hljs-name">title</span>></span>Some Title<span class="hljs-tag"></<span class="hljs-name">title</span>></span>
<span class="hljs-tag"></<span class="hljs-name">head</span>></span>
<span class="hljs-tag"><<span class="hljs-name">body</span>></span>
<span class="hljs-tag"><<span class="hljs-name">input</span> <span class="hljs-attr">type</span>=<span class="hljs-string">"password"</span>></span>
<span class="hljs-tag"></<span class="hljs-name">body</span>></span>
<span class="hljs-tag"></<span class="hljs-name">html</span>></span></code></pre>
<p>Again, note that no explicit render method is required. </p>
<a href="#if" id="if" style="color: inherit; text-decoration: none;">
<h3>$if</h3>
</a>
<p>Rendering HTML conditionally can prove to be extremely useful. The <code>$if</code> statement accomplishes just that.</p>
<pre><code class="language-javascript">H.$if(<span class="hljs-literal">true</span>, H.div(), H.span()).r; <span class="hljs-comment">// output: <div></div></span>
H.$if(<span class="hljs-literal">false</span>, H.div(), H.span()).r; <span class="hljs-comment">// output: <span></span></span>
H.$if(<span class="hljs-literal">false</span>, H.div()).else(H.span()).r; <span class="hljs-comment">// output: <span></span></span>
<span class="hljs-comment">// Use else if:</span>
H.$if(<span class="hljs-literal">false</span>, H.div()).elif(<span class="hljs-literal">false</span>, H.span()).elif(<span class="hljs-literal">true</span>, H.strong()).r; <span class="hljs-comment">// output: <strong></strong></span>
<span class="hljs-comment">// Nested if:</span>
H.$if(<span class="hljs-literal">true</span>,
H.$if(<span class="hljs-literal">false</span>,
H.div(),
H.span()
),
H.strong()
).r <span class="hljs-comment">// output: <span></span></span></code></pre>
<a href="#each" id="each" style="color: inherit; text-decoration: none;">
<h3>$each</h3>
</a>
<p>The <code>$each</code> statement renders a renderable for each item in a list. The <code>eachIn</code> is similar but instead works with
a key,value paired object.</p>
<p>The each statement is very powerful because it allows multiplying HTML elements based on a list.</p>
<pre><code class="language-javascript">H.$each([<span class="hljs-string">'John'</span>, <span class="hljs-string">'Jennifer'</span>, <span class="hljs-string">'Samantha'</span>], H.div(<span class="hljs-string">"{{item}} @ {{i}}"</span>)).r;
<span class="hljs-comment">// output: <div>John @ 0</div><div>Jennifer @ 1</div><div>Samantha @ 0</div></span></code></pre>
<p>As you can see, the each statement injects two special templating tags called <code>item</code> and <code>i</code> where
<code>item</code> refers to the element in the array and <code>i</code> refers to the index. You can change these names:</p>
<pre><code class="language-javascript">H.$each([<span class="hljs-string">'John'</span>, <span class="hljs-string">'Jennifer'</span>, <span class="hljs-string">'Samantha'</span>], H.div(<span class="hljs-string">"{{element}} @ {{index}}"</span>), <span class="hljs-string">'index'</span>, <span class="hljs-string">'element'</span>).r;
<span class="hljs-comment">// OR</span>
H.$each([<span class="hljs-string">'John'</span>, <span class="hljs-string">'Jennifer'</span>, <span class="hljs-string">'Samantha'</span>], H.div(<span class="hljs-string">"{{element}} @ {{index}}"</span>)).setIndexName(<span class="hljs-string">'index'</span>).setIndexName(<span class="hljs-string">'element'</span>).r;
<span class="hljs-comment">// output: <div>John @ 0</div><div>Jennifer @ 1</div><div>Samantha @ 0</div></span></code></pre>
<p>If you need more flexibility, you can use an anonymous function that returns a renderable instead of using the
renderable directly:</p>
<pre><code class="language-javascript">H.$each([<span class="hljs-string">'John'</span>, <span class="hljs-string">'Jennifer'</span>, <span class="hljs-string">'Samantha'</span>], <span class="hljs-function">(<span class="hljs-params">item, index, arr</span>) =></span> H.div(item + <span class="hljs-string">" @ {{index}}"</span>)).r;
<span class="hljs-comment">// output: <div>John @ 0</div><div>Jennifer @ 1</div><div>Samantha @ 0</div></span></code></pre>
<p>Take note that you can still use templates in this returned renderable. In fact, <code>item</code> and <code>index</code> are available,
though including both in the example is a bit redundant. The goal was to show you the signature of this anonymous
function and what it injects.</p>
<p><strong>What happens if the list is empty?</strong>
In case you want to have a special element used if the list is empty, you can chain on the <code>.empty()</code> method:</p>
<pre><code class="language-javascript">H.$each([], H.div(<span class="hljs-string">"{{item}} @ {{i}}"</span>)).empty(H.span(<span class="hljs-string">"List empty!"</span>)).r;
<span class="hljs-comment">// output: <span>List empty!</span></span></code></pre>
<a href="#eachin" id="eachin" style="color: inherit; text-decoration: none;">
<h3>$eachIn</h3>
</a>
<p>The <code>$eachIn</code> statement works similar to each in all aspects expect for the input of data. The data in an each in
statement is an key,value object.</p>
<pre><code class="language-javascript">H.$eachIn({
<span class="hljs-string">"date"</span>: <span class="hljs-string">"08/08/2020"</span>,
<span class="hljs-string">"age"</span>: <span class="hljs-number">19</span>,
}, H.div(<span class="hljs-string">"{{item[0]}}:{{item[1]}} @ {{i}}"</span>)).r;
<span class="hljs-comment">//OR</span>
H.$eachIn({
<span class="hljs-string">"date"</span>: <span class="hljs-string">"08/08/2020"</span>,
<span class="hljs-string">"age"</span>: <span class="hljs-number">19</span>,
}, <span class="hljs-function">(<span class="hljs-params">[key, value], index</span>) =></span> H.div(key + <span class="hljs-string">":"</span> + value + <span class="hljs-string">" @ "</span> + index)).r;
<span class="hljs-comment">// output: <div>date:08/08/2020 @ 0</div><div>age:19 @ 1</div></span></code></pre>
<p>Just like with the <code>$each</code> statement, you can call <code>setIndexName</code>, <code>setItemName</code>, and <code>empty</code>.</p>
<a href="#repeat" id="repeat" style="color: inherit; text-decoration: none;">
<h3>$repeat</h3>
</a>
<p>The <code>$repeat</code> statement will copy an element some number of times.</p>
<pre><code class="language-javascript">H.$repeat(<span class="hljs-number">3</span>, H.div(<span class="hljs-string">"I'm div number: {{i}}"</span>)).r;
<span class="hljs-comment">// OR:</span>
H.$repeat(<span class="hljs-number">3</span>, <span class="hljs-function">(<span class="hljs-params">i</span>) =></span> {
<span class="hljs-keyword">return</span> H.div(<span class="hljs-string">"I'm div number: "</span> + i);
}).r;
<span class="hljs-comment">// output: <div>I'm div number: 0</div><div>I'm div number: 1</div><div>I'm div number: 2</div></span></code></pre>
<a href="#group" id="group" style="color: inherit; text-decoration: none;">
<h3>$group</h3>
</a>
<p>The <code>$group</code> statement groups elements together for rendering.</p>
<p>By using a group statement, we are able to logically group a set of renderable elements. In the example below, we
compare how to use a group statement.</p>
<pre><code class="language-javascript"><span class="hljs-keyword">const</span> type = <span class="hljs-string">'password'</span>;
$group(
H.div({ <span class="hljs-attr">id</span>: [type !== <span class="hljs-string">'password'</span>, <span class="hljs-string">'someid'</span>] }, <span class="hljs-string">'{{age}}'</span>),
H.div({ <span class="hljs-attr">class</span>: [type === <span class="hljs-string">'password'</span>, <span class="hljs-string">'+password'</span>, <span class="hljs-string">'+none'</span>]}, <span class="hljs-string">'{{name}}'</span>),
H.div(<span class="hljs-string">"{{school}}"</span>)
).render({ <span class="hljs-attr">age</span>: <span class="hljs-number">19</span>, <span class="hljs-attr">name</span>: <span class="hljs-string">'John'</span>, <span class="hljs-attr">school</span>: <span class="hljs-string">'UGA'</span> });
<span class="hljs-comment">// output: <div>19</div><div class="password">John></div><div>UGA</div></span>
<span class="hljs-comment">// Equivalent to:</span>
<span class="hljs-keyword">const</span> type = <span class="hljs-string">'password'</span>;
H.div({ <span class="hljs-attr">id</span>: [type !== <span class="hljs-string">'password'</span>, <span class="hljs-string">'someid'</span>] }, <span class="hljs-string">'{{age}}'</span>).render({ <span class="hljs-attr">age</span>:<span class="hljs-number">19</span> }) +
H.div({ <span class="hljs-attr">class</span>: [type === <span class="hljs-string">'password'</span>, <span class="hljs-string">'+password'</span>, <span class="hljs-string">'+none'</span>]}, <span class="hljs-string">'{{name}}'</span>).render({ <span class="hljs-attr">name</span>:<span class="hljs-string">'John'</span> }) +
H.div(<span class="hljs-string">"{{school}}"</span>).render({ <span class="hljs-attr">school</span>: <span class="hljs-string">'UGA'</span> });</code></pre>
<p>As you can see, in the alternative, when not using a group statement, you have repeated render calls and you have to
concat the strings together.</p>
<a href="#switch--case" id="switch--case" style="color: inherit; text-decoration: none;">
<h3>$switch / $case</h3>
</a>
<p>The <code>$switch</code> statement allows you to toggle between a set of elements based on some input. This statement is used with
the <code>$case</code> statement.</p>
<pre><code class="language-javascript"><span class="hljs-keyword">const</span> value = <span class="hljs-number">3</span>;
H.$switch(value,
H.$<span class="hljs-keyword">case</span>(<span class="hljs-number">0</span>, H.div()),
H.$<span class="hljs-keyword">case</span>(<span class="hljs-number">1</span>, H.span()),
H.$<span class="hljs-keyword">case</span>(<span class="hljs-number">2</span>, H.strong()),
H.$<span class="hljs-keyword">case</span>(<span class="hljs-number">3</span>, H.h1()),
).r; <span class="hljs-comment">// output: <h1></h1></span></code></pre>
<p>Just like switch statements in JavaScript, our <code>$switch</code> statements also support a default in case when none of the
cases are met:</p>
<pre><code class="language-javascript"><span class="hljs-keyword">const</span> value = <span class="hljs-string">"dog"</span>;
H.$switch(value,
H.$<span class="hljs-keyword">case</span>(<span class="hljs-string">"cat"</span>, H.div()),
H.$<span class="hljs-keyword">case</span>(<span class="hljs-string">"tiger"</span>, H.span()),
H.$<span class="hljs-keyword">case</span>(<span class="hljs-string">"bear"</span>, H.strong()),
H.$<span class="hljs-keyword">case</span>(<span class="hljs-string">"mouse"</span>, H.h1()),
).default(H.h2()).r; <span class="hljs-comment">// output: <h2></h2></span></code></pre>
<a href="#more-examples" id="more-examples" style="color: inherit; text-decoration: none;">
<h2>More examples</h2>
</a>
<p>The tests/ folder in the github is a great place to explore test cases and uses. You will likely find
<code>intergration.ts</code> and <code>h.test.ts</code> the most interesting as they use the library directly. The subfolders
will contain more internal testing but also serve as valuable example.</p>
</div>
<!--{"options":"typedoc.json","tsconfig":"/Users/shawnholman/Desktop/Aych","inputFiles":["./src"],"mode":1,"includeDeclarations":false,"entryPoint":"","exclude":[],"externalPattern":[],"excludeExternals":true,"excludeNotExported":true,"excludeNotDocumented":false,"excludePrivate":true,"excludeProtected":false,"ignoreCompilerErrors":false,"disableSources":false,"includes":"","media":"","out":"./docs","json":"","theme":"node_modules/typedoc-neo-theme/bin/default","name":"Aych","includeVersion":false,"excludeTags":[],"readme":"DOCUMENTATION.md","defaultCategory":"Other","categoryOrder":[],"categorizeByGroup":true,"gitRevision":"","gitRemote":"origin","gaID":"","gaSite":"auto","hideGenerator":false,"toc":[],"disableOutputCheck":false,"help":false,"version":false,"plugin":["typedoc-neo-theme"],"logger":"console","listInvalidSymbolLinks":false,"outline":[{"Library":{"H":"_h_","Aych":"classes/_core_aych_.aych"},"Core":{"Piper":"classes/_core_piper_.piper","Renderable":"classes/_core_renderable_.renderable","StringLiteral":"classes/_core_stringliteral_.stringliteral"},"Elements":{"Element":"classes/_elements_element_.element","EmptyElement":"classes/_elements_emptyelement_.emptyelement","NestableElement":"classes/_elements_nestableelement_.nestableelement"},"Interfaces":{"Attributes":"interfaces/_interfaces_attributes_.attributes","RenderOptions":"interfaces/_interfaces_render_options_.renderoptions","SimpleObject":"interfaces/_interfaces_simple_object_.simpleobject"},"Structural":{"Each":"classes/_structural_each_.each","If":"classes/_structural_if_.if","Switch":"classes/_structural_switch_.switch","Group":"classes/_structural_group_.group"}}]}-->
</div>
<div class="col-2 col-menu secondary-menu">
<nav class="tsd-navigation secondary menu-sticky">
<ul class="before-current">
</ul>
</nav>
</div>
</div>
</div>
<footer class="with-border-bottom">
</footer>
<div class="container tsd-generator">
<p>Generated using <a href="http://typedoc.org/" target="_blank">TypeDoc</a></p>
</div>
<div class="overlay"></div>
<script src="assets/js/main.js"></script>
<script>if (location.protocol == 'file:') document.write('<script src="assets/js/search.js"><' + '/script>');</script>
</body>
</html>