Getting started is easy. There is no JavaScript stack to set up, no boilerplate/scaffolding, and
no build tools to download and run.
Just add one script tag to the top of your page or template:
<script src="https://cdn.hibikihtml.com/hibiki/v0.3.2/hibiki-prod.min.js"></script>
Wrap any portion of your content with a <template hibiki> tag and you have your first
Hibiki HTML app. All plain HTML content is rendered as is, and because Hibiki HTML uses the browser's HTML parser,
it follows the same rules as standard browser HTML.
Note that all these code examples can be viewed and edited in the
Hibiki HTML Playground.
<template hibiki>
<h1 class="title">🌸 Hibiki HTML</h1>
<p>Hibiki HTML <i>is</i> HTML</p>
</template>
(Playground Link - https://playground.hibikihtml.com/?codeid=readme-gs)
Hibiki HTML applications have a built-in frontend data model. You can initialize it with
any JSON object using the <hibiki-data> tag. To render text use
the <h-text> tag or inline {{ ... }} syntax. Attributes and style properties
are evaluated dynamically if they start with a *.
<template hibiki>
<hibiki-data>
{"color": "blue", "name": "Mike"}
</hibiki-data>
<p>
{{ $.name }}'s favorite color is
<span style="font-weight: bold; color: *$.color">{{ $.color }}</span>
</p>
</template>
(Playground Link - https://playground.hibikihtml.com/?codeid=readme-data-1)
Hibiki HTML supports a full expression language, including all of the standard conditional and arithmetic
operators. Additional classes can be turned on/off using the shorthand
attribute syntax class.[class-name]="true/false expression".
<template hibiki>
<hibiki-data>
{"numlights": 4, "selected": true, "index": 5, "isprimary": true}
</hibiki-data>
<div class="box" style="font-weight: *($.selected ? 'bold' : 'normal')">
Bold Text (if selected)
</div>
<div class="box">Index: <h-text bind="$.index + 1"></h-text></div>
<div class="box">
There are {{$.numlights}} light{{$.numlights > 1 ? 's' : ''}}
</div>
<div class="box">
<button class="button" class.is-primary="*$.isprimary">Primary Button</button>
</div>
</template>
(Playground Link - https://playground.hibikihtml.com/?codeid=readme-data-2)
You can conditionally include elements using the if attribute. Looping
is handled by the foreach attribute. You can loop over arrays or
objects. The foreach attribute uses a special syntax of @item in $.array,
where every iteration @item will be assigned to an element of the array or object.
If you provide a second variable it will capture the array index or element key:
(@item, @key) in $.object or (@item, @idx) in $.array.
<template hibiki>
<hibiki-data>
{"fruits": [{"name": "apple", "emoji": "🍎"},
{"name": "banana", "emoji": "🍌"},
{"name": "blueberry", "emoji": "🫐"}],
"selected": "banana"}
</hibiki-data>
<div class="content box">
<ul>
<li foreach="@fruit in $.fruits">
{{ @fruit.name }} {{ @fruit.emoji }}
<span if="@fruit.name == $.selected">(selected)</span>
</li>
</ul>
</div>
</template>
(Playground Link - https://playground.hibikihtml.com/?codeid=readme-data-3)
To update data (and dynamically change content), Hibiki HTML supports handlers. Basic handlers respond to
events like click, mount, submit, change, etc.
<template hibiki>
<hibiki-data>{"color": "blue"}</hibiki-data>
<div class="box" style="background-color: *$.color; color: white">
The color is {{$.color}}
</div>
<button class="button" click.handler="$.color = 'green'">Change Color</button>
</template>
(Playground Link - https://playground.hibikihtml.com/?codeid=readme-handlers-1)
You can make remote AJAX calls for JSON data using a remote handler. In this example
the call to https://testapi.hibikihtml.com/api/get-color-1 will return the JSON
response {"color": "purple"}. We assign it to a context variable @resp and
then assign $.color = @resp.color.
<template hibiki>
<hibiki-data>{"color": "blue"}</hibiki-data>
<div class="box" style="background-color: *$.color; color: white">
The color is {{$.color}}
</div>
<button class="button" click.handler="$.color = 'green'">Change Color</button>
<button class="button"
click.handler="@resp = GET https://testapi.hibikihtml.com/api/get-color-1; $.color = @resp.color;">
GET /api/get-color-1
</button>
</template>
(Playground Link - https://playground.hibikihtml.com/?codeid=readme-handlers-2)
You can make GET, POST, PUT, PATCH, or DELETE requests by changing the verb in front of the URL. You can
pass query arguments (or JSON data bodies) by passing arguments to your handler by using (arg1=val1, arg2=val2...) (complex arguments will be JSON encoded), and you can define local handlers using the define-handler tag for convenience and reuse.
<template hibiki>
<hibiki-data>{"color": "blue"}</hibiki-data>
<define-handler name="//@local/get-color">
@resp = GET https://testapi.hibikihtml.com/api/get-color-1(name="Michelle");
$.color = @resp.color;
</define-handler>
<div class="box" style="background-color: *$.color; color: white">
The color is {{$.color}}
</div>
<button class="button" click.handler="$.color = 'green'">Change Color</button>
<button class="button" click.handler="//@local/get-color">
Get Michelle's Color
</button>
</template>
(Playground Link - https://playground.hibikihtml.com/?codeid=readme-handlers-3)
Connecting to an existing API? Don't worry, Hibiki HTML handlers support advanced options
like CORS, CSRF, parameter encodings, BLOB results, and multipart file uploads.
The magic of Hibiki HTML is that every handler is really just a series of actions. Hibiki Actions
are primitives like setdata, if, callhandler, fireevent, invalidate, html, etc. Every action
that can you can write in a handler, also has a JSON representation.
This means we can write a backend handler that returns a JSON response that scripts
and updates the frontend! Here's an example JSON response that is equivalent to running
$.color = 'DeepSkyBlue' on the frontend:
{"hibikiactions": [
{"actiontype": "setdata", "setpath": "$.color", "data": "DeepSkyBlue"}
]}
I've set up https://testapi.hibikihtml.com/api/set-color-action to return just that. Now
if we have our click handler call that URL, we'll see the color change automatically.
<template hibiki>
<hibiki-data>{"color": "red"}</hibiki-data>
<div class="box" style="background-color: *$.color; color: white">
The color is {{$.color}}
</div>
<button class="button" click.handler="$.color = 'green'">Change Color</button>
<button class="button" click.handler="GET https://testapi.hibikihtml.com/api/set-color-action;">
Backend Set Color Action
</button>
</template>
(Playground Link - https://playground.hibikihtml.com/?codeid=readme-actions-1)
Backend handlers are very powerful. You can set return values, return data and BLOBs (like images) in
one request, mix frontend and backend data with expressions, conditionally execute actions, and more.
You can also use backend handlers to create multi-page Hibiki HTML applications by returning a
new HTML template to be rendered.
Hibiki HTML makes it easy to use, share, and bundle components for easy reuse. The ecosystem is just getting
started, but you can write native Hibiki HTML components, link to 3rd party JavaScript (D3, CodeMirror, etc.),
and import ReactJS components.
<template hibiki>
<define-component name="colorbox">
<div class="box" style="background-color: *$args.color; color: white">
The color is {{$args.color}}
</div>
</define-component>
<local-colorbox color="green"></local-colorbox>
<local-colorbox color="blue"></local-colorbox>
<local-colorbox color="purple"></local-colorbox>
</template>
(Playground Link - https://playground.hibikihtml.com/?codeid=readme-comps-1)
Last modified 16 December 2024