HTML Syntax Proposal

Overview

The goal of this change is to move from a javascript container type of file to an html one. Implementing this change will give us most of the syntax highlighting for free in all standard IDEs.

From this:

var Class = require("hsp/klass");

var HelloCtrl = Class({
    attributes: {
        name: { type: "string" }
    }
});

{export template hello using ctrl:HelloCtrl}
    <h1>Hello {ctrl.name}!</h1>
{/template}

to this:

<script>
var Class = require("hsp/klass");

var HelloCtrl = Class({
    attributes: {
        name: { type: "string" }
    }
});
</script>

<template id="hello" ctrl="HelloCtrl as ctrl" export>
    <h1>Hello {ctrl.name}!</h1>
</template>

File extension

it is just a proposal, then people are free to do whatever they want in terms of extensions, as all our tools (gulp, noder) allow them to use user-defined ones

We suggest to introduce this double extension .hsp.html when dealing with source code. Then as soon as the template get compiled, we then will create an .hsp.js file.

Allowed tags

For now, only these tags would be accepted as root tags

• <script>
• <template>
• <!-- comment --> single line comment and multi-lines comment
• any whitespaces / EOL to separate blocks

Use cases

Here is the list of different use-cases we need to handle

Prerequisite

For consistency, and code readability, let's enforce that template id is mandatory.

Template, no arguments

<!-- file: foo.hsp.html -->
<template id="foo">
</template>

Template with one argument

<!-- file: foo.hsp.html -->
<template id="foo" args="name">
</template>

Template with multiple arguments

<!-- file: foo.hsp.html -->
<template id="foo" args="name,age">
</template>

For clarity and ease of readability we can allow whitespaces to separate arguments.

<!-- file: foo.hsp.html -->
<template id="foo" args="name, age, weight">
</template>

Template with a controller

<!-- file: myctrl.hsp.html -->
<script>
var MyCtrlClass = require("./MyCtrl.js");
</script>

<template id="myctrl" ctrl="MyCtrlClass as ctrl">
</template>

Exporting a template with an implicit naming reference

<!-- file: foo.hsp.html -->
<template id="foo" export>
</template>

This template will be exported as foo. To use it elsewhere you would write that

<!-- file: bar.hsp.html -->
<script>
var myfoo = require("./foo.hsp").foo
</script>

Exporting a template with an explicit naming reference

<!-- file: foo.hsp.html -->
<template id="foo" export="bar">
</template>

This template will be exported as bar. To use it elsewhere you would write that

<!-- file: baz.hsp.html -->
<script>
var mybar = require("./foo.hsp").bar
</script>

Exporting a template as the whole module

<!-- file: foo.hsp.html -->
<template id="foo" export-module>
</template>

This file will export the template foo as the module itself. Usage could be:

<!-- file: baz.hsp.html -->
<script>
var foo = require("./foo.hsp"); //template function ready to use;
</script>

Multiline template statement

It should be possible to have multiline template statement:

<template id="foo"
    args="a,b,c">
</template>

Error reporting

Hashspace compiler should be able to handle several use-cases where errors should be thrown.

Unsupported html tag

<!-- file: foo.hsp.html -->
<script>

</script>

<div>This is unsupported</div>

<template id="foo" export-module>
</template>

foo.hsp.hml(6,1) Unsupported HTML 'div' tag. Only <script> and <template> can be used.

Invalid component / arguments syntax

<!-- file: foo.hsp.html -->
<!-- component class 'MyCtrl' reference or definition should go here -->
<template id="foo" ctrl="MyCtrl as ctrl" args="name, age">
</template>

foo.hsp.hml(3,42) Invalid template 'foo' definition. You can not use 'args' attribute when using a controller.

Invalid argument syntax

<!-- file: foo.hsp.html -->
<template id="foo" args="[name, age]">
</template>

foo.hsp.hml(2,26) Invalid arguments syntax. '[' can not be used to declare arguments. Use only ',' as a separator.

Invalid literal argument syntax

<!-- file: foo.hsp.html -->
<template id="foo" args="3, age">
</template>

foo.hsp.hml(2,26) Invalid argument reference '3'. The reference has to be a valid name.

Missing template name

<!-- file: foo.hsp.html -->
<template args="name, age">
</template>

foo.hsp.hml(2,1) Missing template name '<template args="name, age">'.

---

<!-- file: foo.hsp.html -->
<template export="foo">
</template>

foo.hsp.hml(2,1) Missing template name '<template export="foo">'.

Invalid script type

<!-- file: foo.hsp.html -->
<script type="whatever/type">
</script>

foo.hsp.hml(2,15) Invalid script type 'type="whatever/type"'. 'type' attribute is not mandatory, and only 'text/javascript' is allowed here.

Export conflicts, global vs local

<!-- file: foo.hsp.html -->
<template id="foo" export-module>
</template>

<template id="bar" export>
</template>

foo.hsp.hml(5,20) Incompatible export usage '<template id="bar" export>', your file already export a template as the module line 2 '<template id="foo" export-module>'

Export conflicts, global vs local

<!-- file: foo.hsp.html -->
<template id="bar" export>
</template>

<template id="foo" export="bar">
</template>

foo.hsp.hml(5,28) Already defined export name "bar" at line 2.

Export conflicts, multiple global

<!-- file: foo.hsp.html -->
<template id="foo" export-module>
</template>

<template id="bar" export-module>
</template>

foo.hsp.hml(5,20) Module export error. "export-module" can only be used one time per file.