Webtag Applicability (preserving history)

From Cumulus Wiki
Revision as of 16:16, 4 December 2021 by Sfws (talk | contribs) (Corrections: material on this Wiki page was originally on "webtags" page, somehow it never got edited for being on new page!)
Jump to navigationJump to search

This Wiki page

The Web tags page was getting far too complicated, information about input/output modification parameters was moved to Webtags/Parameters page, and information previously on main web tag page relating to specific beta builds,legacy versions and MX releases has been moved to this page.

Cumulus MX provides many, but not all web tags that were available in Cumulus 1.

MX adds many more web tags, mostly in support of new weather stations or new sensors.

The list of tag names on Web tags page makes an attempt to describe which tags are available for different builds. However, it is made complicated in that:

  • originally, the additional webtags page was created to hold web tags that were not yet available in any Cumulus 1 formal release, but were available in any Beta version that was under development.
  • some tag names are only available for the legacy Cumulus 1 software,
    • these were listed on the beta page, while they were in beta
    • these were deleted from the beta page and included on the Web tags page when available in a formal legacy release
    • all legacy web tags remained included until final version
  • further tag names are introduced by Cumulus MX,
    • for 3.0.0 builds of MX, all the MX only tags were listed on the beta page, which had become empty when beta builds of the legacy software ended
    • for 3.0.0 builds of MX, any tags that were available in the legacy software and in MX were listed on the main Web tags page
    • this meant early MX users had to look at two Wiki pages with some tag names on one page, some on other page
    • for 3.1.0 and later MX releases, all the MX tags joined the legacy tags on the main Web tags page
    • early releases of MX supported a small subset of the tag names available in the legacy software, but nobody marked which legacy tag names were not available in MX
    • some MX tag names were introduced in error and later withdrawn, either because MX could not access that data from a weather station in the way that the legacy software had done (e.g. <#THWindex>), or because the derivative being reported (e.g. <#ThumidexTL>) did not make sense
  • the output modification parameters for time/date vary between the legacy software and MX
  • some input/output modification parameters vary depending on which MX release is being used

Thus a very complicated explanation of the impact of all the above on a tag by tag basis used to appear on the Web tags page, but to simplify that page, a summary of such information has since been moved here.


A note of caution

Given how often a new release alters either what web tags are available or what parameters can be used with particular web tags, it is possible the tables on the linked page do not list all web tags at any version, and the tables can't say which modifiers are available at your version.


Please note that where any page in this Wiki makes reference to other pages in the Wiki, such cross-references often date from before MX was available

Consequently, any MX user should exercise caution; as there are differences between the user interface for Cumulus 1 and MX flavours of this software, and the Wiki was originally written before MX existed, so there remain a lot of references to the setting screens for the legacy software, and pages may have not been updated for the ever changing MX.

Cumulus 2

Cumulus 2 is no longer available, it never did any web page generation, so even if you happen to have installed Cumulus 2 from when it was available, there are no web tags it supports.


Beta Builds of Cumulus MX

The developer of MX new releases normally shares a new version of MX first as beta by sending the distribution in an email to a number of Cumulus users. They respond by email, with the intention any issues can be ironed out before the distribution is made available as a public release. Given the number of weather station types supported and the complexity of options for using Cumulus, this does not always ensure all ways in which MX can be used are tested, especially as the Cumulus Users given the beta test zip might not use all the features that have been modified in a particular development.

Any new web tags introduced by a MX beta are not publically available, so may not be mentioned in the main web tags page. Sometimes there are multiple MX beta releases before a public release, often the update history gets abbreviated when multiple beta are merged for the public release, and some changes get lost.

Public releases of Cumulus MX

Each public release is announced, but some changes that may have been made in advance, and recorded in forum threads, don't always get a mention in the formal release announcement. The formal release announcement is kept brief, and tends not to give a full list of new web tags, or not to fully explain those it does mention! This does mean that documentation in the Wiki may be delayed, missing, or incorrect!

MX has become more and more complicated and more ambitious, so keeping the Wiki up to date has become a bigger chore. It is assumed that the web tag page will still be used by those running the legacy software, so it should be correctly identifying tag names only available to MX users.

The web tag main page will no longer attempt to maintain details of which MX releases apply for tag names, MX users are expected to keep updating to newest release, so for tag names, the reader must check which apply to their MX release.

Template files

All web servers need to get the latest data uploaded.

The terminology "template files" was used historically for files that Cumulus was asked to process, so that any web tags included in the file got replaced by the equivalent latest value, time-stamp, etc.

In the case of the legacy Cumulus, Beth Loft designed some web pages, and Steve Loft made these available as example HTML template files, by a single setting in the legacy Cumulus, it would process the full standard set of example HTML template files, or replacement HTML template files with same names, and upload them as web pages to a web server. Alternatively, the user could write their own web pages, either using Cumulus 1 to create these web pages from template files, or using Cumulus 1 to process XML or PHP data file templates that were, then uploaded and used as source of data for web pages already on the web server. For the graphs that could appear on web pages, the legacy Cumulus software processed data internally to create a set of graph images, in a single setting these could all be uploaded to your web server.

Early releases of MX supported a similar process, except that there were no graph images, the data was generated internally and uploaded as a JSON data file. From releases 3.10.x onwards, the JSON data approach has been expanded to cover all the default web pages (which only get uploaded once), with each using a JavaScript file to extract the data from the relevant JSON file and either place it in the relevant position on a web page or plot it using HighStock library software.

Using your own web pages with Cumulus:

  • You can, even with latest MX release, create a template file using web tags, as mentioned elsewhere on this page, and fully described on the Customised templates page.
  • MX will raise an error:
    • for any web tag it does not recognise at the version you are running (see example below these bullet points)
    • for any input parameter that the token parser is unable to recognise
  • MX treats output parameters differently to the legacy Cumulus:
    • any output parameter that it does not recognise at all, is ignored
    • any output parameter in a web tag that does not accept output parameters is also ignored
    • any output parameter in a web tag that does accept output parameters, where the supplied parameter is inconsistent with the content of the web tag, is reported as an error by the token parser
    • an output parameter that specifies only part of the standard output may be reported as an error because of single character rules (for example a tag that reports a time cannot understand format=H, amongst the acceptable formats are format=%H for just hour and format=H:mm for hour and minutes but not seconds.
    • any output parameter that contains incorrectly formatted characters in that output parameter will be treated as an error by the token parser (a common mistake is forgetting spaces are expected to be included with other literal characters by the MX token parser)
    • if you use valid parameters but the wrong parameters, you are likely to be confused by the output (the most common cases result in seeing minutes where a month is wanted, or there is a misunderstanding of the concept where the same character has different meanings when on its own and when with other characters).

Example of how MX deals with tag name it does not understand

When MX is processing through tag names and finds one it cannot understand, a "*** web tag error - see MXdiags file ***" message will appear in the engine console (if running interactively, you don't see this if running as a service), and the diagnostic file will include something like this, be aware a "token" parser is used to evaluate web tags:

Web tag error
Exception: i=8998 len=106297
inputText.Length=106297
token=<#daylightlength format=H>

This particular error is that when you use a single output format character it does not have same meaning as when there are multiple characters, correct this particular web tag to:

<#daylightlength format=%H>


Original (legacy) Cumulus software

  • There are gaps in the Cumulus 1 documentation, and so it is not usual for any web tag page table entry to indicate when a particular tag name started to be available
  • If you are using the final version of Cumulus 1, then all legacy tag names will be available to you
  • In general, Cumulus 1 will silently ignore any web tag it does not recognise. This means that you might see the raw

web tag remaining after processing, or you might see a gap on your web page where the web tag was prior to processing. It also means that if you try to do a numeric calculation on a web tag that Cumulus 1 does not recognise, the calculation will fail, but you might not see an error message.

  • Thus to look for errors in tag names, or their input/output modifiers, you must carefully examine your web pages to find errors.