Hawkejs syntax

Next to EJS, Hawkejs also supports a custom syntax. For this, it uses the {% %} delimiter

Statements

Printing

There are 2 ways of printing text.

Safe-printing

The first (and preferred) method is "safe-printing" using {{ some_variable }}. This will automatically encode any HTML entities, preventing potential cross-site scripting (XSS) vulnerabilities by sanitizing the output.

Unsafe-printing

The second method can be used like this: {%= some_variable %}. This will parse the contents of the string as if it were plain HTML and add it to the DOM.

Warning: Use this method cautiously as it directly injects HTML, potentially exposing your application to XSS attacks.

If

Every syntax requires an If keyword. Ours does not look fundamentally different from JavaScript's:

        {% if my_variable %}
            Print this text if `my_variable` is truthy
        {% /if %}

However, it treats values slightly differently. Objects and arrays that have no key/values are considered falsy.

Truthy Values:

  • Non-empty strings
  • True booleans
  • Non-zero numbers
  • Non-empty arrays
  • Non-empty objects

Falsy Values:

  • Empty strings
  • False booleans
  • Zero numbers
  • Empty arrays
  • Empty objects

Each

Iterating over items can be done with the each keyword:

        {% each items as key, val %}
            {{ key }}: {{ val }}
        {% /each %}

With

The with statement is used to work with arrays and objects, allowing you to define different behavior based on the content of the variable.

Inside the with block, you can use the following branches. (These can be put in any order and repeated as many time as you want)

  • none: Branch that is executed if the context variable is empty
  • all: Branch that is executed if the context variable is NOT empty
  • single: Branch that is executed if the context variable contains only 1 element
  • multiple: Branch that is executed if the context variable contains more than 1 element
  • each: This is the actual iteration branch: it will be repeated for every element in the array/object
        {% with my_array as entry %}
            This text will be printed only once.
            
            {% none %}
                This text will be printed if `my_array` is empty
            {% /none %}
            
            {% all %}
                This text will be printed if `my_array` is NOT empty
            {% /all %}
            
            {% single %}
                This text will be printed if `my_array` contains only 1 element
            {% /single %}
            
            {% multiple %}
                This text will be printed if `my_array` contains more than 1 element
            {% /multiple %}
            
            {% each %}
                This text will be repeatedly be printed for each element in the `my_array` variable.
                The value can be reached with the {%= entry %} variable
            {% /each %}
            
        {% /with %}

Reactivity / Binding

Hawkejs supports reactive variables, meaning changing the value of the variable will trigger some kind of change to your document. You have to use the special suffix {:} to indicate you want to make it reactive in that place. The values also have to be an instance of the Develry.ObservableValue class.

Then the final requirement: the way reactivity is handled is per DOM element.

    <div>
        {% if my_value{:} %}
            Truthy!
        {% else %}
            Falsy!
        {% /if %}
    </div>

When the value of my_value changes, the contents of the <div> it is in will be re-rendered. Hawkejs directly uses DOM elements, it does not use a Virtual DOM with diffing, so in this case the entire content of the <div> will be re-rendered & replaced.

It is also possible to bind to a value inside of a path, like this:

    <div>
        {% if holder.child{:}.my_value %}
            Truthy!
        {% else %}
            Falsy!
        {% /if %}
    </div>

This means that whenever the value of holder.child changes, the <div> will get re-rendered. Warning: it does not look for changes made to its value. So if holder.child is an object, and you change that object in some way, no change will be triggered.

Expressions

An expression is any valid set of literals, variables, operators, and expressions that evaluates to a single value.

Here are the operators you can use in expressions, used in if statements as example:

Operators

Not

We can negate something by using the `not` keyword:

        {% if not my_variable %}
            Print this text if `my_variable` is falsy
        {% /if %}

Or

        {% if my_variable or other_variable %}
            Print this text if `my_variable` or `other_variable` is truthy
        {% /if %}

And

        {% if my_variable and other_variable %}
            Print this text if `my_variable` and `other_variable` is truthy
        {% /if %}

Eq

        {% if my_variable eq "something" %}
            Print this text if `my_variable` equals "something"
        {% /if %}

Neq

        {% if my_variable neq "something" %}
            Print this text if `my_variable` is not equal to "something"
        {% /if %}

Gt

        {% if my_variable gt 1 %}
            Print this text if `my_variable` is greater than 1
        {% /if %}

Ge

        {% if my_variable ge 1 %}
            Print this text if `my_variable` is greater than or equal to 1
        {% /if %}

Lt

        {% if my_variable lt 1 %}
            Print this text if `my_variable` is greater than 1
        {% /if %}

Le

        {% if my_variable le 1 %}
            Print this text if `my_variable` is greater than or equal to 1
        {% /if %}

Starts with

        {% if my_variable starts with "prefix" %}
            Print this text if `my_variable` starts with the string "prefix"
        {% /if %}

Ends with

        {% if my_variable ends with "suffix" %}
            Print this text if `my_variable` ends with the string "suffix"
        {% /if %}

Empty

        {% if my_variable empty %}
            Print this text if `my_variable` is empty
        {% /if %}

Empty in this case would be:

  • An empty string
  • A string containing only whitespaces
  • An empty array
  • An empty object
  • Any falsy values (0, null, undefined, false)

Conditional ternary operator

The conditional ternary operator is also supported since v2.4.0:

{{ some_value ? 'Exists!' : 'Falsy?' }}

HTML

Hawkejs templates have to be written in valid HTML syntax, it's a bit like JSX in that way as it gets compiled into function calls. There are several special directives you can use:

Hawkejs expressions as attribute values

Any vanilla HTML is valid Hawkejs syntax:

    <div data-my-attribute="string"></div>

But you can also use expressions here. The important difference with other engines like Vue is that you should not wrap these expressions in quotes, unless you want to cast it to a string. So for example <input value={% my_value %}> will be executed like input.setAttribute('value', my_value), without casting it as a string. But doing <input value="{% my_value %}"> will be more like input.setAttribute('value', ''+my_value)

This isn't a big deal for regular, vanilla attributes, as they're always cast to strings eventually. But for other directives this might be a big deal.

By the way: anything between quotes will be concatenated. You can even mix and match:

    <div class="first-class {% var_one %} {% var_two %} {% conditional ? 'active' : '' %}"></div>

The prop: directive

If you want to directly set a property of an HTML element instance, you can do so with prop:

    <div
        prop:hidden={% true %}
    ></div>

This basically compiles into div.hidden = true

The var: directive

You can define a variable limited to the scope of that element directly. This is especially useful for custom elements:

    <my-custom-element
        var:my_title="title"
    ></my-custom-element>

Then you can use this variable in the template of the custom element:

This is the template of my-custom-element.
I can print my_title like so: {{ my_title }}

The state: directive

Custom elements can have predefined state values. Whatever value you set it to, it will always be stored in an Develry.ObservableOptional class.

    <my-custom-element
        state:my_title="title"
    ></my-custom-element>

The template can actually stay pretty much the same as the previous var: example. You just have to know that state: values always take precedence. But let's add some reactive binding to it this time:

<div>
    This is the template of my-custom-element.
    I can print my_title like so: {{ my_title{:} }}</div>

Now we can actually programatically change this state using javascript:

let my_custom_element = document.querySelector('my-custom-element');
my_custom_element.setState('my_title', 'A different title');

And this will now trigger a re-render.

The on: directive

You can set event handlers directly in your templates:

    <button
        on:click={% doSomething() %}
    >
        Do something!
    </button>

Deprecated directive symbols

Before v2.4.0, these directives had to be used with a symbol. It is technically still supported, but you should make the switch to the named versions as it is more readable.

  • <div prop:hidden={% true %}> used to be written with a # sign like: <div #hidden={%true %}>
  • <div var:foo="bar"> used to be written with a + sign like: <div +foo="bar">
  • <div on:click={% self.someExpression() %}> used to be written with just the : sign, but this is no longer supported