Webtags/Parameters (preserving history): Difference between revisions

This page is about parameters used for modifying Cumulus web tags. All this information was originally on [[Webtags]] page, but has been moved to this separate page as part of an attempt to make the Wiki easier to read by shortening pages.

A [[Cumulus template file|'''Cumulus Template File''']] was the name given by Steve Loft to any files that contain web tags. Each of those files need to be processed before they actually include values:

* For Cumulus MX, there is only one Cumulus template file, the web tags that supply values to the various tables in the [[New Default Web Site Information|Default Web Site]] are stored in [[websitedataT.json]] template file.

* Otherwise MX avoids using template files that can be edited, instead the code itself internally generates most of the data files that are sent externally.

[[File:Badge vMx.png]]Cumulus MX also differs from the legacy software in that tag names, with the parameters described on this page, ''can be used in several new places'' including within [[Cumulus_MX_Local_API|Cumulus MX Local API]], [[Cumulus.ini#Optional_Structured_Query_Language_Settings|"My SQL Connector"]], and [[Cumulus.ini_(MX_3.0.0_to_3.7.0)#MQTT|MQTT]]. Most of those web tags use the default output format, but a few use some of the [[#Output modification parameters]] listed below. To customise the default web site, you might want to edit '''websitedataT.json''', by using information found on this page.

[[File:Badge vMx.png]]If you are using MX:

[[File:Badge vMx.png]]From release 3.12.0, you can set the default number of decimal places to output for all derivatives of temperature, pressure, etc. by [[Cumulus.ini#Units.2C_Derivative_Options.2C_and_Decimal_Places|advanced settings]]. Those settings can force output as integers, stopping these modification parameters from working.

As handling of each web tag is coded individually, the number of decimal places output by default in any web tag might vary slightly from the above default.  As Cumulus has been developed, people have commented that these defaults do not reflect the precision of their instrumentation (weather stations used with Cumulus tend not to have the accuracy of those used by meteorologists, or are not re-calibrated as often).  

[[File:Badge vMx.png]]From release 3.10.5 (which did a big rewrite of web tag handling), you can modify real number output for individual tag names, using output modification parameters in either of the following formats:

[[File:Badge vMx.png]]This output format modifier is only available in MX.

[[File:Badge vMx.png]]For MX running on most operating systems (and therefore using Mono),  type <code>locale</code> to see the default locale that will be adopted when mono-complete is installed as MX will, by default, take locale setting from Mono. When you start MX, you can ask it to use a different locale to that picked up by Mono, by adding the parameter "-lang locale-code", see examples at [[MX_on_Linux#Parameter_for_changing_Locale]].  For example, the Australian English language with UTF-8 encoding locale is defined as: en_AU.UTF-8.

[[File:Badge vMx.png]]However, for MX only, you can use a script to convert a time to UTC. This is not the place to tell you how to write the script, but taking time of highest pressure today as an example, you would use <#TpressTH format=Hh:mm> and <#TpressTH format=zzz>, the first gives hours and minutes in your local time, and the second gives the offset that needs to be applied to that time to convert it to UTC.

For Cumulus MX output formatting,  the date and time modifiers are complicated by the fact that ''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 with another modifier (custom format).  One more confusion, Microsoft have reversed the use of capital 'M' and lower case 'm' from the standard used very widely, and you may have got to know.  '''Sounds confusing?''' Well it is complicated.

[[File:Badge vMx.png]]You need to add quotation marks to the output format specifier if spaces are present. You also may need to add "%" or "space" before the first modifier within the double quotation marks, as without it you may get an unwanted format!

[[File:Badge vMx.png]]The first complication is that the parser that interprets time/date characters has two ways of interpreting a space character, depending on what immediately follows.  In the tables, below, I have used a "%" in various places. In any of those places with a "%", you can insert a space instead,  understanding that space is not a gap between characters, but an alternative to "%".  I discuss this later in [[#Migrating from legacy Cumulus 1 to MX]] section.

 

If we have single character specifiers, then a space has to be enclosed in single quotes to mark it as a literal, not a modification of the subsequent single character. To explain this, a simple example is '''<#MonthPressHD format=" d' 'M">''', in this example the "space" before "d" is

treated as same as "%", but since the month number is a single character "M", the space before it can only be treated as a "space" if we treat it as a literal by enclosing the space character in single quotes and the whole specifier in double quotes.   

Finally, the use of literals can cause you ''a problem if you want to use a date/time specification in a script'' because the script wants literal delimiters outside any web tags, so that delimiters remain when the web tag itself has been processed into a string by Cumulus.  This means the type of quotes (single or double) used outside the web tag, cannot be used within the web tag. The complicated sounding (but actually simple solution) is to avoid placing literals, and/or spaces, within any output format specifier, instead put single quotes round the whole content. What you thought of putting as literals within any web tag is instead typed outside with separate web tags for the part of the specification before and after each literal. An example to make this clearer is <code>$MXDateTime = '<#date format=yyyy-MM-dd>' . 'T' . '<#time format=hh:mm:ss>';</code>, which is written in PHP Hypertext pre-processor format, the literal 'T' has been inserted by using two separate web tags surrounding the literal.

 

The table below is the definitive guide to how to ensure you do specify just the day part of any date specifications.   

As for month above, the short day names that are generated depend on your locale, so you might see additional punctuation defined for abbreviated names in some locales (e.g. 'Wed.').

If you are in the USA, Cumulus will only use your month first date internally for the start date (see [[Cumulus.ini (Cumulus 1)]] and [[Cumulus.ini|Cumulus.ini (Cumulus MX)]]), that format will not be used in any files in the [[Data folder|'''data''' sub-folder]], but you can see your preferred format in the settings pages, in the extreme record editing pages, and by default as an output from many (not all) web tags.  For any web tags that do permit use of output date modification format parameters, you can can combine any month specifier, with any day of month specifier, in that order, to get an output where the month appears first (see example in table below).  

<big>Please could an American contributor please check if the "M" modifier works for their locale as shown and update the table below if necessary, and edit this comment into a confirmation</big>.

Short date format e.g. '22/03/2019' (British Locale) produced in MX by either of these:

Here context matters, so both standard (single character) and custom (two or more characters) formats are shown in the following table.  As explained earlier, time formats can be used with both time-duration reporting and clock time reporting.