Helium Custom Web Content (WIP)

Table of Contents

To be released in Helium 1.17.0

Introduction

The purpose of this article is to provide an example of custom web content can be added to Helium DSL apps. Custom web content (HTML / JS / CSS) can be written and bundled with a Helium application. The static content widget can be used on a Helium view to specify which resource is to be rendered when the view is loaded by a user.

Static content resource must exist in the projects web-app/static directory.

Declaring a Static Content Widget on a Helium View

The static content widget is declared as a single widget on a view. In this example the HTML file being referenced is embedded_component.html which should exist in the web-app/static directory of the project.

The Helium View (EmbeddedComponentView.vxml)

<?xml version="1.0" encoding="UTF-8"?>
<ui xmlns="http://uiprogram.mezzanine.com/View" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://uiprogram.mezzanine.com/View ../views/xsd/View.xsd">
	<view label="view.title.Embedded_Component" unit="EmbeddedComponentUnit" init="init">
		
		<menuitem label="view.title.Embedded_Component" icon="icon-name" order="1" >
			<userRole>...</userRole>
		</menuitem>
		<static source="embedded_component.html"/>
	</view>
</ui>

• A view with static content may include a regular Helium unit to back the view, the view may include a reference to an init function in the unit.

• A view with static content may:
  • Contain a <menuitem/>.
  • Contain <action/> buttons.
  • Be navigated to from other views as part of a workflow.
• A view with static content may not:
  • Declare other widgets along with the static tag, the exception to this is a menuitem and action button.
  • Declare a source that is not found to be bundled in the project (The directory is web-app/static from the project root)

Declaring Static Content

<div>
	<h3>Hello world!</h3>
</div>

• A custom static content source file must:
  • Be a well formed HTML file
  • Have a single top level node such as a <div/> tag.
• A custom static content source file must not:
  • Declare the a DOCTYPE
  • Use the following tags: html,head,title,body
• A custom static content source file may:
  • Include <script> tags
  • Include local styles
  • Import other JS / CSS resources programmatically

Loading Other Bundled Resources From a Component

Embedded static resources can be imported from Helium over REST using JavaScript to make the calls.

Helium Session ID (HSID) 

To allow the custom web content to authenticate with the Helium backend the browser session for the signed in user can be used. This ID is called the Helium Session ID (or HSID).

To authenticate with the HSID any HTTP call made to Helium should include a query parameter 'hsid' with the value as the current session id. To get the current session id the string template ${hsid} can be used.

HTTP GET /web-api/services/app/exec/static/foo.png // 401 Not authenticated
HTTP GET /web-api/services/app/exec/static/bar.png?hsid=${hsid} // 200 Resource downloaded

Loading resources

The following piece of example JavaScript that uses jquery ajax to load JS and CSS resources that are bundled with the app release into the embedded component.

var baseUrl = '/web-api/services/app/exec/static/';
var hsid = '?hsid=' + ${hsid};
var jsUrl = baseUrl + 'embedded_component.js' + hsid;
var cssUrl = baseUrl + 'embedded_component.css' + hsid;
$.ajax({
    url: jsUrl,
    dataType: 'json',
    cache: false,
    error: function (jqXHR, textStatus, errorThrown) {
        console.log("Failed to load JS resource: " + jsUrl + " with result: " + textStatus);
        console.log(errorThrown);
    },
    success: function (data, textStatus, jqXHR) {
    	// Decode result and execute JS
        eval(window.atob(data.data));
    }
});
// Load CSS
$.ajax({
    url: cssUrl,
    dataType: 'json',
    cache: false,
    error: function (jqXHR, textStatus, errorThrown) {
        console.log("Failed to load CSS resource: " + cssUrl + " with result: " + textStatus);
        console.log(errorThrown);
    },
    success: function (data, textStatus, jqXHR) {
    	// Decode result and include styles
        $('head').append('<style type="text/css">' + window.atob(data.data) + '</style>');
    }
});

• Resources are exposed by Helium at the base url /web-api/services/app/exec/static/{resource-name}
• Authentication is done using the HSID, see how the JS variable named hsid is declared on line 2

Consuming the Helium Inbound API

The Helium Inbound API can be used to an an interface between a custom web component and Helium to extract data or perform operations. All REST API calls made to Helium need to be authenticated using the hsid query parameter.

Leveraging Helium CSS Classes

The bundled custom web content is rendered within the Helium webapp in the clients browser. The stylesheets declared by Helium (CSS) is available and can be to be reused to build HTML components that fit in with the look and feel of a Helium application.

The following is an example that displays a simple label with an input field that re-uses stylesheet classes declared in Helium. The code will output label and input tags that are styled by Helium's included stylesheet. See Helium CSS Classes for a list of examples that create HTML styled with Helium's look and feel by using Helium's CSS classes which are accessible from the context of the web-app. 

It is recommended to make use of the built in Helium UI components when possible since these already have support for large datasets with features like paging, sorting and filtering.

Plain HTML

<div class="widget-container">
	<label for="w0">What is the meaning of life?</label>
	<input id="w0" type="number" value="42" class="widget textoutput ui-corner-all">
</div>

JavaScript / jQuery

var myDiv = ${'#myDiv'}; // Assuming an element with ID myDiv exists.
var labelText = 'What is the meaning of life?';
var value = 42;
// Append label
$('<label />',{
   'for':'w0'
   'text':labelText
}).appendTo(myDiv);
// Append span
$('<span />',{
	value
}).addClass("widget textoutput ui-corner-all").appendTo(myDiv);

* The input could alternatively be styled as an input if the classes "textoutput" and "ui-corner-all" are removed and the classes "input" and "textinput" are introduced on the input tag.

Result in browser

Samples of styles imported for classes in HTML

.widget-container {
    float: left;
    clear: both;
    margin-bottom: 10px;
}
 
.widget-container label {
    width: 200px;
    float: left;
    margin-top: 0.2em;
    min-height: 22px;
    padding: 3px 0 3px 0;
}
.widget-container .input {
    width: 250px;
    float: left;
}
 
.widget-container .textoutput {
    font-size: 1.1em;
    min-height: 28px;
    display: inline-block;
    float: left;
    padding: 4px;
    background-color: #EDEDED;
    border: 1px solid #DDD;
    -moz-box-shadow: 0 0 2px 0 white inset;
    -webkit-box-shadow: 0 0 2px 0 white inset;
    box-shadow: 0 0 2px 0 white inset;
}

Source Code

An example repo is zipped and attached to this article, you can also find the source on Bitbucket