Advanced HTML Previews

About HTML Previews
Example Actions
Presenting HTML Previews
Generating HTML Content
Controlling Flow
Sending Data from Preview

About HTML Previews

The HTML preview action step provides a way to display HTML in a local in-app web browser. The primary use of this step is to preview content intended for the web, and is typically used along with content created in Markdown to preview the HTML output.

HTML Previews are not limited to this purpose. The content displayed can be dynamically generated, use all the tools of the browser (HTML/CSS/JavaScript), load remote content (images, scripts, stylesheets, run scripts, and even send data back to Drafts from HTML forms or other dynamic content in the page - allowing the HTML Preview step to be used to generate custom user interfaces for Drafts actions.

If you have basic skills in HTML and related technologies, this article is designed to help you utilize some of these advanced features in your actions. Possible use cases:

Creating more complicated user input forms than can be created with Drafts Prompt scripting, which have validation or other advanced features.
Use JavaScript library which depend on running in a browser because they utilize functions not available in Drafts JavaScript runtime (DOM, Ajax).

Example Actions

Like to learn by example? We have provided a couple of example actions demonstrating use of techniques discussed in this article:

HTML Preview Form Example: Displays a simple HTML form, and shows how to gather values from the form and use them in a script.
HTML > Markdown: Uses browser-dependent JavaScript library to convert raw HTML in the current draft into Markdown.

Presenting HTML Previews

HTML Previews can be presented either using the HTML Preview action step or in script using the HTMLPreview object.

By default, previews are presented in a window, and contain toolbars with buttons to “Continue” or “Cancel”. HTML Previews can optionally be configured to “Hide interface”, in which case these toolbars will not be displayed. This option is useful when using the preview to generate user interface where you control the flow. See controlling flow section below for details.

Generating HTML Content

Whether presenting via the action step or script, the preview requires an HTML document to display. The content displayed should be a complete HTML document. When using HTML Previews to display content from the current draft, one would typically use Drafts template tags to insert dynamic content, but this information could also be loaded from files, include static content, be built by scripts…there are many possibilities.

Like any browser display, your generated HTML can:

Include scripts and stylesheets.
Link to external resources on the web, like images, stylesheets and scripts.
Contain interactive elements, forms, buttons and the like.

Controlling Flow

When an HTML Preview is displayed, it is displayed modally and pauses the execution of the action until it is closed by the user.

Drafts makes the following JavaScript functions available to be called from script in the HTML document loaded in the preview:

Drafts.continue(): Call this function to close the preview window and continuing execution of the current action. This is equivalent to the user tapping/clicking the “Continue” button in the preview.
Drafts.cancel(): Call this function to close the preview, cancelling. This is equivalent to the user tapping/clicking the “Cancel” button in the preview.

If you choose to display an HTML Preview with the “Hide Interface” option, your own JavaScript in the preview must call one of these functions to close the preview and allow the action to finish.

Sending Data from Preview

If using an HTML Preview to gather input, JavaScript in the HTML document can send data back to Drafts using the following function:

Drafts.send(key, value): Send data to the Drafts scripting context. This can be use to make any values, selections, or other details generated from user input available to scripts running after the preview is presented in the same action. The values become entries in the context.previewValues object.

In a simple example, if you embed the following script in your HTML Preview:

<script>
    Drafts.send("myString", "String value");
    Drafts.send("myObject", {"a": 1, "b": 2});
</script>

After the script is run in the preview, in a subsequent script step in the same action, these values could be accessed as follows:

let s = context.previewValues["myString"]; // "String Value"
let obj = context.previewValues["myObject"]; // {"a": 1, "b": 2}

A more practical example, you might serialize the values in an HTML form, and send those back to Drafts when the user submits the form. Something along the lines of the below in your HTML:

<form id="data-form">
<p>
    <label for="input-1">Input 1</label>
    <input id="input-1" type="text" placeholder="Input 1" value="Sample text">
</p>
<p>
	<label for="select-1">Select 1</label>
	<select id="select-1">
		<option>0</option>
		<option>1</option>
		<option>2</option>
	</select>
</p>
<p>
    <label for="checkbox-1">
    <input type="checkbox" id="checkbox-1" />&nbsp;Checkbox 1</label>
</p>

<div style="margin: 1em 0 3em 0;">
<button onclick="submitFormById('data-form');return false;">
    Submit
</button>
</div>
</form>

<script>
// load form values to an object
let serialize = (form) => {
    let data = {};
    for(let e of form.elements) {
        if (e.type && e.type === 'checkbox') {
            data[e.id] = e.checked;
        }
        else {
            data[e.id] = e.value;
        }
    }
    return data;
};

// send values to Drafts action, then continue...
let submitFormById = (id) => {
	let f = document.getElementById(id);
	let data = serialize(f);
	Drafts.send("formValues", data);
	Drafts.continue();
}
</script>