Constructible HTML Specification

The Constructible HTML specification aims to define as little as possible by reusing as much as possible from the existing HTML spec, and to promote the complete decentralization of parts.

UUID

Each Constructible HTML file must have a UUID to enable decentralized identification and management. Most Web resources are identified by a URL. A URL is a location-specific identifier, while a UUID is not. The following is an example of how you declare the UUID of a given Constructible HTML.

<meta name="uuid" 
      content="8ec39eeadd9442cfa238af3b4b1c2dc8" />

A UUID can be generated with tools such as this. We recommend that you remove the hyphens, as they are not actually part of the UUID. For convenience, you can simply download a new constructible HTML file from our Website. Each new download will be have a new UUID.

There must be exactly one <meta> tag with the name uuid in any given Constructible HTML.

Inputs

Each Constructible HTML file can have zero or more inputs. The following is an example of how you declare a single input.

<meta name="inputs" 
      content="trigger_in" />

The following is an example of how you declare two input. You basically use a comma to separate each input.

<meta name="inputs" 
      content="trigger_in, content_in" />

There is also a special input known as __power__. By declaring this input, you express an interest in knowing when the HTML is powered and ready to start. As soon as it is, the time stamp of that moment is sent through this input. If this input is connected to an enclosed part, the part will receive this time. The following is an example of how you would declare this special input in addition to the two inputs previously defined.

<meta name="inputs" 
      content="trigger_in, content_in, __power__" />

It is recommended that you choose the name of your input in such a way that they meaningfully express what is meant to come through given the context of the HTML. For example, trigger_in denotes that a trigger of some kind will come in through this input.

There must be at most one <meta> tag with the name inputs in any given Constructible HTML.

Outputs

Each Constructible HTML file can have zero or more output. The following is an example of how you declare a single output.

<meta name="outputs" 
      content="content_out" />

The following is an example of how you declare two outputs. You basically use a comma to separate each output.

<meta name="outputs" 
      content="content_out, trigger_out" />

It is recommended that you choose the name of your output in such a way that they meaningfully express what is meant to exit through given the context of the HTML. For example, trigger_out denotes that a trigger of some sort will come out through this output.

There must be at most one <meta> tag with the name outputs in any given Constructible HTML.

Parts

Each Constructible HTML file can have zero or more parts. The following is an example of how you use a part in your HTML. You can simply add another pair of div tags to add more parts.

<div id="timer"
     spec="1ab7ddeea4bd428996c746cea52fae82">
</div>

The id is your choice. However, it must be unique within the HTML page. The spec attribute specifies the UUID of the Javascript part you would like to use.

There must be exactly one id and one spec attribute for any given div tag. The UUID must match what is found in the packaging of the Javascript.

If you would like to customize the part using its properties, you add the properties attribute. Here is an example of setting one of the available properties.

<div id="timer"
     spec="1ab7ddeea4bd428996c746cea52fae82"
     properties="triggers_in_milliseconds:1000">
</div>
      

The following is an example of how you set two properties. You basically use a comma to separate each property.

<div id="timer"
     spec="1ab7ddeea4bd428996c746cea52fae82"
     properties="triggers_in_milliseconds:1000
	        ,does_trigger_automatically:true">
</div>

There must be at most one properties attribute for any given div tag. The name of each property must match what is found in the packaging of the Javascript.

You may also specify a script attribute to dynamically load a javascript file in case the specification denoted by the spec attribute cannot be found in memory. If the javascript part is found in memory, the script tag will be ignored. However, instead of depending on such dynamic loading of javascript, it is recommended that you bundle up all javascript files into one big javascript file to minimize overhead.

<div id="timer"
     spec="1ab7ddeea4bd428996c746cea52fae82"
     properties="triggers_in_milliseconds:1000
	        ,does_trigger_automatically:true"
     script="https://js.constructibl.es/specs/Timer.js"
</div>

There must be at most one script attribute for any given div tag.

Some parts are meant to act as a proxy to a remote service. (The part will tell you that it is, if you try to use it without treating it as such.) Proxy parts require an additional property is_proxy set to true. It also requires an enclosed a tag whose rel attribute is set to rpc, and href attribute is set to the address to which it is proxying to. The following is an example use of the Flickr Photo Server.

<div id="flickr_photo_api1"
     spec="1B056AD26838491696D0380AA80CA085"
     is_proxy="true"
     properties="uses_api_key:'7649c72ff120a2d7da9c99a04788f964'"
     script="https://js.constructibl.es/specs/FlickrPhotoServer.js">
 <a rel="rpc" href="https://api.flickr.com/services/rest/"></a>
</div>

There must be at most one is_proxy attribute for any given div tag. If one is present, it must be set to true, and must enclose exactly one a tag whose rel attribute is set to rpc, and whose href attribute is set to the address to which it is proxying to.

Assembly

Each Constructible HTML file can have zero or more pairs of connections. These connections assemble the parts enclosed within, and allow them to send messages to one another. The following is an example of how you declare a single pair of connection. The first item is the id of the part as denoted in the div, the second is the name of the input as defined in its specification.

<meta name="connections" 
      content="{ from: ['trigger', 'trigger_out'] 
               ,   to: ['alert_box', 'trigger_in']}" />

The following is an example of how you declare two pairs of connections. You basically use a comma to separate each pair.

<meta name="connections" 
      content="{ from: ['trigger', 'trigger_out'] 
               ,   to: ['alert_box', 'trigger_in']}
              ,{ from: ['emitter', 'emission_out']
               ,   to: ['text_slots', 'content_in']}" />

The following is an example of how you declare a pair of connections between the HTML and the enclosed parts in addition to the connections made previoulsy. You basically use the self keyword.

<meta name="connections" 
      content="{ from: ['trigger', 'trigger_out'] 
               ,   to: ['alert_box', 'trigger_in']}
              ,{ from: ['emitter', 'emissions_out']
               ,   to: ['text_slots', 'content_in']
              ,{ from: [self, '__power__']
               ,   to: ['trigger', 'trigger_in']}" />

There can be more than one meta tag with the name connections in any given Constructible HTML. This may be helpful when keeping your sanity intact by dividing connections into meaningful groups.

uKernel

To load, run, and route messages among the parts, there exists a uKernel known as Star. We will work to elliminate the need to manually include and boot the uKernel inside each Constructible HTML file. Until that becomes the reality, we must include the following two lines at the end of all Constructible HTML file before we close the body tag.

 <script src="https://constructibl.es/_j/kernel/1.0.0.jgz"></script>
 <script>__star.boot();</script>
</body>

Weighing in at 6.8KB, the download overhead should be minimal.

There also exists a version of Star meant for debugging. The following example shows the reference to that version instead.

 <script src="https://constructibl.es/_j/kernel/1.0.0.debug.jgz">
 </script>
 <script>__star.boot();</script>
</body>

The manual inclusion and booting of the uKernel inside a Constructible HTML is not part of the specification. It exist as a temporary means to make things work. One can easily imagine a future where the uKernel is embedded as part of the Web Browser, and gets invoked automatically.

Please visit the gallery for complete examples.

Questions about the spec? Tell us about it below!

Download