5,838
edits
Webtags/Parameters (preserving history): Difference between revisions
Webtags/Parameters (preserving history) (view source)
Revision as of 20:11, 22 June 2022
, 22 June 2022Corrections
m (Make legacy/MX differences clearer by identifying MX specific items) |
m (Corrections) |
||
|
=Introduction=
Put simply, a [[Webtags|Cumulus tag]] is included to indicate where Cumulus should insert values when it [[Customised_templates#What_is_meant_by_.27Cumulus_processes_templates.27|processes the command/file]] that quotes the tags.
The general format for every Cumulus tag is: <code><#tag_name [optional input selection parameters] [optional output modification parameters]></code>
This page is about those (generally optional) parameters used for modifying Cumulus tags.
# An input parameter is used where the same tag name 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 a tag name and input modification parameter lets Cumulus select the value you want to see.
#* Whether a particular tag name can use input modification parameters will depend on both which tag name has been chosen, and which Cumulus release you are using.
# An output parameter is used when a particular tag name can be fed through a process that alters how the output is shown
#* Tag names representing integer values cannot have their output format modified
#* Internally Cumulus handles numbers in binary, for numbers that have an integer and a decimal part, there is no exact conversion between the way the decimal part of a number is stored in binary, and the way the decimal part (after the decimal comma/point) appears on output. Therefore, non-integer numbers have to be rounded, and there are some output parameters that modify the output:
#*# You can modify the number of decimal places shown for some tag names
#*# With Cumulus MX, you can modify whether number is output with a decimal comma, or a decimal point
#* Tag names representing time intervals, clock times, [[meterological day|dates]] or representing both time/date for an extreme record, may have a fixed format that cannot be changed, or may be able to be processed through a date-time routine that changes how either time or date or both are output
All this parameter 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.
=Legacy software=
The legacy Cumulus 1 software can only use tag names, and whatever parameters are permitted, within a file. Steve Loft used [[Cumulus template file|'''Cumulus Template File''']] for a file that used tags:
* The legacy Cumulus 1 software, and MX releases up to release 3.9.7 - build 3107, provided a selection of template files (see [[Customised templates]] that produced 'standard' web pages, see [[Cumulus.ini_(Cumulus_1)#Section:_FTP_site|"IncludeSTD" here]].
* A Cumulus user could specify an alternative [[Customised_templates#HTML_5_-_a_very_quick_guide_to_structure|web page]],
* A Cumulus user could transfer data to a web server using a [[Php_webtags#Option_3:_JavaScript_Object_Notation|JavaScript Object Notation (.json) file]]
* A Cumulus user could transfer data to a web server using a [[Feels_Like#HTML_code_to_translate_web_tags_to_JavaScript_variables_.28as_modified_for_additional_parameters.29|JavaScript file]],
* A Cumulus user could transfer data to a web server using a [[PHP]] script file, or
* A Cumulus user could transfer data to a web server using a [[Xml_webtags|eXtensible Mark-up Language (XML)]] file.
For information on how to process, and upload, non-standard files, see [[Cumulus.ini_(Cumulus_1)#Section:_FTP_site|"ExtraProcessxx"]].
=Cumulus MX software=
MX can process template files, using [[Cumulus.ini#Extra_Web_Files|Extra web file settings]], but tag names (and input/output parameters as permitted) can also be used in:
* standard [[websitedataT.json]] template file, or a tailored file that is processed into same destination file
* on demand using [[Cumulus_MX_Local_API|Cumulus MX Local API]]
* standard or custom interval use of [[Cumulus.ini#Optional_Structured_Query_Language_Settings|"My SQL Connector"]]
* Customised [[Cumulus.ini_(MX_3.0.0_to_3.7.0)#MQTT|MQTT]] commands
=Rules=
Tag names and parameters must obey certain rules.
The tag_name in the general format above is case sensitive, so please type the tag name exactly as shown in lists of tag names.
== Case sensitivity for parameters ==
The optional input modification parameters always use lower case, so please type them exactly as shown in the [[#Input modification Parameters|section below]].
The content of optional output parameters are
== Tag names and Parameters available==
=== Input modification Parameters ===
'''Most web tags do not require any input parameters'''. Luckily, where they are needed, it is quite simple to use them, see table below.
{| class="wikitable" border="1"
! scope="row"| Tag names listed at [[Webtags#Table of Recent History tag names available|'''Table of Recent History tag names available''']] (see [[Recent history]] page for explanation)
| One value for each minute in last 7 days
| * '''d''' specifies number of days ago,
* '''h''' specifies number of hours ago,
* and '''
* You can use any combination of the three parameters.
* The same d, h, and m, parameters are used by Cumulus 1 and MX.
| Examples for outside temperature:
* <#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 (or whatever tag name you have quoted) 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.
|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''.
* '''Beware: If you use <code><#RecentRainToday d=2></code> remember that rainfall can accumulate during a day, so "d=2" returns an estimate of the rain between rollover 2 days ago and the same time as now 48 hours ago, it does not return the total rainfall 2 days ago!
! scope="row"| [[Webtags#Monthly_All_Time_Records|'''monthly all-time extreme records''']] tag names
| These tag names represent extreme record values (and corresponding time-stamps) for any particular month (1 =January, and so on, to 12 =December) in all years
| Optional input parameter is '''mon=N''' where N is the index of the month in which the extreme record occurs considering all years
| Cumulus 1.9.3 beta build 1033 (remain available in MX)
| * <#ByMonthDewPointH mon=3> is highest monthly dew point for
* <#ByMonthTempH mon=3> gives highest temperature in any March, <#ByMonthTempHT mon=3> gives the date and time for that highest temperature
| * If you don't supply an input parameter (or supply an invalid value like zero) the current month will be used.
* The value of "N" supplied should be an integer between 1 and 12
*
'''NOTE:''' Use without an input parameter
|-
! scope="row"| [[Webtags#Monthly|Only <#SunshineHoursMonth>]] and [[webtags#Yearly|Only <#SunshineHoursYear>]]
| Values available for current month/year, and for past month/year
| Omit input modification parameter to get value for current month/year. Alternatively include one of the following options:
* '''r=-ww''' (note minus sign and up to 2 digits) representing that number of months/years ago
*
* Yearly tags also take: '''y=nnnn''', this parameter specifies exact year required
| MX release 3.12.0
| Monthly examples:
|}
=== Output modification parameters availability by tag name ===
Each tag name falls into one of these 3 types:
* Some tag names have a fixed output format (so they ignore any output format parameters, although obviously better not to specify any)
* Some tag names always need an output format specifier
* The majority of tag names have a default output if there is no output format modifier, but accept either one or two output format parameters, allowing you to change what they output.
This Wiki page does not include a table showing which tags belong to which type, simply because it is dependent on which Cumulus release you are running. An attempt to indicate some general guidance has been included on another [[Webtag_Applicability|discussion about applicability]] Wiki page, but contributors need to update that page and start listing tag name and release specific information.
===Output modification parameters available in legacy Cumulus 1===
Your options are described under the following subheadings:
* [[#Rounding to a specific number of decimal places]]
* [[Multiple Output Format Modifier parameters for times and dates]]
===Additional output modification parameters that are only available for MX users===
[[File:Badge vMx.png]]
* [[#Output Modification Parameter for changing any decimal comma into a decimal point]]
*
* [[#Two Output (format modifier) parameters for decimal places]]
* [[#Truncation of unwanted decimal places]]
=Documentation for Output modification parameters=
Use the links above to skip to the particular parameters that you wish to use.
==Output Modification Parameter for changing any decimal comma into a decimal point==
Note that Cumulus software never uses a comma for separating off thousands, and there is no way to make it output numbers above 999 with a space or comma to separate out thousands.
If the tag name represents a real number with integer and decimal parts, then Cumulus by default will output that number using whatever your locale defines as the separator character (decimal comma or decimal point). The legacy Cumulus 1 provided a few derivatives where a prefix of "RC" before tag name as in <code><#RCtag_name></code> could force the output to use a decimal point (regardless of locale), that option remains available in MX for forward compatibility.
In Cumulus MX (only), you can alternatively use an output modification parameter in format <tt><#tag_name rc=y></tt> to select whether the output should use decimal comma or decimal point:
*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 <tt><#tag_name rc=n></tt> became also possible, to ensure decimal comma shown when locale specifies it
{| class="wikitable" border="1"
|-
'''Why would you want to remove decimal commas?''' Well because the JavaScript language (and some other languages) cannot understand decimal commas, and MX has several scripts written in this language, equally some third party alternative web pages rely on ajax to update them (and Ajax uses JavaScript).
==Controlling the number of decimal places==
If the tag name represents a real number (with both integer and decimal parts) then there are a number of ways to control the number of decimal places:
* [[File:Badge v1.png]]Cumulus 1.x.y: <tt>dp=i</tt> rounds output to number of decimal places specified by "i"
* [[File:Badge vMx.png]] All MX releases: <tt>dp=i</tt> rounds output to number of decimal places specified by "i"
* <tt><#tag_name tc=y></tt> truncates output, display as integer, no rounding, simply ignoring all decimal places
If the tag name gives an output that is defined as text, or as an integer, then none of these can be used. It depends upon which release you are using whether a particular "real number" tag name will accept any of the above output modification parameters, 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.
Internally, Cumulus stores numbers in binary. You cannot represent base 10 decimal places exactly in base 2.
Weather stations report [[Calculate_Missing_Values#Source_value|values]] as integers. Cumulus converts these to the user's desired units, and that processing can add decimal places, as it may involve division by a factor of 10, or multiplication by a conversion factor. Obviously, the sensor has a particular accuracy, and this conversion process can introduce additional errors, as can the storing in binary, Cumulus generally (not in every case) stores to a precision that would generally give about 24 significant figures when expressed in base 10.
[[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, in which case the parameter for controlling number of decimal places have no effect.
===Two Output (format modifier) parameters for decimal places===
Depending on tag name and release you are using, there may be two ways to control decimal places:
* <tt><#tag_name dp=i></tt> and
* <tt><#tag_name tc=y></tt>
====Rounding to a specific number of decimal places====
Use <tt>dp=i</tt> (the value '''i''' following the attribute '''dp''' is an integer, it represents how many decimal places you want for the output you see):
* [[File:Badge v1.png]]Cumulus 1.x.y: only <tt><#latitude dp=i></tt> and <tt><#longitude dp=i></tt> are able to be output with "i" denoting number of decimal places, e.g. <#latitude dp=5> gives "59.24250".
* [[File:Badge vMx.png]] Depends on MX release:
*# From beta releases (3.0.0) onwards, <tt><#latitude dp=i></tt> and <tt><#longitude dp=i></tt> 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"
*# From release 3.10.5 (which did a big rewrite of web tag handling) any tag names that output as real numbers
====Truncation of unwanted decimal places====
<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>.
[[File:Badge vMx.png]]This output format modifier is only available in MX:
* If you are using an early release of MX, you will need to research whether this is available for particular 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 ==
Output modification parameters for times and dates are highly complicated!
To start with a simple example, suppose you want date/time in ISO 8601 format:
# Take the tag name (from tables on [[Webtags]] page)
# Next check in [[#Which tag names take date/time output formatting modifiers]] to see if that tag accepts both time and date modifiers
# If
# To explain each element in that format value, look in [[#Time formats]], [[#Year formats]], [[#Month formats]], [[#Day formats]], [[#Use of spaces]], [[#
Should you want a different date/time format, then the sub-sections just referenced should help you to select a different arrangement, although there are some more options in [[#Date formats]].
===Which tag names take date/time output formatting modifiers===
There are a few time-related tag names labelled as being fixed format, that means any time/date output modifiers you might try would be ignored.
Some tag names, although it can be hard to tell which, report durations. You can use time modifiers to change how these are reported. Examples include '''<#daylength format=H:mm:ss>''' which reports day length and '''<#MonthDailyRainHD format=H:mm>''' which reports how much of a day it was raining.
Time modifiers can also be used to change the way that clock times are reported, you might only want the hour, or you might (if resolution is available) want to also see seconds. The [[webtags]] page has columns headed "Time" to clearly identify all tag names that report clock times.
There are some tag names (e.g. moon rise) that relate to an event that does not happen each Earth day, so those tags have to be able to report "--:--", and you cannot modify their output. Equally, many of the tag names that describe extreme records for this month/year/all-time are not defined until the respective period reaches its second day, so again those tags may output hyphens and so any modification parameters will be ignored. For example, highest temperature range in month/year has been coded in Cumulus to report "--" for value, and "--:--" for time, on the first day of that period (because there is only a partial day to consider you might not yet have experienced a true maximum and a true minimum), so modifying the time output can only be done on subsequent days.
It is not practical to indicate which time/date modifiers are accepted on a tag by tag basis. It would involve a lot of repetition. Instead, the following table, explains much more simply, which web tags will accept time and/or date output modifiers:
|-
! scope="row"| [[Webtags#Monthly]], [[Webtags#Yearly]]
|
| Any tag name in "Date" column of linked table in first column that represent either daily extremes or spot value extreme records. For notes see † below this table
| None of the tag names. For explanation see the ^ below this table
|-
! scope="row"| [[Webtags#All_Time]], [[Webtags#Monthly_All_Time_Records]]
| None (all tag names combine both time and date)
| Those tag names in "Date/Time" column of linked table that represent daily extremes
|
|-
! scope="row"| [[Webtags#Davis]]
| None
|}
~ For rainfall, only '''<#LastRainTip>''' can have output modifiers added to report a clock time.
† Daily extremes (e.g. wettest day <#MonthDailyRainHD>, and temperature ranges <#MonthHighDailyTempRangeD>) have no time tag.
^ For the monthly and yearly web tags, the date and time are in separate tag names. It is not possible to get both time and date out of either tag name.
===Locales===
The effect of some output format modifiers is also dependent on locale.
For Microsoft Windows Operating Systems, a Language is defined within the "Region" page of the Settings app. That should be sufficient for the legacy software that uses Delphi. However for MX date and time formats within Windows Operating System, you must use the older '''Control Panel''' (go to "Clock and Region" screen, choose "Change date, time or number formats", choose "Language preferences") because it is only there that you can adjust all the defaults used by .NET.
[[File:Badge vMx.png]]For MX running on most operating systems (other than Microsoft Windows), 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#Parameters]]. 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.
For permanently changing the locale used by your system, the instructions vary considerably according to the kernel used in your operating system, so you need to look up the instructions for yourself. However, if you have a graphical user interface, such as the full Raspberry Pi Operating System provides, you might have a configuration command in terminal mode and a configuration app accessed (within ''Preferences'') from the "Raspberry" key on the official keyboard. For the Raspberry Pi, please read [[Raspberry Pi computer page]] for more details.
===Time zones===
All web tag outputs are in local time, except '''<#timeUTC>'''.
[[File:Badge vMx.png]]
===Time resolution===
For the legacy software, there may be no point in asking for seconds, as Cumulus 1 did some actions at one minute intervals. For MX, it depends on which tag name you are using whether it supports seconds (e.g. <#LastDataReadT> supports seconds, but <#LastRainTip> is reported rounded back to previous minute and <#TrrateTM> is reported rounded forward to the next minute).
If Cumulus obtained archive data, as part of the catch-up process it can do when it restarts, any time-stamps for that historic period can only be the time of a particular archive record, so that might be every half an hour, but not aligned precisely with hour changes.
===Dependency on Cumulus flavour===
You
All the tables explaining
====For the legacy software====
*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).
===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 both time-duration reporting and clock time 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>
{| class="wikitable" border="1"
|-
!style="width:150px" | [[File:Badge v1.png]]Delphi Specifier for Cumulus 1.9.x
!style="width:150px" | [[File:Badge vMx.png]]Mono/.NET Specifier for Cumulus MX
!style="width:600px" | Displays
!style="width:600px" | Example
|-
|h
|%h
|Displays the hour (12 hour clock) without a leading zero (1-12)
| 7
|-
|h ''AM/PM''
|%h ''tt''
|Displays the hour (12 hour clock) without a leading zero (1-12) in combination with AM/PM.
[[File:Badge v1.png]]For Cumulus 1 the formats for am/pm depend on the case in which you type the parameter as shown later in this table
[[File:Badge vMx.png]]What "tt" produces depends on locale settings for your device, it might be capitals or it might be lower case (in Windows use Control Panel, not Settings app, to get to these regional additional settings).
| [[File:Badge v1.png]]7 PM
|-
|h:nn [''AM/PM'']
|%h:mm [''tt'']
|Displays the hour (using 12 hour clock) without a leading zero (1-12) followed by 2 digit minutes [optionally in combination with AM/PM whose case varies as explained in previous entry].
[[File:Badge v1.png]]For Cumulus 1, the minutes can be represented by 'mm' (instead of "nn") only when appearing in combination with 'h'
|'10:27 am' produced by [[File:Badge v1.png]] <#LastDataReadT format="h:nn am/pm">[[File:Badge vMx.png]] <#LastDataReadT format="h:mm tt">
|-
|H (or ''H'')
|%H
| Displays the hour part of any duration or clock time, without a leading zero (0-23).
[[File:Badge vMx.png]]Note that '%' before the "H", this makes it a custom modifier, needed because H is on its own.
|7 produced by
* [[File:Badge v1.png]]<#daylength format=H>
*[[File:Badge vMx.png]]<#daylength format=%H>
|-
| H:mm (or ''H:nn'')
| H:mm
| Displays the hour part of any duration or clock time, without a leading zero (0-23) followed by 2 digit minutes for that duration or clock time.
|'6:27' or '17:49' produced by <#LastDataReadT format="H:mm">
|-
|HH (or ''hh'')
|HH
| Displays the hour part of any duration or clock time, using 24 hour clock with a leading zero (00-23).
|'06' or '17' produced by <#LastDataReadT format=HH>
|-
|hh [''am/pm''][''AM/PM'']
|hh [''tt'']
| Displays the hour part of any duration or clock time, (12 hour clock) with a leading zero (01-12) [optionally, if it is a clock time, in combination with am/pm].
[[File:Badge v1.png]]For Cumulus 1, two optional terms are shown because the case output for the optional 'am/pm' depends on the case used for that parameter
[[File:Badge vMx.png]] For MX, the optional 'tt' displays the contents of the device locale setting for AM string for midnight until any hour before noon, and the contents of the PM string for noon or any hour after noon but before midnight.
|'07 am' produced by
* [[File:Badge v1.png]] <#LastDataReadT format="hh am/pm">
*[[File:Badge vMx.png]] <#LastDataReadT format="hh tt"> if locale specifies lower case
|-
|hh:mm (or ''hh:nn'' or 'HH:NN') [''am/pm''][''AM/PM'']
|hh:mm [''tt'']
| Displays the hour part of any duration or clock time, (12 hour clock) with a leading zero (01-12) followed by 2 digit minutes [optionally, if it is a clock time, in combination with am/pm].
* [[File:Badge v1.png]]For Cumulus 1, the minutes can be represented by 'mm' only when in combination with 'h', in other contexts 'mm' is interpreted as month number, two optional terms are shown because the case output for the optional 'am/pm' depends on the case used for that parameter
*[[File:Badge vMx.png]] For MX, the optional 'tt' displays the contents of the device locale setting for AM string for midnight until any hour before noon, and the contents of the PM string for noon or any hour after noon before midnight
|'8:27 am' produced by
* [[File:Badge v1.png]] <#LastDataReadT format="h:nn am/pm">
*[[File:Badge vMx.png]] <#LastDataReadT format="h:mm tt"> if locale specifies lower case
|-
|n
|%m
|Displays the minutes of any duration or clock time, without a leading zero (0-59).
[[File:Badge vMx.png]] As other examples show, the % is only needed when "m" is on its own.
| 7 produced as a duration in minutes by
* [[File:Badge v1.png]]<#daylength format=n>
*[[File:Badge vMx.png]]<#daylength format=m>
|-
|nn
|mm
|Displays the minutes of any duration or clock time, with a leading zero (00-59).
|'07' produced as a duration in minutes by
* [[File:Badge v1.png]]<#daylength format=nn>
* [[File:Badge vMx.png]]<#daylength format=mm>
|-
|s
|%s
|Displays the seconds for any duration or clock time, that has resolution to less than a minute, without a leading zero (0-59).
[[File:Badge vMx.png]] As other examples show, the % is recommended when "s" is on its own, although I have not found any alternative meaning for "s" on its own.
| 9 produced by <#metdate format=s>
|-
|ss
|ss
|Displays the second with a leading zero (00-59).
|'06' or 19 produced by <#LastDataReadT format=ss>
|-
|z
|FFF
|Displays the millisecond without a leading zero (Cumulus 1: displays 0-999, Cumulus MX: displays either nothing, or displays 1-999, so don't write any code that assumes the MX output is numeric).
Note that the system clock (before Windows 10 64-bit systems) only has precision to 15 ms, so don't use this modifier if your Cumulus is running on an old version of Microsoft Windows.
|
|-
|(not available)
|ff (or ''f'')
|Displays hundredths of a second (or tenths) with leading zero(s)
|
|-
|zzz
|fff
|Displays the millisecond with a leading zero (000-999).
Note that the system clock (before Windows 10 64-bit systems) only has precision to 15 ms, so don't use this modifier if your Cumulus is running on an old version of Microsoft Windows.
[[File:Badge vMx.png]]The 'fff' modifier in MX can actually be extended to 'ffffff' for output to a millionth of a second!
| 09:47:25.000' produced by
* [[File:Badge v1.png]]<#time format=hh:nn:ss.zzz>
*[[File:Badge vMx.png]]<#time format=hh:mm:ss.fff>
|-
|(not available)
| zzz
|Displays the offset of any time from UTC in hours and minutes
| e.g.-07:00
|-
|(not available)
|"h:mm K"
|Effectively another way of including time zone after a time, but it can only be used for time-zones never matching UTC (if I understand correctly)
|(no examples supplied yet)
|-
|t
|%t
|Displays the time using the Short Time format.
[[File:Badge vMx.png]]Remember that 't' combined with other specifiers (or preceded by space or '%') has a different meaning - see below.
| '09:47' produced by <#LastDataReadT format=t> (might not use colon in your locale) for both flavours of Cumulus
|-
|am/pm or Am/Pm or AM/PM
|tt
| [[File:Badge v1.png]]Uses the 12-hour clock for the preceding h or H specifier, and displays 'am' for any (clock time) hour from midnight until just before noon, and 'pm' for any hour from noon onwards. The am/pm specifier for Cumulus 1 can use lower, upper, or mixed case, and the result is displayed accordingly.
[[File:Badge vMx.png]] For MX, 'tt' displays the contents of the device locale setting for AM string for midnight until any hour before noon, and the contents of the PM string for noon or any hour after noon before midnight, so whether it displays in capitals or lower case is determined by the locale settings, not the case of "tt".
| [[File:Badge v1.png]] 'am' produced by <#LastDataReadT format=am/pm>, 'AM' produced by <#LastDataReadT format=AM/PM>
|-
|h a/p
|h t
|Uses the 12-hour clock for the preceding h or H (clock time) specifier, and displays 'a' for any hour from midnight until before noon, and 'p' for noon or any hour after noon.
[[File:Badge v1.png]]The a/p specifier can use lower, upper, or mixed case, and the result is displayed accordingly.
[[File:Badge vMx.png]]whether it displays the "a" or "p" in capitals or lower case is determined by the locale settings, not the case of "t".
| see previous example
|-
|ampm
|(see above for 12 hour formats)
|This displays the contents of the device locale setting for AM string for midnight until any hour before noon, and the contents of the PM string for noon or any hour after noon before midnight.
[[File:Badge v1.png]]Uses the 12-hour clock for the preceding h or H specifier
| see previous examples
|-
|/
|/
|Displays the date separator character given by the Date Separator. It might not display a slash.
| '/' for typical British locale
|-
|:
|:
|Displays the time separator character given by the Time Separator. With Cumulus 1, this might not display a colon.
[[File:Badge vMx.png]]Note that by default Cumulus MX expects a locale to use ":" for any time separator.
|':' for British locale
|}
===Year formats===
These are the simplest output format modifiers. We can only 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 as meaning same as lower case, it is simplest if we just show the lower case options
{| class="wikitable" border="1"
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
** In
**
*In the following table "MMMM" is shown as producing the full name for a month
**The output you get will depend on the language defined in your locale
**In all English based locales, the output will be in the range "January"
[[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
{| class="wikitable" border="1"
|Displays the month as a number without a leading zero (1-12).
* [[File:Badge v1.png]]Cumulus 1.x.y:If the 'M' or 'm' specifier immediately follows an h, hh, HH, or H specifier, the minute rather than the month is displayed.
* [[File:Badge vMx.png]]Cumulus MX: Note that including a ' ' (space) or '%' before the M makes it a custom modifier, so giving a different
|2
|-
|MMM
|Displays the month using the strings defined for '''short month name''' in the Locale.
|'Jun.' or 'Jun' produced by <#metdate format="MMM"> (varies depending which English locale as explained before table)
|-
|MMMM (or ''mmmm'')
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 not shown because it 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 is the definitive guide to how to ensure you do specify just the day part of any date specifications.
|ddd (3 characters long)
|ddd
|Displays the day as an abbreviation (in
|'Wed' produced by <#metdate format="ddd"> (UK English locale)
|-
|dddd (4 characters long)
!style="width:600px" | Example
|-
| c
| G (as single character format)
| Displays the date using the format given by the Short Date format, followed by the time using the format given by the Long Time format. The time is not displayed in Cumulus 1 if the date-time value indicates midnight precisely.
| '22/03/2019 09:47:25' produced by [[File:Badge v1.png]]<#time format=c>[[File:Badge vMx.png]]<#time format=G>
|-
| ddddd (5 characters long)
| ddddd (5 characters long)
| 'ddddd' will output the date using the format given by the Short Date format.
[[File:Badge vMx.png]]'d' (when on its own, without space or '%' prefix) may or may not work, it displays inconsistent behaviour as its effect depends on the tag name (sorry, there is no definitive list from the MX author specifying effect by individual tag name) with which it is used (you will need to experiment for yourself and compare with the two examples).
| *
* [[File:Badge vMx.png]]
** <#metdateyesterday format=d> e.g. '22/03/2019' (British Locale)
** <#yesterday=d> e.g. '22' returned
|-
|dddddd (6 characters long)
|"D MMMM"
|M
|Day of month followed by Month name.
| e.g. 22 July (English Locale)
|-
===
If you are considering use of literals (such as a space) within a output format modifier in a script, then don't. Instead include whatever precedes the literal in a tag specification, then concatenate on the literal, and finally concatenate another tag specification for whatever is to follow the 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 same approach applies if you wanted to replace that "T" with a space. (The explanation is that Cumulus (1 and MX) requires single quotes round a literal, but the script language requires any string to be enclosed in quotes, and double quotes are required by Cumulus round any complex specifier including any that include a space or other literal).
[[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 format characters, but simply an alternative to "%" as a special character. To explain the two ways of interpreting spaces consider as an example '''<#TpressTH format=" h:mm tt">'''. In that example the two spaces are interpreted in two different ways! The "space" before "h" is treated as the same as "%", but as the ''mm'' and ''tt'' are multi-character symbols, that does insert a space after the minutes but before the am/pm. I discuss this later in [[#Migrating from legacy Cumulus 1 to MX]] section.
If you want spaces to appear between symbols in an output format:
* [[File:Badge v1.png]]Cumulus 1.x.y: Add double quotation marks around everything after equals sign if spaces are present anywhere after that equals sign.
* [[File:Badge vMx.png]] In MX, add double quotation marks around everything after equals sign if spaces are wanted as separators, but you also need to add single quotation marks around the included space.
** If the first symbol after equals sign is a single character modifier, then it has a different meaning depending on whether it is first specificatiion or is preceded by a "%" or "space" as in example above. If the first modifier inclues more than one letter, then it does not ever take a prefix.
** If the space appears after double characters and the symbol that appears after the space is also double characters (as in example above) the single quotes round the space are optional.
** 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.
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' ' tt' <nowiki><small>on 'd/M/yyyy' </small></nowiki>'"> </code>.
| |||