Cumulus template file

Introduction

A Cumulus Template File is the name given by Steve Loft to any files that contain web tags and need to be processed before they actually include values.

When Cumulus processes any template file, it generates an output file where every included Cumulus web tags has been replaced by values, while any other content is retained unchanged.

Consequently, a single template will actually generate a different file each time Cumulus processes that template because the part of the content that was web tags is now populated with text (values, times, dates, etc.) and, as these values change, a newly generated file is different to the previous generated file.

General Format for Web Tags

In the position, in the template file, where you wish Cumulus to insert the relevant data, place a web tag observing the general format specified here:

<#tag_name [optional input parameters][optional output parameters]>

Case sensitivity

The tag_name in the general format (see above) is case sensitive, so please type the tag name exactly as shown in the web tag columns in the tables on the [Webtags|web tags page]]. Steve Loft did not define a consistent naming standard, so don't make any assumptions about what case he selected for each character, and remember that some names (as explained later) are less easy to predict than others.

Any input selection parameters always use lower case, so please type them exactly as shown in the sections dealing with input parameters on that page.

Where output formatting parameters are used, they are case insensitive for processing by Delphi parser in legacy Cumulus 1. But for MX, all output parameters are case sensitive, and also dependent on what other output formatters are being used if any, so please read the sections on output parameters and study the examples in the tables carefully.

Template files you add

As explained on this page, template file can generate a variety of file types. People writing their own templates can use any file extension (some popular choices are "tmpl" or "cum" to indicate they are Cumulus templates). To ensure that the template files and generated web pages cannot be confused, Steve Loft realised the "T" notation used by the provided templates may not be part of the name used by third parties for their templates, hence he designed Cumulus such that (for a non-standard name) the generated file will have "tmp" added to the end of the template name you selected, just to remind you of its temporary existence (until the source template is processed again). That "tmp" is removed when the final web page is stored on your web server.

Note by Steve Loft: When you put a tag into your template, be careful that whatever program you are using to develop your web pages doesn't change the angle brackets to slightly different symbols -- this is a common cause of failure!

There are a number of editing tools that are designed for editing programming code and you should use one of those (e.g. Notepad++, Brackets, NoteTab Light, HTML kit, amongst many others), rather than a tool designed for web page design editing (e.g. Dreamweaver, word press, amongst others).

Using web tags in templates for creating HTML pages

If you want your template file to generate a web page, then this is discussed fully on the Customised templates page, where there is a diagram that explains how file names are affected by your choices in some of the settings for file transfer.

Here I just remind you that Cumulus web tags are the special markers in your template file; during processing of that template file, Cumulus will replace them with the actual values, in the web page it creates. However, this is just one of many ways to build your own website with Hyper-Text Manipulation Language file with your layout, including static text and perhaps graphics, calling a Cascading Style sheet to define the look. Creating a template with all the content needed for a web page means you are uploading large files (with a significant proportion of their content never changing) every time you want new data on your web site, so the next section describes an alternative way to use a template file to get just the data to your web server.

Using web tags in scripts

As mentioned in previous section, it is inefficient to create a template file where the majority of the content is not web tags and so never changes. JavaScript Object Notation (JSON) files are probably the most efficient way for template files to include just web tags, with minimal structure around them. (In fact MX uses this approach).

If your JavaScript is less structured, then a .js script template can perform arithmetic, and/or validation, on web tags. This gives you more flexibility about how information appears on your web page, and it can support graphical ways of presenting data. JavaScript files can be called from a web page when it is viewed in a browser; consequently, your HTML file can be a static file on your web server, and call a JavaScript file that Cumulus has generated and uploaded, and that script can amend the contents of table cells in your HTML to display the latest data. A variant is AJAX, where a timer allows a fresh JavaScript file to be uploaded (without reloading the web page) and thus refresh the table cell contents; this is discussed elsewhere on more technical pages of this wiki (see Category:WebTips).

• As JavaScript can not understand a real number that has the integer and decimal parts separated by a comma, but your computer may be set to use that representation in standard tags, there are special versions of many tags to use in script - see tags with commas removed section.
• JavaScript is available in every modern browser (Microsoft's Internet Explorer initially used a different language jScript), but actually it is hard to get right. A human being recognises something as a number or text or operation. Programmers writing in JavaScript can use Objects, but you need to be skilled to do that. Without Objects, it is easy to write code that gets text and numbers confused; for example you can have two variables (door1 and door2) defining width of two adjacent doors and want total opening size in variable Opening. The code Opening = door1 + door2; generally will just concatenate the text, rather than add them as numbers! There is some guidance below on how to use "parse" functions to make JavaScript recognise numbers.

PHP Hypertext Preprocessor (PHP) is another script language, it is parsed on the web server and so the browser only sees what is generated by the PHP script, not the actual script. PHP can do a lot, so it takes some time to learn, but it is very simple in concept, and you should find writing simple scripts is surprisingly easy once you master the syntax. There are many guides to writing PHP online, and you may find the notes on PHP page helpful in a Cumulus context.

• Note that if a PHP or JavaScript file contains any Cumulus web tags then you must ask Cumulus to process the script file.
• JavaScript processing code can be embedded in a template that is already being processed into HTML. (This technique has been used in the standard 'monthlyrecordT.htm' template).
• Alternatively embed a bit of JavaScript assignment code in HTML, that is already been processed, to convert the tags to a collection of string variables and use those variable names in any external script called from the HTML file. (This technique has been used in the standard 'gaugesT.htm' template in the legacy Cumulus 1 software).
• To use the value from a tag as an integer in JavaScript assigning code you need to use a

integer_variable_name=parseInt(string_variable_name,10)

type conversion

• To use a value from a tag as a floating point number in JavaScript you need to use

  parseFloat(string_variable_name)

  otherwise you will find any attempt to add something to it results in a concatenation because JavaScript uses "+" for two purposes and concatenation takes precedence over arithmetic adding!
• Alternatively, in most script languages, apply ' * 1', i.e. multiply by one, to implicitly convert the tag from string to base 10 number.
• Another alternative is to add zero when a web tag is being assigned to a script variable, this is frequently used in scripts where the web tag being used is not available in all versions of Cumulus, because Cumulus does not implement the concept of null values and often zero is used when a true value is not available because that sensor is not installed for example. Adding 0 means that if the web tag is not recognised, the script is still able to give a variable in its language some value and won't fail because that variable is undefined. If the web tag is available, adding zero does not prevent the true value of that web tag being assigned to the variable.

Inconsistency of web tag names

Some tags are all lower-case, some are camel-case, and some start with a capital letter. Have a look yourself at just how much inconsistency is present in the names in the tables below. The great inconsistency in the naming, gives rise to a problem as it very easy to spell a tag_name incorrectly as you naturally expect there to be a standard pattern.

You will find yourself frequently having to refer to this article, if you decide to make your own Cumulus templates (see section below for more information). This applies whether those templates are for web pages, to implement Extensible Mark-up Language files, or PHP Hypertext Pre-processor scripts.

When Steve Loft introduced the first web tags as part of developing software for his own use, he did not create a naming standard to ensure consistency in the future. As he introduced further web tags at different times, the names used might be consistent amongst the ones introduced that day, but there was still no naming convention to ensure consistency with tags introduced previously or to help name future tags.

Inconsistency for today, yesterday, this month, this year groups

It would be easier if all tags reporting parameters for today were consistent, let alone consistency in naming between tags for today and yesterday. The tags for this year and this month were introduced in same release, so there is some consistency in how they were named then, but no standard to ensure future tags for this month and this year would be named the same way.

Inconsistency in use of "Y"

• The character "Y" might be included in a web tag to denote yesterday, or it might denote this year
• Where the Y is indicating yesterday, it is sometimes a prefix, sometimes a suffix!

Inconsistency in use of "T"

• The newer web tags for today include a "T" as a suffix, the older ones do not.
  • The lack of a "T" in some today tags causes some confusion with all-time record tags as they have a similar naming structure to these older today web tags.
  • This is particularly confusing and is why you must look up today, and all-time, tags in the tables in this article.
• The time-stamp tags add a "T" to the corresponding web tag for the value, but in an inconsistent way:
  • the T is a prefix sometimes and
  • the T is a suffix sometimes
  • This is particularly confusing and is why you must look up time-stamp tags in the tables in this article.

Choosing script variable names derived from tag names

In the web tag to PHP variable scripts, I have posted, see Php_webtags#Minimised_Upload_size, I have tried to introduce better consistency in the PHP variable names, so "T" is added as a suffix to all "today" variables for example. Some other script authors try to match the inconsistent web tag names, so their script variable names are also inconsistent.

Cumulus MX

All the template files in the latest MX release (at the time of writing) create JavaScript Object Notation (.json) files.

Template files you can customise

These templates use the "T" notation and are found in CumulusMX/web sub-folder.

1. realtimegaugesT.txt is included in all releases, it contains the web tags used to produce the latest available values for the "gauges.htm" web page to plot, and is processed at whatever real time interval you have programmed. There are some settings that determine whether it is processed and whether the resulting data file is uploaded.
2. websitedataT.json is included in releases from 3.10.1, it is a large file, and probably contains more than you need for your web site. Obviously, as this file is transferred to your web server on every standard update period, it is best to upload only what you need. After all you may choose to use only a sub-set of the default web pages provided with MX. The template file can be edited to exclude any derivatives that you don't want, and/or to add any extras you want.

Early MX releases

These had modified versions of the original Beth Loft web templates in the CumulusMX/web sub-folder. These templates use the "T" notation as with the legacy software, but there is no "originals" sub-folder.

Internal template files

The vast majority of the JavaScript Object Notation files uploaded by MX are generated in the code, and so cannot be customised, although later releases have additional settings that give you control over which are generated and which are uploaded.

One-off uploads

These templates are found in CumulusMX/web sub-folder:

1. availabledata.json
2. graphconfig.json

You upload them once if you have the MX default web pages on your web server, as they tell those web pages what settings you have enabled.

Internal api

The admin interface relies on .json files transferred via the application program interface (api), again these are generated within the code and cannot be modified, although scroll up on the linked Wiki page to find out how you can write customised api calls.

Original cumulus software

Template files provided

There is one template that is held within the legacy Cumulus code, this generates the default Realtime.txt. It is possible to generate different content

The other template files are always installed into a sub-folder: cumulus\web\originals (except for very early versions). As its name suggests, "web" sub-folder holds templates that generate web pages for Cumulus to then upload to your web server.

When you run the install package (see Setup, you can choose whether these web template files are also installed into the parent folder cumulus\web.

• This allows you to use only some of the templates (you only include the ones you want the software to process, and delete the others).
• It also means if you have modified the provided template files (keeping original names), the installation process will not overwrite them and you can continue to have the software process your modified template files.

Steve Loft made it clear that the 'web template files his wife (Beth) designed, were their files, and only included in his software as examples to help you devise your own template files. He said, we never thought that people would use our files without modification. Each of these templates, after processing becomes a fully working web page that can optionally be uploaded to your web server.

To help people using the legacy software, there is more about processing of files on the Customised templates page, but think of a template as containing text that Cumulus copies from the template file to the web page it is constructing. The processing process is basically a parse, each time Cumulus finds a web tag complete with any parameters it needs, Cumulus software looks up the value that it will use to replace that web tag in the web page it is creating before moving on through the text.

The example web templates provided by Cumulus insert a "T" at the end of the intended web page name before the extension (.htm or .html), so that the template files and generated web pages cannot be confused.

You may find the information on the FAQ page helps answer some of your questions.

Your own templates

• As the Setup page, and the notes above, indicate, the legacy cumulus software uses a subfolder "originals" to keep the example web templates safe, allowing you to do edits in the cumulus\web folder above that.
  • Such edits, as already mentioned, allow you to modify provided templates.
• Alternatively, you can write your own templates, with any names you like, place them in a new folder you create (perhaps called "cumulus Templates") and using the advice in Customised templates use them.

To summarise the necessary tasks:

1. You can create a template file that has a structure of HTML elements with Cumulus web tags to represent the information you want included.
2. Next you ask Cumulus to process that template file, it will create a HTML page from the template, and during that file creation replace the tag with the current value of the item the tag represents.
3. You also need to tell Cumulus that the resulting HTML file is to be uploaded to the internet (or copied to a local web server).