This page is about parameters used for modifying Cumulus web tags. To put these into context, let us learn the terminology with cross-references to where those features are explained further.
What is a web tag?
Put simply, a web tag is included in a Cumulus template file to indicate where Cumulus should insert values when it processes that template and produces an output file. 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.
The output file can be:
- a web page,
- a PHP script file, or
- a eXtensible Mark-up Language (XML) file.
General Format for Web Tags
In the position in the file where Cumulus is to insert the relevant data, place a web tag in the general format specified here:
<#tag_name [optional input selection parameters] [optional output modification parameters]>
Case sensitivity for tag names
The tag_name in the general format above is case sensitive, so please type the tag name exactly as shown in the web tag columns in the tables on the web tags page.
What is a web tag parameter?
Now we get to the terminology for what this Wiki page will document.
The parameters shown in the general format above are of two kinds:
- Input modifying
- Output modifying
These are explained below, after the warning on case sensitivity.
Case sensitivity for parameters
The optional input parameters always use lower case, so please type them exactly as shown in the sections dealing with input parameters on this page.
The optional output parameters are case insensitive when used in Cumulus 1. But for Cumulus 2 and later, so this includes MX, the 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.
Input modification Parameters
Most web tags do not require any input parameters.
An input parameter is used where the same web tag can represent a value for a number of different past time instants. Each of those past time instants is represented by a different value for the input parameter. So a combination of web tag name and input parameter lets Cumulus to pick the value you want to see.
There are currently only two groups of tags where an input parameter is mandatory:
- The recent history tags where a separate value exists for potentially every individual minute in last week.
- These tags need between one and three input parameters as explained below.
- The monthly all-time records where a separate value exists for each particular month (of any year).
- These tags need an input parameter specifying which month.
- To save you looking up the linked section, a single input parameter is needed (which is 1 for January to 12 for December, or 0 for current month).
You specify which value you want from the array by using parameters on the web tags for number of days ago, hours ago, and minutes ago. The same d, h, and m, parameters are used by Cumulus 1 and MX.
All values supplied for parameters must be whole numbers.
If you don't supply any parameters, the result is undefined for Cumulus 1, and an illegal web tag for MX.
<#RecentOutsideTemp m=1> will give the temperature one minute ago, <#RecentOutsideTemp h=1> will give the temperature one hour ago (as will <#RecentOutsideTemp m=60>).
<#RecentOutsideTemp d=1> will give the temperature one day ago. Please note: Some Cumulus users say that using <#RecentOutsideTemp d=1 m=1> is more reliable at getting the temperature at a similar time the day before, the extra minute apparently gives better results when you might not be using Cumulus all the time, or your weather station might have some drift on when it supplies readings. See which works best for you.
<#RecentOutsideTemp d=1 h=1 m=1> will give the temperature one day, one hour and one minute ago.
Please note that parameters specify time-stamped array element to retrieve based on counting back from current local time so the result for any period including when clocks change may not be quite what you anticipated.
When Cumulus is re-started the array it sets up will be based on reading the logs, so the contents will initially have a resolution according to the logger interval you have set in Cumulus and/or your station. You'll get the nearest value if you ask for a time for which there is currently no exact match, and the first tag listed tells you that nearest time.
Variations between Builds/Versions
Before build 1098, the recent history array did not initialise correctly from the station logger for the period since Cumulus was last run.
The input parameters are same for Cumulus 1 and Cumulus MX, they always use lower case d, h or m.
The list of tags available has not changed between last Cumulus 1 release and any MX release. Any new derivatives reported elsewhere have not resulted in equivalent new recent history tags.
Each Monthly All Time Records web tag has an optional input parameter "mon=N" where N is the index of the month of the year that you want the value for (January=1 and so on).
If you don't supply an input parameter (or supply an invalid value like zero) the current month will be used. This is useful if you want to write a template that will always supply values for the current month and don't want to use a script to enter the correct input parameter by processing with that script before Cumulus processes the template.
The corresponding date/time web tags are formatted just like the all time records. You can customise the date and time formats by adding the output 'format' modification parameters (shown later on this page) to the web tag.
To supply both optional input modification, and optional output modification parameters, separate them with spaces, e.g. <#ByMonthTempHT mon=7 format=hh:nn>. In that example, the highest ever temperature in July is returned in the value after processing by Cumulus.
Output modification parameters
- A few web tags always need an output format specifier
- Some web tags never use an output format specifier
- The majority of web tags either can use an output format parameter, but they have a default output if there is no output format modifier.
This page does not tell you which web tags fall into each of the above 3 types.
To make life more complicated, the availability of output format parameters for particular web tags is dependent on which Cumulus release you are running. There is a general discussion about applicability, but that does not yet specify dependencies for individualweb tags.
The output modification options available, if you are using a MX release, include:
- if your locale specifies that integer and decimal parts of real numbers are separated by a comma, there is an ouput parameter to replace that decimal comma by a decimal point for any script that does not recognise decimal commas
- there are two output modifiers for changing number of decimal places
- there are multiple output modifiers for changing date and/or time format
Each of these will be explained in turn.
Output Modification Parameter for Removing Commas
General format: <#tag_name rc=y>
This only applies:
- if the web tag name represents a real number with integer and decimal parts
- if you are using MX
- From beta release 3.0.0, build 3047 (3 February 2019), up to and including release 3.5.3, only implemented on a few new web tags (#MoonPercent, #MoonPercentAbs, #MoonAge)
- From release 3.6.6 onwards (1 June 2020), it was extended to other web tags that output real numbers.
- From release 3.10.5 onwards (29 March 2021), the use of <#tag_name rc=n> became also possible, to ensure decimal comma shown when locale specifies it
This output modification format parameter can be used to replace all commas in the output by a full stop (don't worry, MX does not use a comma for separating off thousands, so it is the decimal comma that becomes a decimal full stop like character when this remove comma specifier is used).
If you run MX on a computer using Microsoft Windows, then the "locale" mentioned below is determined by settings in either Control Panel (go to "Clock and Region" screen, choose "Change date, time or number formats", choose "Language preferences") or using "Settings app" (go directly to "Language").
On computers running other operating systems, the locale is set when you install "Mono-complete". You can overide the default locale with -lang parameter when starting MX.
|rc=n||This is the default, so does not need to be specified. The output from the web tag will use either decimal comma or decimal point as specified by the locale in which MX is running|
|rc=y||the attribute rc takes the value 'y' to replace any commas defined by the locale with full stops to separate integer and decimal parts of the output value.|
Two Output (format modifier) parameters for decimal places
This functionality was trialled in the original Cumulus, but has been properly implemented in MX.
From release 3.10.5 (which did a big rewrite of web tag handling), you can modify the way real numbers (with integer and decimal parts) are output using output modification parameters in either of the following formats:
- <#tag_name dp=i> and
- <#tag_name tc=y>
These can be applied to any tag names that represent real numbers (with integer and decimal parts).
If you are using an early release of MX:
- From beta releases (3.0.0) onwards, <#latitude dp=i> and <#longitude dp=i> were able to be output with "i" decimal places
- But this output modification parameter could not be applied to any other tags in the MX beta.
- MX when it came out of beta, added this output modification parameter usage in the moon tags <#MoonPercent> and <#MoonPercentAbs>).
- Specifically, <#MoonAge> gives "11" but <#MoonAge dp=3> gives "11.234"
- In later releases of MX, any tag that gives a decimal output, can use the "dp=n" modifier.
If you are using the legacy Cumulus (1.9.4), only <#latitude dp=i> and <#longitude dp=i> were able to be output with "i" decimal places, e.g. <#latitude dp=5> gives "59.24250".
Controlling the number of decimal places
Internally, Cumulus stores numbers in binary. You cannot represent base 10 decimal places exactly in base 2. Therefore, Cumulus stores to a precision that would generally give about 24 significant figures when expressed in base 10.
The number of decimal places output by default in any web tag varies, as each is coded individually. The default output from a web tag is generally rounded to one, or two decimal places, although in a few cases it is rounded to nearest integer. People have found that default does not always suit them, maybe they feel their instrumentation does not produce measurments to that precision, and so gradually Cumulus has allowed more and more of its output to take an output format modifier that allows people to control number of decimal places shown with rounding.
- dp=i is used for both Cumulus 1 and MX.
- The value i following the attribute dp is an integer, it represents how many decimal places you want for the output you see.
- If you are not using latest MX release, you may find this is not available for particular web tag names
Truncation of unwanted decimal places
Whilst many people want Cumulus to round output as done by the previous parameters, there are circumstances when rounding down (or truncation) gives the result desired. This output format modifier is only available in MX.
- tc=y is the truncation parameter, the attribute tc takes the value 'y' to remove decimal places by truncation. e.g. <#MoonAge tc=y>.
- If you are using an early release of MX, you will need to research whether this is available for particular web tag names
- Later releases of MX implement this for any tag that by default outputs decimal places.
Multiple Output Format Modifier parameters for times and dates
These are highly complicated, and so have been left until after the simpler ones!
Where date format codes are used
Time/Date format codes are used in two places:
- As part of report names for NOAA style reports (see this page for full details)
- As part of web-tags that report either times or dates, or report both a date and a time (this is what the rest of this page covers)
Which web tag names take date/time output formatting modifiers
Cumulus includes a lot of web tags that can output dates, times, or both. In many cases, it will not be obvious from the web tag name whether it can return both time and date information. Sometimes, the default (without any output format modification codes) will reveal whether date and time information are both available, but unfortunately that does not always work. The following table shows some examples of which web tags will accept time and/or date output modifiers. Be aware, some of the tags shown in the table may return "---" or "--:--" or some other non-numerical output in two circumstances:
- where the event they report does not happen that day (e.g. moon rise and set do not always happen within a calendar day on Earth.
- where the related data is not defined until at least one whole day has been recorded (e.g. some monthly and yearly web tags do not contain data until second day of month/year)
Remember, the default format for web tags reporting date and/or time is often dependent on the locale you are using for running MX (and we will discover below the effect of some output format modifiers is also dependent on locale):
If you run MX on a computer using Microsoft Windows, then the "locale" is determined by settings in either Control Panel (go to "Clock and Region" screen, choose "Change date, time or number formats", choose "Language preferences") or using "Settings app" (go directly to "Language").
On computers running other operating systems, the locale is set when you install "Mono-complete". You can overide the default locale with -lang parameter when starting MX.
|Cross-reference||Accept time only (examples)||Accept date only (examples)||Accept time and date modifiers (examples)|
|Date &Time, Webtags#Day/Night/Sun/Moon||<#timehhmmss>, <#minute>, <#hour>, <#sunrise>, <#sunset>, <#dawn>, <#dusk>||<#LatestErrorDate>, <#date>||<#LastDataReadT>, <#time>, <#metdate>, <#metdateyesterday>, <#update>, <#LastDataReadT>|
|Webtags#Today, Webtags#Yesterday||any tag in "Time" column of linked table||None||None|
|Webtags#Monthly, Webtags#Yearly||any tag in "Time" column of linked table||any tag in "Date" column of linked table||None|
|Webtags#All_Time, Webtags#Monthly_All_Time_Records||n/a||n/a||any tag in "Date/Time" column of linked table|
What can time/date output modifiers do?
These output format modifiers allow you to override the default display format for a particular web tag (subject to restrictions seen in last sub-section), using the format specifiers to be described later. The characters used to represent year, month, day, hour, minute, second, microsecond, and am/pm; all differ between C1 and MX.
- You can choose whether 12-hour clock is used with am/pm, or the 24-hour clock is used.
- You can choose to include/exclude leading zero for hours.
- You can only report the hour if you don't care about the minutes, or only report the minutes if you don't need the hour.
- In most cases you can add seconds to the output, and in some cases either milliseconds or microseconds. This does not imply that Cumulus calculates everything every microsecond, in fact many are only calculated once a minute, but the flexibility is there for time outputs.
Use of double quotation marks
The general syntax is <#tag_name format=x> where x can represent a single chacter, or multiple characters without any spaces.
If we need to include spaces, then we have to add double quotation matrks round the right hand side as shown here <#tag_name format="x y z">
Dependency on Cumulus flavour
There are differences between the original (legacy) Cumulus and MX. The characters used for specifying the required output modification vary, so all tables showing details of time and date modifiers have separate columns showing what is used in each flavour.
For the legacy software
I deal with this first, just because it is simple!
From version 1.9.1, most web-tags that report any form of time or date will accept an optional 'output format' parameter (we have already seen whether this can only affect time, only affect date, or both).
The legacy Cumulus uses Delphi to interpret the output modifiers:
- For most modifiers, a particular character produces the same output regardless whether the output modification specifier is in capitals or lower-case
- There is an exception, the case you use for any am/pm output format modifiers determines the case that is output.
- In general, the context of a modifier does not affect the output it produces
- Again, there is an exception, "m" or "M" has two different meanings (minutes or month) depending on context.
The complications with MX
In Cumulus MX the same character can have 4 different meanings depending on its case (capital letter or lower-case letter), and depending on whether it is on its own (standard format) or not (custom format). Sounds confusing? Well it is complicated.
Consider context first:
- <#tag_name format=x>
- If the x in the above general syntax is a single character, it represents a standard format code
- The standard characters for dates and times are defined at standard-date-and-time-format-strings
- <#tag_name format=xyz>
- If the xyz in the above general syntax is replaced by two or more characters, it becomes a custom format code (combinations of characters, or single characters prefixed by %)
- The custom characters for dates and times are defined at custom-date-and-time-format-strings
Consider case next:
- Cumulus MX (when running on Windows) uses the .NET software which is provided as standard by Microsoft Windows.
- ".NET" was originally operating system independent, later only Microsoft Windows specific components were included, but since November 2020 ".Net" is used for an operating system independent version that originally Microsoft issued under another name!
- (actually it is possible to install and run "Mono" in Windows Operating Systems).
- If Cumulus MX is running on any Linux distribution (including Raspberry Pi Operating Systems) or Mac OS X, or any other device that uses an UNIX derived operating system, then MX uses Mono software for same purposes. (MONO is a operating system independent version of .NET, although they are developed independently, they have common origins).
Effect of Locales
Locales have already been mentioned twice on this page, now it is time to say what is defined in these locales.
Cumulus works with dates specified in either a day before month before year format, or ISO 8601 date format where year comes first (yyyy-MM-dd). If you are in the USA, you can can combine the month specifier in the previous sub-section, with the day specifier in this sub-section to get an output where the month appears first.
Locales will define a Short Date Format and a Long Date Format. Which date format is used as the default, depends on which web tag is used. What appears in short and long formats depends entirely on the selected locale.
If you run MX on a computer using Microsoft Windows, then the "locale" is determined by settings in the (now hidden) Control Panel (go to "Clock and Region" screen, choose "Change date, time or number formats", and enter the formats you want for long and short here).
On computers running other operating systems, the locale is set when you install "Mono-complete". That is determined by language settings when you set up your computer, but you may be able to edit the configuration to change what is defined for the long and short formats. You can overide the default locale with -lang parameter when starting MX.
There is a single character output format modifier (G or c) that makes the output appear exactly as defined in short date format, followed by long time format. There are other format codes in table below for other date outputs.
All locales offer both numerical and alphabetical formats for representing months.
- In the following table "MMM" is shown as producing short month name.
- What language is used, and what characters appear, depend on what is set up for your language in your settings (by default or by you changing your settings)
- In British English (UK) locale this will be the appropriate 3 letter abbreviation that starts with "Jan" and runs to "Dec"
- It appears that language settings in many locales (not "en-gb"), add a full stop to any abbreviations (e.g. Australia settings default to "Jan." to "Dec.")
- MX has been coded to remove that full stop in various places (like in standard log file naming and NOAA report naming), but at the time this section was edited, "MMM" still reports the full stop if your locale uses it
- In the following table "MMMM" is shown as producing the full name for a month
- This will depend on the language defined in your locale
- In English locales, this will be "January" - "December"
All locales offer both numerical and alphabetical formats for representing a day.
The table below relates just to the day part of any date specifications. As for month above, the short and full day names that are generated depend on your locale, so you might see additional punctuation defined in some locales.
These are the simplest output format modifiers. We choose from 2 options, and because both involve more than one character their context does not matter. Although the legacy Cumulus will accept upper case, it is simplest if we just show the lower case options:
|yy||Displays the year as a two-digit number (00-99).||19 produced by <#LastDataReadT format=yy>|
|yyyy||Displays the year as a four-digit number (2000-9999).||2009 produced by <#LastDataReadT format=yyyy>|
Here context matters, so both standard (single character) and custom (two or more characters) formats are shown in the following table.
In some rows of this table, square brackets  indicate optional items, they are included just to make it clearer how items can be combined in a single output parameter. If you want to include what is shown in square brackets you don't type the square brackets e.g. <#LastDataReadT format="h:nn am/pm">
Some Extra Information
Having covered the basics of both date and time modifiers above, it is time to talk about incorporating other information in an output modifying date/time format specification.
Basically, we can include literal characters, and we can include HyperText Manipulation Language tags, in our specifiers.
Finally, there will be a section on migrating from the legacy Cumulus to MX and how to modify the web tags in your templates to keep them working.
Including literals in format parameters
As stated long ago on this page, if you are going to include spaces, or any other characters not defined in tables above, you must put double quotes round the whole specifier folowing the equals sign e.g. <#YearTempHT format="hh nn"> can be used with Cumulus 1.9.x. Consequently, you cannot include double quote characters in any other position (see here for work-around).
You should put anything that is additional, to the defined format modifier specification below, into single quotation marks to prevent it being interpreted as a date or time format modifier. In MX, such single quotation marks should include the spaces round the additional literal text.
- For example, the word "on" contains the character "n", which for Cumulus versions 1.9.1 to 1.9.4 will be interpreted as a time format modifier unless you put it into single quotation marks. Example of valid Cumulus 1 syntax: <#TtempH format="'at' hh: mm 'on' dd / mm / yyyy">.
- You can include HTML tags (but they cannot have any attributes because both single and double quote characters have defined meanings) and special characters as quoted text within the 'format' parameter.
Example of valid syntax: <#TapptempH format="'at 'h:nn' 'am/pm '<small>on' d/m/yyyy'</small>'">.
- See next sub-section for more information on incorporating HTML if you are using MX.
Note for MX - you can use single quotation marks round spaces and text (e.g. ' on '), but you can also use '\' as escape character (e.g. for 'on' use \o\n). However for at the only alternative is \a't' because the character t has another meaning and escape followed by a "t" i.e. "\t" becomes a tab!
Example using a class to change the look of part of the output
<#TapptempH format="dd' 'MMM' 'yyyy'<span class=\'xx\'> at 'HH:mm'</span>'">
the output from this will look like 04 Dec 2018 at 10:12
Note where the quotes are, and where you need to use '\' escape characters.
Example using HTML tags
<#RecentTS d=2 format="h:mm' 'tt'<small>on' d/M/yyyy'</small>'">
This puts the date in a smaller font than the time
Migrating from legacy to MX
If you have created any Cumulus template files, then every place in each template, where an output modifiers is used to specify a date and/or time format, has to be edited. For web tags it is much more complicated, simply because it is not just month we may be representing, and we might require only one specifier (being careful whether we use a standard or custom modifier) or we might want to specify a combination of modifiers (and we might want to add a space character or other literals). It is difficult to summarise, but here are some potential issues:
- the reserved characters are different in C1 and MX (affecting use of literals like "on" and "at" that appear in many English time-stamps)
- MX introduces the concept of escaping characters (a \ placed before a character can be either a control sequence or an instruction to display the character)
- MX is inconsistent e.g. format=d gives a different result depending on the tag it is applied to (e.g. the script conditional '<#metdateyesterday format=d>' == '<#yesterday format=d)>' will never be equal as the LHS returns a full date and the right hand side returns day of month only)
- in MX space in some cases may need to be within the single quotes containing other literals (as in MX space can change the interpretation of a modifier character).
Confused even more now? I'm not surprised, but maybe some examples will help before we actually list the available modifiers.
- Examples related to case selection
- In Delphi, "nn" means "minutes" for Cumulus 1, but "minutes" is "mm" for .NET or MONO in Cumulus MX.
- The hour in 24-hour format with leading zero, in non case sensitive Delphi (Cumulus 1) 'HH' or 'hh' would be treated as same, but in .NET or MONO it must be "HH" (Cumulus MX).
- The hour in 24-hour format without leading zero, in non case sensitive Delphi (Cumulus 1) 'H' or 'h' would be treated as same, but in .NET or MONO it must be "%H" (Cumulus MX).
- For 12-hour specifiers, please see the table, as this is far more complicated.
- You might be put off by references within .NET and MONO (Cumulus MX) to single/standard characters and custom modifiers, the following 3 examples may add clarity:
- For example, <#MonthTempHD format="d"> is a single character format modifier, therefore the 'd' acts as a standard modifier, and causes for a date of 22 July 2014 for the highest temperature in the month to be returned in the standard short date format e.g. '22/07/2014' (exact contents for any one date vary by locale).
- Similarly, <#MonthTempHD format="M"> is a single character format modifier and therefore the 'M' acts as a standard modifier and causes the date for the highest temperature in the month to be returned in the standard day and month format e.g. '22 July' (exact contents for any one date vary by locale).
- Whilst <#metdate format="d M"> is not a single character format modifier and therefore both the 'd' and the 'M' are interpreted as custom modifiers and cause the current date to be returned as a digit(s) for the day and a digit(s) month (in a without leading zeroes format) e.g. '6 7' would be returned for 6 July.
- Alternatively, <#MonthTempHD format="%d"> is NOT a single character format modifier, therefore the 'd' acts as a custom modifier, and causes a date of 22 July 2014 for the highest temperature in the month to be returned as the day of the month only '22' in all locales.
- Similarly, <#MonthTempHD format="%M"> is NOT a single character format modifier and therefore the 'M' acts as a custom modifier and causes the same date for the highest temperature in the month to be returned as the month number '7'.
In both Cumulus 1 and MX if you want a space character within your output, the output specifiers must be enclosed in double quotes. If that space character is next to a non modifier (e.g. around word "at") then the single quote needing to surround the at should be widened to include the spaces in MX, but Cumulus 1 does not care if single quotes excluded spaces. However, with MX, single quotes enclose multiple characters, but there is an alternative way to deal with some single verbatim characters to cover next.
So let us compare these two alternative ways that MONO and .NET escape any characters that are not being used as format specifiers.
- In Delphi you can put the 'verbatim' characters inside single quotes (Cumulus 1); this is often used to (in English) include words like ' on ' and ' at ' in the formatted output.
- in .NET or MONO you can still use single quotes (as mentioned above extended to include adjacent spaces),
- but alternatively you can escape each verbatim character with a backslash as prefix (Cumulus MX).
- You may need to use both single quotes and back slashes in some format specifiers, depending whether the characters you want to include can be interpreted as control characters (yes, backslash is also used to escape control characters, so backslash will NOT work for some characters such as those in "on" and "at" [\n will produce new line not the letter n, \t will produce a tab not the letter t]), consequently for some characters you must use the literal approach to include them in your format.
Past history for this page
This page is a complete redesign of how to present information that was previously on the Webtags page, so look there for past content by selecting "history" tab.
Trying to make the old design made for the original Cumulus software, work for MX which is now very different, made the old page unwieldy.
Steve Loft published a table showing comparison between output date modifiers for Cumulus 1 and MX at Cumulus MX forum. The table there was based on the table that was originally created when only the original Cumulus existed.
The subsequent comments in the forum suggested his layout got people confused. Most of that confusion came in two circumstances:
- When someone wanted to use one date or time modifier on its own
- When someone who had been using Cumulus 1 swapped to MX and wanted to replace a combination of output modifier characters
That all comes from the fact that when a MX modifier consists of a single character it can mean something different to when it appears with other characters. In Cumulus 1, "m" or "M" meant something different when it was combined with "H" or "h" (when it represented minutes), but in all other contexts it represented month. But for Cumulus 1, there is no other case where it matters what context a modifier is put in by the use of other modifiers, and no other modifier takes more than one meaning.
In MX it is much more complicated, to take a few examples "D", "H", "M" represent different items on their own to what they represent when combined with other characters. That other character can be as simple as a space or a "%" which modify the meaning of the character.
Looking at the tables, now included above, you can see "G" is used on its own because it represents a full date-time specifier. "D" is similarly used on its own represents the long date format. If we only want the day of month number we must use "%d" to avoid the meaning of short date format that "d" on its own represents. If we want the typical Cumulus date-stamp of day of month number and month "d M" and "M" will both work because "M" has a different meaning on its own and with another modifier.
Hopefully, the way that information is now presented on this page makes any use of parameters for web tags much easier now.