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 these files it generates output files where the tags/tokens have been replaced by values.
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.
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 modifed 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.
Template files you add
The page dealing with the customisation of web templates is Customised templates, and it includes a diagram that explains how file names are affected by your choices in some of the settings for file transfer.
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 you choose, hence the generated file will have "tmp" added to the end of the template name you selected, just to remind you of its temporary existance until the source template is processed again. That "tmp" is removed when the final web page is stored on your web server.
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.
- 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.
- 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:
- availabledata.json
- 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.
