``
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:
Prompt
scripting, which have validation or other advanced features.Like to learn by example? We have provided a couple of example actions demonstrating use of techniques discussed in this article:
HTML Previews can be presented either using the HTML Preview action step or in script using the [HTMLPreview
object](https://scripting.getdrafts.com/classes/htmlpreview).
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.
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:
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.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:
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: