Cumulus Wiki

Webtags/Parameters (preserving history): Difference between revisions

Page Discussion

Webtags/Parameters (preserving history) (view source)

Revision as of 15:12, 3 June 2022

2,627 bytes added ,  3 June 2022
m
Make legacy/MX differences clearer by identifying MX specific items
m (removed unwanted space/new line)
m (Make legacy/MX differences clearer by identifying MX specific items)
=Introduction=
 
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''']] iswas 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 these template files that can be edited, instead the code itself internally generates most of the data files that are sent externally.
* The legacy Cumulus 1 software, and MX releases up to release 3.9.7 - build 3107, used lots of template files (see [[Customised templates]].
 
For[[File:Badge vMx.png]]Cumulus MX, therealso isdiffers stillfrom onethe Cumuluslegacy software in that templatetag filenames, with the webparameters tagsdescribed thaton supplythis valuespage, to''can thebe various tablesused in theseveral [[Newnew Defaultplaces'' Webincluding Sitewithin Information[[Cumulus_MX_Local_API|DefaultCumulus WebMX SiteLocal API]], are[[Cumulus.ini#Optional_Structured_Query_Language_Settings|"My storedSQL inConnector"]], and [[websitedataTCumulus.jsonini_(MX_3.0.0_to_3.7.0)#MQTT|MQTT]] file. 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.
 
To set context, let us learn the terminology with cross-references to where those features are explained further.
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 [[Webtag_Applicability|discussion about applicability]], but that needs updating as it does not specify dependencies for individual [[Webtags|web tags]].
 
[[File:Badge vMx.png]]If you are using MX:
* if your locale specifies that integer and decimal parts of real numbers are separated by a comma, there is an output 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
Cumulus is written to assign particular numbers of decimal places to any outputs it makes, and in any logging of current, or extreme values (for day or longer periods). It determines these precisions, by reference to the units chosen for outputs.
 
[[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 recalibratedre-calibrated as often).
 
This section (and its subsections) only applies to tag names that output real numbers (with integer and decimal parts). You can't change anything that is output as an integer, or is text with these parameters, nor can you change the decimal places for any time element.
===Two Output (format modifier) parameters for decimal places===
 
[[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:
* <tt><#tag_name dp=i></tt> and
* <tt><#tag_name tc=y></tt>
====Truncation of unwanted decimal places====
 
[[File:Badge vMx.png]]This output format modifier is only available in MX.
 
<tt>tc=y</tt> is the truncation parameter, the attribute '''tc''' takes the value 'y' to remove decimal places by truncation. e.g. <#MoonAge tc=y>.
The effect of some output format modifiers is also dependent on locale.
 
[[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.
 
The available locales on your computer in Linux are listed by <code>locale -a</code>. For example, the Russian locale would be selected as the one your computer uses ''for the current session only'' by using <code>LANG=ru_RU.utf8</code> either typed into a terminal session before you start MX, or used as a parameter (preceded by "-") as you start MX interactively.
Although Cumulus 2 internally stored all date/times in UTC, no flavour of Cumulus is currently able to output the time-stamp for any weather extreme in UTC, if your current time is not in UTC.
 
[[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.
 
===Time resolution===
The [[:Category:MX txt Files|*.txt Files]] have so far stuck to date formats as used in the legacy definitions, the intention to swap to ISO format for the .txt files from September 2020, having been postponed to an unannounced future date, because of the continuing need for compatibility while there is use of the legacy software by a significant number of users.
 
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.
 
Consider context first:
There are multiple symbols for specifying dates and times, and you might want spaces to appear between symbols in that output format.
 
[[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!
 
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, a space is not a gap between characters, but an alternative to "%". I discuss this later in [[#Migrating from legacy Cumulus 1 to MX]] section.▼
 
▲[[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.
For a space character to be interpreted as a gap between symbols, the symbol that follows the space must include at least two characters. The syntax <code><#tag_name format="x y z"></code> works if the y and z in it are representing multi-character symbols. To explain this, an example is '''<#TpressTH format="h:mm tt">''' as both ''h:mm'' and ''tt'' are multi-character symbols, we have inserted a space after the minutes.
 
If''For wea have singlespace character specifiers,to thenbe interpreted as a spacegap hasbetween tosymbols, bethe enclosedsymbol inthat singlefollows quotesthe tospace markmust itinclude asat aleast literal,two notcharacters.'' aThe modificationsyntax of<code><#tag_name format="x y z"></code> works if the subsequenty singleand z in it are representing multi-character symbols. To explain this, a simplean example is '''<#MonthPressHDTpressTH format=" d'h:mm 'Mtt">''', herein thethat monthexample numberthe istwo aspaces singleare characterinterpreted "M",in sotwo todifferent insertways! theThe "space" webefore have"h" tois treat ittreated as athe literalsame byas enclosing"%", but as the space''tt'' are multi-character insymbols, singlethat quotesdoes andmean theinsert wholea specifierspace inafter doublethe quotesminutes.
 
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.
 
Literals are discussed fully in the [[#Including literals in format parameters]] sub-section later. If we want to include other characters not to be interpreted by the date time parameter parser, and spaces, then both double and single quotes must be used, and the spaces must be within the single quotes. An example, that shows all the options that MX allows, with literals is <code> <#TpressH format="\a't 'h:mm'&nbsp;' tt' <nowiki><small>on 'd/M/yyyy' </small></nowiki>'"> </code>.
 
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 preprocessorpre-processor format, the literal 'T' has been inserted betweenby using two separate web tags surrounding the literal.
 
===Year formats===
**The output you get will depend on the language defined in your locale
**In English locales, the output will be in the range "January" - "December"
 
[[File:Badge vMx.png]]'''CAUTION:''' Cumulus MX has yet another complication, a web tag can return different months depending on whether the output modifier for month is used with or without an output modifier for day. Take two examples <code><#metdateyesterday format=yyyy-MM-dd></code> and <code><#metdateyesterday format=yyyy-MM></code>, these can produce different months when processed by MX on same day at near enough same time! Let us assume the first is reporting (in a particular year) the first day of June, the second would in that case report the same year, but could report the month of May!
 
{| class="wikitable" border="1"
|-
All locales offer both numerical and alphabetical formats for representing a day.
 
[[File:Badge vMx.png]]Again, there are extra complications with MX, the "d" modifier is inconsistent, the format it returns depends on which tag name it is used with - see [[#Date formats]] table later! For some tag names it returns just "day of month" (like "%d", for others it returns the full "Short date format" (like "ddddd")!
The table below relates just to the day part of any date specifications. ▼
 
▲The table below relatesis justthe definitive guide to how to ensure you do specify just the day part of any date specifications.
{| class="wikitable" border="1"
|-
|ddd
|Displays the day as an abbreviation (in UK English will output Sun-Sat) using the strings appropriate to the Locale.
 
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.▼
|'Wed' produced by <#metdate format="ddd"> (English locale)
 
▲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.').
|-
|dddd (4 characters long)
[[#Locales]] will define a '''Short Date Format''' and a '''Long Date Format'''. You will see references to those in the table below explaining available output format modifiers, for example the single character output format modifier ('''G''' or '''c''') listed at the start of the table below.
 
If you are in the USA, Cumulus will notonly use your month first date internally orfor 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 asanin the settings pages, in the extreme record editing pages, and by default as an output from many (not all) web tags,. as For any web tags that do permit use of output date modification format parameters, you can can combine theany month specifier, with theany 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>.
{| class="wikitable" border="1"
|-
| [[File:Badge vMx.png]] '22' returned by e.g. <#yesterday=d>
 
Short date format e.g. '22/03/2019' (British Locale) produced in MX by either of these:
* [[File:Badge v1.png]]<#metdate format=ddddd>
* [[File:Badge vMx.png]]<#metdateyesterday format=d>
===Time formats===
 
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 durationsboth time-duration reporting and clock timestime reporting.
 
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. <tt><#LastDataReadT format="h:nn am/pm"></tt>
Sfws
5,838

edits

Retrieved from "https://www.cumuluswiki.org/a/Special:MobileDiff/10462"