Thursday, February 15, 2018

HTML5 Views and Forms

HTML5 is now available in Mote :)

Given it's a new feature, and an imported one at that (from Sift), there will likely be some kinks to iron out. This post will change over time, so do come back to check for updates, from time to time.

Things to consider:

  • In order to display HTML5 forms and views, you have to be logged into Sandstorm, and the session host should be subscribed to the full-feature plan.
  • To differentiate HTML5 code from older HTML versions, you must declare the document type at the top i.e. <DOCTYPE html>, which keeps to actual standards for HTML5. 

    If this is not present during runtime, the HTML content will be evaluated using the old HTML standard (3.2)
  • There is no in-form expression evaluation.

    Third I is an independent component and we have no intentions or plans to mimic MT/Mote-style Frames and Dialogs, where script is interspersed within HTML. 

    Contemporary standards for HTML advocate a separation of concerns, and our HTML5 feature provides means to accomplish dynamism, without the need for such expression evaluation.
  • Due to security considerations, Javascript cannot be referenced (i.e. <script src>), either locally, in-app, or externally.

    We are creating a white list where users submit useful and safe "libraries" for evaluation. If they pass muster, users can then reference them for their HTML5 content.

    Scripts bound within the script tag (<script>code</script>), will be allowed evaluation, as well as scripts referenced from library tokens.

2 Ways to Display HTML5

  • Directly from a Macro Button - Starting in version 1.14, users can directly launch HTML frames and dialogs, without using scripts. This works for the current HTML feature, as well. You can do this by:
    1. Create a macro button
    2. Enter HTML content. Again, remember to have the document type stated at the very top (<DOCTYPE html>).
    3. Hit F5, or click the 1st button on the macro editor toolbar, to open the Macro Properties panel
    4. Change the Content Type to HTML
    5. This will enable a couple of controls specific to HTML content.
      • Associate CSS - a convenience functionality to associate a macro containing (usually monolithic) CSS, instead of doing it via the usual link tag. In order to be included in this dropdown list, macros containing CSS must gave its content type set to "Cascading Style Sheet"

        For HTML5, all CSS references are collated for use, this includes CSS associated via this control, and CSS content referenced through link tags.
      • HTML Properties - The items in here are self-explanatory, but let's go over them briefly:
        • Width and Height - these values are for the containing window for the HTML form/view, and not for the actual HTML content. You will still have to define such values, in either the HTML content, or any associated CSS.
        • Transparent - HTML5 only. This affects the actual HTML5 form/view. Used mainly for visual effect.
        • Modal - parlance for a "blocking" window. What it does is limit input to the dialog only, preventing interaction with other components of the app's UI.

          Unfortunately, we missed committing the toggle that tells the app whether or not this macro launches a frame or dialog (sorry, we'll get it in on the next release!).
      • User Data - HTML5 only. This is a convenience control to pass data into the HTML form/view.

        Acceptable types of data are strings, numbers, and JSON objects or arrays.

        You can reference this passed data via the reserved variable window.args. Depending on what you passed, you can access its contents just like you would with any other Javascript entity e.g. window.args[0] (JSON array), window.args.key (JSON object), or just window.data (if what was passed was a "primitive" value i.e. number, string).
  • Window API: All the functionality present in macro buttons, are available via window.new(). This includes passing user data and HTML window properties.

    Furthermore, macro.create (known as createMacro in MT) was also expanded to reflect these new additions. Please review code completion, to know more about the changes to these functions. We will update this post further, as this feature matures.

Special Referencing

The following are similar to existing "internal" referencing. Note, these do not pass through the MScript parser (i.e This is not  in-form expression evaluation.):

For script tags (<script src=source>

  • macro@lib:token
  • macro@this - references the token where the running macro is located. In place of this, you can just do macro without the "@this".


For image tags (<img src=source>)
  • this - this gets the image of the token this macro is located on.
  • token.imageId - same as above
  • asset:// protocol - an internal protocol that fetches from the host or image asset cache 
  • image tokens (i.e. tokens named with the prefix "image:" e.g. image:token) - fetches the image of the referenced token.
For link tags  referencing CSS (<link rel="stylesheet" href=source>)

  • <css_macro_id>@this queries the token where this macro is located for the css macro referred to.
  • <css_macro_id>@macro.location() - same as above
  • Directly referencing library tokens e.g. <css_macro_id>@lib:token

The Window Host object

The Host object is a child of the Window object that holds several functions that serve as intermediaries between the HTML5 view and the Mote's underlying Java code. Current functions usable in form Javascript are:
  • window.host.reload() - triggers a page reload
  • window.host.update(html) - updates the view with the passed HTML.
  • wnidow.host.close() - closes the parent window (frame or dialog)

Passing data to the HTML5 view

As mentioned above, data can be passed as window.args, to be used in the HTML view.

Passing data back to the executing macro

When you want to return data back to the executing macro (when modal dialogs are used), or just to Mote, where it exists as data bound to the originating window, you pass it back via window.data.set(value). The usual acceptable data types can be passed i.e. string, numbers, JSON.

In macros, you can then reference this data by using the window.data() function. You can find more information on its usage, by consulting code-completion.

Submitting Form Data

When you want to submit a form, using <input type="submit">, won't do anything. Instead, use <button> tag (or the older <input type="button">), and set its onclick event to process the form's data and return it to the macro execution context.

Every user-created HTML5 window has a Return object, which you is used to send data back, via its set member method. Supported data types are numbers, strings, and JSON arrays or objects.

Here's some pseudo code that encapsulates the idea:

<!DOCTYPE html>
<html>
<body>
<script>
function ret() {   //process data to be returned    window.data.set(data);}</script>


<button onclick="ret()">Submit</button></body></html>

Video Hangouts

Subscribers to Sandstorm's Full-feature plan can now host video hangouts in their sessions! When creating a server, just make sure you...