12. User HTML

This section is an updated version of the user_html_cgi.pdf document found on the introduction page under User HTML Tutorials at https://info.csimn.com. This information has been updated per implementation in ValuPoint. Except for changing the link “../index.html” to “/html/index.html” where applicable, the various demos found in the knowledgebase should work in a ValuPoint.

The “naked pages” referenced in the 2008 version of the CGI overview are not implemented in ValuPoint. They were an attempt at allowing some level of “private labeling” the ValuPoint. If private labeling is desired, Control Solutions does offer that option which will result in fully rebranding the entire preprogrammed web UI.

12.1 Static HTML

User HTML may be installed as a “wrapper” around the default web pages. To install user HTML, use the File Manager (filter set to *.*) to upload any combination of .html, .txt, .gif, and .jpg files. You can also include .pdf, .xml, .css and JavaScript .js files. Note that PHP, ASP, etc., are not supported.

You can also use FTP to upload files to the /FLASH0 (that’s flash zero) directory and this will be the default directory upon opening an FTP session. An FTP session in Linux, Windows command prompt, or Windows PowerShell work well. Some smart FTP clients work, but some try to be too helpful and simply screw things up. We tested FileZilla at one point and it seemed to work ok, but we do not keep testing every revision of FileZilla.

The top level user file must be named User.html (case sensitive). If this file is present in /FLASH0, it will be served instead of the default index.html page pre-programmed in the device any time you simply browse to the device's IP address. Once this page is open, it may link to any other html files in the /FLASH0 directory. All user HTML is filtered as it is served to provide dynamic content.

There are a handful of tricks that must be observed to make user html work. All references to other user pages and to user image files must have the file names preceded with /UE/ as in /UE/User2.html or /UE/mypicture.gif. The UE stands for “user escape” and is treated as a virtual directory that actually points to /FLASH0. All preprogrammed pages are found in /html/ and preprogrammed images are found in /img/.

12.2 Dynamic Data Tags in User HTML

Dynamic Data – Creating a Form

Dynamic access to register data is provided. Dynamic updates of register contents is also supported via the form post method. The form must be defined using the following tags:

</form>

The submit button causing the post must be defined as:

Any submit buttons other than those recognized as noted here will simply result in a page refresh. Only the submit button named “submitChange” with a value of “Change” will result in parsing of the form data. Only a form with action as named above will be parsed.

If you want to redefine the appearance of the button, you can implement a graphic button by including an image as follows, and then including the JavaScript function as shown:

Input Types: <input type=”text”>

Two types of data input are recognized by CGI processing of the user post: Text input and option select. The search string keyed upon for text is <input type=”text” and the search string keyed upon for the select option is <select name=

A text input should be constructed as follows:

The contents of the register number included in the name (“regX”) will be displayed when the page is served, and the data will be taken dynamically from the register at that point in time, and again each time the page is refreshed. The data will be formatted using the C format string found in the value tag. Integer formats (%d, %04d, %x, etc) should be used for integer registers, and floating point (%f, %.2f, etc) should be used for floating point registers. If “readonly” is specified, data will only be displayed in this window. Otherwise the data returned by the post will be parsed, and the result placed back into the register.

The following keywords are recognized as text input “names”:

            regX – references the value in local register number X
            namX – references the name of register number X
            site – references the Thing Name (Thing ID page)

All of these data elements may be read, and will be written unless you specify “readonly”. The definition of read means take data from the local register when serving the page, and write means write data to the local register if the form was submitted by the appropriately named submit button (see Form above).

Input Types: <select>

An option select should be constructed as follows:

The strings corresponding to the values given will be displayed when the register named matches that value, otherwise “---“ will be displayed. When an option is selected and the form posted, the value corresponding to the new selection will be written back into the register. The “selected” tag shown above is not required since it is automatically inserted in the appropriate place (moved around) when the page is served.

Input Types: <input type=”hidden”>

An additional form of input has been added to filtered HTML. Hidden variables may be defined using the following syntax:

This will be processed the same as “text” input except the value is not displayed. This is useful as a means of providing non-displayed data to a JavaScript function. Hidden data upon return will be parsed and put back into registers unless readonly is specified. Omit readonly if hidden data should be parsed. This provides a means for JavaScript to get data back into registers.

Page Links

To create a link on the user page to get into the default preprogrammed pages, define a link to “/html/index.html”, for example:

To link to another user page in the FLASH0 directory, use a link such as:

Links to graphic images you want shown on the page are created in similar fashion:

Note that you preface the page name with “/UE/” when the file is located in the FLASH0 directory, but preface the name with “/html/” when accessing a preprogrammed page.

Password Protection

There are 3 levels of password protection: Restricted, Maintenance, Administrator (root is a special form of administrator). User pages may be password protected at the “Restricted” level. To password protect a user page, simply insert the letters “pw” in front of the name. Therefore, if User2.html is a page you wish to protect, rename it pwUser2.html.

The top level page for User HTML must still be named User.html (and not user.html or not USER.html). If you don’t want anything useful to be completely unrestricted, simply put a plain dumb page in User.html with a link that says “log in” and link it to pwUser.html.

Note that “restricted” level of password protection means the user can access any “pw” user pages, but cannot access any pages beyond index in the pre-programmed page set.

Other Input Types

Radio buttons and other forms of input are not supported at this time. The HTML will be passed through, but not filtered and associated with register data. Therefore, you can use radio buttons, etc., with JavaScript, but you must explicitly associate the resulting data with hidden input variables in order to return the data to registers.

Additional Special Submit Buttons

The submit button causing the post for changing data values must be defined as:

Two additional button actions are available to save the configuration file or restart the device:

12.3 Live JavaScript Gauges

An external JavaScript library can be specified. The JS file should be loaded into the /FLASH0 directory along with User.html, etc. In the HTML file, the script file is referenced as illustrated here by the first few lines of User.html that generated the gauges pictured in the screen shot.

<!doctype html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Gauge Test</title>
<link rel="stylesheet" href="/FS/FLASH0/fonts.css">
<script src="/FS/FLASH0//gauge.min.js"></script>
</head>
<body style="background: #fff" onload="animateGauges()">

(entire project is available on csimn.com web site)

Many different JavaScript gauges are available at https://canvas-gauges.com/.

To cause the gauges to automatically update in real time, you need two things: The animageGauges() function in the JavaScript, and something that is going to retrieve real time data into the HTML document. The real time data retrieval is done by a hidden iframe, included in the User.html like this:

The UserGetData.html is constructed like this:

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">

<html>
<head>
<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
<title>Untitled Page</title>
<meta http-equiv="refresh" content="1">
</head>

</html>

NOTE: The above example using an iframe to retrieve real time data was created prior to adding the REST API capability to ValuPoint. The gauge animation could be restructured to take advantage of the REST API if you know your way around JavaScript.