Webtags/Parameters (preserving history): Difference between revisions

From Cumulus Wiki
Jump to navigationJump to search

Webtags/Parameters (preserving history) (view source)

Revision as of 09:22, 8 August 2021

5,781 bytes added ,  09:22, 8 August 2021
m
→‎Input modification Parameters
m (→‎Use of spaces: Rewrite of last paragraph)
(23 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{Template:Version badge Mx}}{{Version badge 1}}This Wiki page applies to both flavours of Cumulus currently available.
=Introduction=
=Introduction=


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.
This page is about parameters used for modifying Cumulus web tags.
 
A [[Cumulus template file|'''Cumulus Template File''']] is 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:
* MX avoids using these template files, 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 Cumulus MX, there is still 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]] 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.


==What is a web tag? ==
==What is a web tag? ==
{{TOCright}}
 
Put simply, a [[Webtags|web tag]] is included in a [[Cumulus template file]] to indicate where Cumulus should insert values when it [[Customised_templates#What_is_meant_by_.27Cumulus_processes_templates.27|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.
Put simply, a [[Webtags|web tag]] is included in a [[Cumulus template file]] to indicate where Cumulus should insert values when it [[Customised_templates#What_is_meant_by_.27Cumulus_processes_templates.27|processes that template]] and produces an output file.   


The output file can be:
The output file can be:
Line 12: Line 22:
* a [[Feels_Like#HTML_code_to_translate_web_tags_to_JavaScript_variables_.28as_modified_for_additional_parameters.29|JavaScript file]],
* a [[Feels_Like#HTML_code_to_translate_web_tags_to_JavaScript_variables_.28as_modified_for_additional_parameters.29|JavaScript file]],
* a [[PHP]] script file, or  
* a [[PHP]] script file, or  
*a [[Xml_webtags|eXtensible Mark-up Language (XML)]] file.
* a [[Xml_webtags|eXtensible Mark-up Language (XML)]] file.


==General Format for Web Tags==
==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:   
In the position in the template file where Cumulus is to insert the relevant data, place a web tag in the '''general format''' specified here:   


<pre><#tag_name [optional input selection parameters] [optional output modification parameters]></pre>
<code><#tag_name [optional input selection parameters] [optional output modification parameters]></code>


==== Case sensitivity for tag names ====
==== 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 [[Webtags|web tags page]].
The tag_name in the general format above is case sensitive, so please type the tag name exactly as shown in the tag name columns in the tables on the [[Webtags|tag names page]].


== What is a web tag parameter?==
== What is a web tag parameter?==


Now we get to the terminology for what this Wiki page will document.
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:
The parameters shown in the general format above are of two kinds:
*Input modifying
# Input modifying
*Output modifying
# Output modifying


These are explained below, after the warning on case sensitivity.
You can include both optional input modification, and optional output modification parameters
* As the general format above shows, you separate them with spaces, e.g. <#ByMonthTempHT mon=7 format=hh:nn>.
** In that example,  the time only is returned for the highest ever temperature in July, after processing by Cumulus of the time-stamp web tag.


=== Case sensitivity for parameters ===
=== 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 input modification parameters always use lower case, so please type them exactly as shown in the [[#Input modification Parameters|section below]].


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.
The content of optional output parameters are only case insensitive when used in Cumulus 1.
 
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 =
= Input modification Parameters =


'''Most web tags do not require any input 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.


* An input parameter is used where the same web tag can represent a value for a number of different past time instants.  
* An input parameter is used where the same web tag can represent a value for a number of different past time instants.  
Line 49: Line 62:
* So a combination of web tag name and input modification parameter lets Cumulus select the value you want to see.  
* So a combination of web tag name and input modification parameter lets Cumulus select the value you want to see.  
* The web tags that can use input modification parameters will depend on which Cumulus release you are using
* The web tags that can use input modification parameters will depend on which Cumulus release you are using
* 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 time only is returned for the highest ever temperature in July, after processing by Cumulus of the time-stamp web tag.


{| class="wikitable" border="1"
{| class="wikitable" border="1"
|-
|-
!style="width:30px" | Web Tags
!style="width:15px" | Tag names
!style="width:100px" | Values Available
!style="width:100px" | Values Available
!style="width:300px" | Input Modification Parameters
!style="width:200px" | Input Modification Parameters
!style="width:60px" | Introduced
!style="width:60px" | Introduced
!style="width:500px" | Examples
!style="width:500px" | Examples
!style="width:600px" | Description
!style="width:900px" | Description
|-
|-
| [[Webtags#Recent_History|'''recent history tags''']]
! 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
| One value for each minute in last 7 days
|   '''d''' specifies number of days ago, '''h''' specifies number of hours ago, and '''m''' specifies number of minutes ago.  
| '''d''' specifies number of days ago,
 
'''h''' specifies number of hours ago,  
 
and '''m''' specifies number of minutes ago.  
* You can use any combination of the three parameters.
* You can use any combination of the three parameters.
* The same d, h, and m, parameters are used by Cumulus 1 and MX.
* The same d, h, and m, parameters are used by Cumulus 1 and MX.
| Cumulus 1.9.3 beta build 1033
| Cumulus 1.9.3 beta build 1033 (remain available in MX)
| Examples for outside temperature:
| 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 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> will give the temperature one day ago.  
* <#RecentOutsideTemp d=1 h=1 m=1> will give the temperature one day, one hour and one minute ago.
* <#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.  
|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.
* If you don't supply any parameters, the result is undefined for Cumulus 1, and an illegal web tag for MX.
* '''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.
* '''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!
* When Cumulus is re-started the array it sets up will be based on reading any station log that exists, 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 [[Webtags#Recent_History|listed here]] tells you that nearest time.
* ''''''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.
* 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 recent history web tags available has not changed between last Cumulus 1 release and any MX release.
* Any new derivatives introduced by MX, will have current value web tags, and may have tags for extremes this month, extremes this year, all-time extremes, and monthly-all-time-extremes but do not have equivalent new recent history tags.
'''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!'''
|-
|-
| [[Webtags#Monthly_All_Time_Records|'''monthly all-time extreme records''']]
! scope="row"| [[Webtags#Monthly_All_Time_Records|'''monthly all-time extreme records''']]
| These exist for all occurrences of the current month, and for all occurrences of each month
| These exist for all occurrences of the current month, and for all occurrences of each month
|  '''mon=N''' where N is the index of the month of the year that you want the value for (1 =January, and so on, to 12 =December)  
|  '''mon=N'''
| Cumulus 1.9.3 beta build 1033
 
| e.g. <#ByMonthDewPointH mon=3> is highest monthly dew point for any March and <#ByMonthDewPointHT mon=3> is the related time and date.
where N is the index of the month of the year that you want the value for (1 =January, and so on, to 12 =December)  
| Cumulus 1.9.3 beta build 1033 (remain available in MX)
| <#ByMonthDewPointH mon=3> is highest monthly dew point for any March and <#ByMonthDewPointHT mon=3> is the related time and date.


<#ByMonthTempH mon=3> gives highest temperature in any March, <#ByMonthTempHT mon=3> gives the date and time for that highest temperature
<#ByMonthTempH mon=3> gives highest temperature in any March, <#ByMonthTempHT mon=3> gives the date and time for that highest temperature
| Only one input parameter applies:
| Only one input parameter applies:
* The value of "N" supplied should be an integer between 1 and 12
* The value of "N" supplied should be an integer between 1 and 12
* 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 process a script, to calculate the correct input parameter, before Cumulus processes the template.
* If you don't supply an input parameter (or supply an invalid value like zero) the current month will be used.  
 
Use without an input parameter applies if you want to write a template that will always supply values for the current month and don't want to process a script, to calculate the correct input parameter, before Cumulus processes the template.
|-  
|-  
| Only <#SunshineHoursMonth> and <#SunshineHoursYear>
! scope="row"| [[Webtags#Monthly|Only <#SunshineHoursMonth>]] and [[webtags#Yearly|Only <#SunshineHoursYear>]]
| Values available for current month/year, and for past month/year
| Values available for current month/year, and for past month/year
| All web tags take '''r=-ww'''
| Listed web tags take: '''r=-ww''' (note minus sign and up to 2 digits)
* Monthly tags also take: '''m=N y=nnnn'''
* Monthly tags also take: '''m=N y=nnnn''' ('''N''' can be 1 to 12, ''nnnn'' is 4 digit year)
* Yearly tags also take: '''y=nnnn'''  
* Yearly tags also take: '''y=nnnn'''  
Omit input modification parameter to get value for current month/year
Omit input modification parameter to get value for current month/year
Line 101: Line 116:
* <#SunshineHoursMonth> gives total sunshine hours since 1 minute past midnight at start of current month  
* <#SunshineHoursMonth> gives total sunshine hours since 1 minute past midnight at start of current month  
* <#SunshineHoursMonth y=2021 m=1> for the January 2021 total
* <#SunshineHoursMonth y=2021 m=1> for the January 2021 total
* <#SunshineHoursMonth r=-1> for last months total
* <#SunshineHoursMonth r=-1> for last month's total
* <#SunshineHoursMonth r=-12> for same month as current month, but one year ago
* <#SunshineHoursMonth r=-12> for same month as current month, but one year ago
Yearly examples:
Yearly examples:
* <#SunshineHoursYear> gives total sunshine hours since 1 minute past midnight on New Year's Day
* <#SunshineHoursYear> gives total sunshine hours since 1 minute past midnight on New Year's Day
* <#SunshineHoursYear y=2019> for the total for 2019
* <#SunshineHoursYear y=2019> for the total for 2019
* <#SunshineHoursYear r=-2> total for the year before last (if current year is 2021, that is same as previous example)
* <#SunshineHoursYear r=-2> total for the year before last (if current year is 2021, that returns total for 2019 as previous example)
| Returns the sunshine hours total in selected period
| Returns the sunshine hours total in selected period
(You need a sensor to be monitoring this throughout selected period)
|}
|}


= Output modification parameters =
= Output modification parameters =


*A few web tags always need an output format specifier
This page does not tell you which web tags fall into each of these 3 types:
*Some web tags never use an output format specifier
* A few web tags always need 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.
* Some web tags ignore any output format specifier as they have a fixed output format
* The majority of web tags have a default output if there is no output format modifier, but accept an output format parameter, so you can change what they output.


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 [[Webtag_Applicability|discussion about applicability]], but that needs updating as it does not specify dependencies for individual [[Webtags|web tags]].  


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 does not yet specify dependencies for individual [[Webtags|web tags]].
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
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 two output modifiers for changing number of decimal places
* there are multiple output modifiers for changing date and/or time format  
* there are multiple output modifiers for changing date and/or time format  
If you are using the legacy Cumulus (or a very early MX release), please skip to [[#Two Output (format modifier) parameters for decimal places]] as the changing decimal comma into decimal point parameter is not available to you.


Each of these will be explained in turn.
Each of these will be explained in turn.


==Output Modification Parameter for Removing Commas==
==Output Modification Parameter for changing any decimal comma into a decimal point==


General format: <tt><#tag_name rc=y></tt>  
General format: <tt><#tag_name rc=y></tt>  
Line 137: Line 155:
**From release 3.6.6 onwards (1 June 2020), it was extended to other web tags that output real numbers.
**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
**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


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).
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 [[MX_on_Linux#Parameter_for_changing_Locale|-lang]] parameter when starting MX.
{| class="wikitable" border="1"
{| class="wikitable" border="1"
|-
|-
Line 153: Line 165:
|rc=n
|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
|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
For more information about how the computer determines whether decimal commas is your default, see [[#Locale]] section later.
| Both <#tempYH> and <#tempYH rc=n> will return yesterday's highest temperature using what is specified by locale to separate integer and decimal parts
| Both <#tempYH> and <#tempYH rc=n> will return yesterday's highest temperature using what is specified by locale to separate integer and decimal parts
|-
|-
Line 163: Line 177:
'''Why would you want to remove decimal commas?'''  Well because the JavaScript language 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).
'''Why would you want to remove decimal commas?'''  Well because the JavaScript language 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).


==Two Output (format modifier) parameters for decimal places ==
==Controlling the number of decimal places==


This functionality was trialled in the original Cumulus, but has been properly implemented in MX.
Internally, Cumulus stores numbers in binary. You cannot represent base 10 decimal places exactly in base 2.  


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:
Therefore, Cumulus stores to a precision that would generally give about 24 significant figures when expressed in base 10.
 
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.
 
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 recalibrated 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.
 
Consequently, 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.
 
===Two Output (format modifier) parameters for decimal places===
 
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 dp=i></tt> and  
*<tt><#tag_name tc=y></tt>  
* <tt><#tag_name tc=y></tt>  
These can be applied to any tag names that represent real numbers (with integer and decimal parts).  
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:
====Rounding to a specific number of decimal places====
#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.
<tt>dp=i</tt> is used for both Cumulus 1 and MX.  
#MX when it came out of beta, added this output modification parameter usage in the moon tags <#MoonPercent> and <#MoonPercentAbs>).
*The value '''i''' following the attribute '''dp''' is an integer, it represents how many decimal places you want for the output you see.
#*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 <tt><#latitude dp=i></tt> and <tt><#longitude dp=i></tt> were able to be output with "i" decimal places, e.g. <#latitude dp=5> gives "59.24250".
This functionality was trialled in the original Cumulus, but has been properly implemented in MX.   


===Controlling the number of decimal places===
If you are using the legacy Cumulus (1.9.4), only <tt><#latitude dp=i></tt>  and <tt><#longitude dp=i></tt> were able to be output with "i" denoting number of decimal places, e.g. <#latitude dp=5> gives "59.24250".


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.  
If you are not using latest MX release, you may find this is not available for particular web tag names
# 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"
====Truncation of unwanted decimal places====


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.
This output format modifier is only available in MX.


*<tt>dp=i</tt> is used for both Cumulus 1 and 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 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. 


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.
* 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.


*<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>.
Note, truncation by MX converts real numbers to integers. There is no option to truncate to one decimal place, Airports are expected to report air field level (QFE), and sea level (QNH), pressures truncated to one decimal place rather than rounded.
**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 ==
== Multiple Output Format Modifier parameters for times and dates ==
Line 204: Line 232:
These are highly complicated, and so have been left until after the simpler ones!
These are highly complicated, and so have been left until after the simpler ones!


===Use of spaces===
To start with a simple example, suppose you want date/time in ISO 8601 format:
# This means, something like ''2019-02-28 06:59:05''.
# 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 our tag name does accept both date and time modifiers, simply modify the web tag as shown here <code><#tag_name format="yyyy-MM-dd HH:mm:ss"></code> where tag_name is set from step 1, but all the rest is typed as shown.
# To explain each element in that format value, look in [[#Year formats]], [[#Month formats]], [[#Day formats]], [[#Use of spaces]], [[#Time formats]].


There are multiple parameters for specifying dates and times, and you might want spaces to appear in that output format.
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]].
 
If we need to include spaces, then we have to enclose the whole specifier in double quotation marks e.g. <code><#tag_name format="x y z"></code>
 
Any literals (i.e. characters we do not want to be interpreted by the date time parameter parser) are generally enclosed in single quotation marks, within the double quotation marks delimiting the specifier.  You will find literals discussed fully at [[#Including literals in format parameters]] later.
 
For now just remember, 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.  The complicated sounding (but actually simple solution) is to avoid placing literals 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.


===Which tag names take date/time output formatting modifiers===
===Which tag names take date/time output formatting modifiers===
Line 218: Line 245:
There are nearly a thousand different tag names.  
There are nearly a thousand different tag names.  


There are a few tag names labelled as being fixed format, obviously they cannot take any output 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.


Time modifiers can be used to change the way that durations are reported, for tag names that report durations instead of clock times. Examples include '''<#daylength>'''  and '''<#MonthDailyRainHD format=H:mm>'''.  The [[webtags]] page clearly identifies those tag names that report clock times, but it is left to you to work out where durations are reported.
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>'''  and '''<#MonthDailyRainHD format=H:mm>'''.
 
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.
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.


There are some tags (e.g. highest temperature range in month/year), for which Cumulus has been coded to report "--:--" 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 their output can only be done on subsequent days.
There are some tags (e.g. highest temperature range in month/year), for which Cumulus has been coded 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 possible here to list each of these tag names, and indicate which time/date modifiers are accepted on a tag by tag basis.  I did consider adding a column for that purpose to each table on the [[webtags]] page, but decided those were complicated enough.  Instead, the following table, explains much more simply, which web tags will accept time and/or date output modifiers:
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:
{| class="wikitable" border="1"
{| class="wikitable" border="1"
|-
|-
Line 235: Line 264:
|-
|-
|-
|-
| Any tag names that don't report times nor dates
! scope="row"| Any tag names that don't report times nor dates
| None
| None
| None
| None
| None
| None
|-
|-
| [[Webtags#No_Commas]]
! scope="row"| [[Webtags#No_Commas]]
| None
| None
| None
| None
| None
| None
|-
|-
| [[Webtags#Date_.26_Time|Date &Time]], [[Webtags#Day/Night/Sun/Moon]]
! scope="row"| [[Webtags#Date_.26_Time]], [[Webtags#Day/Night/Sun/Moon]]
| Only <#timehhmmss>, <#minute>, <#hour>, <#sunrise>, <#sunset>, <#dawn>, <#dusk>  
| Only <#timehhmmss>, <#minute>, <#hour>, <#sunrise>, <#sunset>, <#dawn>, <#dusk>  
| Only <#LatestErrorDate>, <#date>  (but no others)
| Only <#LatestErrorDate>, <#date>  (but no others)
| Only <#LastDataReadT>, <#time>, <#metdate>, <#metdateyesterday>, <#update>, <#LastDataReadT>  
| Only <#LastDataReadT>, <#time>, <#metdate>, <#metdateyesterday>, <#update>, <#LastDataReadT>  
|-
|-
| [[Webtags#Today]], [[Webtags#Yesterday]]
! scope="row"| [[Webtags#Today]], [[Webtags#Yesterday]]
| Any tag name in "Time" column of linked table
| Any tag name in "Time" column of linked table
| None
| None
| None
| None
|-
|-
| [[Webtags#Monthly]], [[Webtags#Yearly]]
! scope="row"| [[Webtags#Monthly]], [[Webtags#Yearly]]
| Any tag name in "Time" column of linked table in first column
| Any tag name in "Time" column of linked table in first column
| Any tag name in "Date" column of linked table in first column
| Any tag name in "Date" column of linked table in first column
| None of the tag names. For explanation see the ^ below this table
| None of the tag names. For explanation see the ^ below this table
|-
|-
|[[Webtags#All_Time]], [[Webtags#Monthly_All_Time_Records]]
! scope="row"| [[Webtags#All_Time]], [[Webtags#Monthly_All_Time_Records]]
| None (all tag names combine both time and date)
| None (all tag names combine both time and date)
| None (all tag names combine both time and date)
| None (all tag names combine both time and date)
Line 267: Line 296:
^ 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.
^ 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.


Note: There are some monthly/yearly web tags (e.g wettest day) where a date tag is available (i.e. <#MonthDailyRainHD>), but there is no time tag.  As explained before, in that wettest day example '''<#MonthDailyRainHD format=H:mm>''' returns the duration in hours and minutes since rollover for which rain continued to increase on that date, not the clock time. For rainfall, only '''<#LastRainTip>''' can have output modifiers added to report a clock time.
Note: There are some monthly/yearly web tags (e.g. wettest day) where a date tag is available (i.e. <#MonthDailyRainHD>), but there is no time tag.  As explained before, in that wettest day example '''<#MonthDailyRainHD format=H:mm>''' returns the duration in hours and minutes since rollover for which rain continued to increase on that date, not the clock time. For rainfall, only '''<#LastRainTip>''' can have output modifiers added to report a clock time.


===Locales===
===Locales===
Line 303: Line 332:
===Dependency on Cumulus flavour===
===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.
You cannot,in general, use the same date/time formatting for both the original (legacy) Cumulus and MX.
 
All the tables explaining what is available, attempt to show what is used in each flavour for each type of output, both by including separate columns for each flavour, and by giving examples in each flavour.


====For the legacy software====
====For the legacy software====
Line 319: Line 350:
====The complications with MX====
====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.
Cumulus MX works '''internally''' with dates specified in either a day before month before year format, or ISO 8601 date format where year comes first (yyyy-MM-dd) depending on context.  Compatibility with the legacy software has so far meant while the [[:Category:Ini Files|*.ini Files]] have adopted the year first approach, the [[:Category:MX txt Files|*.txt Files]] have stuck to date formats as used in the legacy definitions. 
 
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 modifer (custom format).  '''Sounds confusing?''' Well it is complicated.


Consider context first:
Consider context first:
Line 333: Line 366:
**".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!  
**".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).  
**(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).
*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).
 
===Use of spaces===
 
There are multiple symbols for specifying dates and times, and you might want spaces to appear between symbols in that output format.
 
You need to add quotation marks to the output format specifier if spaces are present.
 
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.
 
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.


====Date formats====
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">''', here the month number is a single character "M", so to insert the space we have to treat it as a literal by enclosing the space character in single quotes and the whole specifier in double quotes. 


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).
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>.


If you are in the USA, Cumulus will not use your month first date internally, but you can see your preferred format in any output as you can can combine the month specifier, with the day 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 them and update the table below</big>.
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 preprocessor format, the literal 'T' has been inserted between two separate web tags.
 
===Year formats===
 
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 as meaning same as lower case, it is simplest if we just show the lower case options needed for MX:


[[#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.
{| class="wikitable" border="1"
{| class="wikitable" border="1"
|-
|-
!style="width:150px" | [[File:Badge v1.png]]Delphi Specifier for Cumulus 1.9.x
!style="width:150px" | Specifier
!style="width:150px" | [[File:Badge vMx.png]]Mono/.NET Specifier for Cumulus MX
!style="width:600px" | Displays
!style="width:600px" | Displays
!style="width:600px" | Example
!style="width:600px" | Example
|-
|-
|c
|yy
|G  (as single character format)
|Displays the year as a two-digit number (00-99).
|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.
|19 produced by <#LastDataReadT format=yy>  
|'22/03/2019 09:47:25' produced by [[File:Badge v1.png]]<#time format=c>[[File:Badge vMx.png]]<#time format=G>
|-
|-
|"D MMMM YYYY"
|yyyy
|D
|Displays the year as a four-digit number (2000-9999).
|Long date format
|2009 produced by <#LastDataReadT format=yyyy>  
|e.g.4 December 2009
|-
|"D MMMM"
|M
|Day of month followed by Month name (except USA locales).
 
Compared with next table where '''format=%M''' used, '''format=M''' on its own returns both Month and Day according to local format
| e.g. 22 July (English Locale)
|-
|"MMMM D"
|"MMMM d" if M alone does not work
| USA format of month before day of month
| e.g. July 4 (USA format)
|-
|TT
|T  (as single character format)
|Displays the time using the '''Long Time format'''.
 
[[File:Badge vMx.png]] Note that this is a full time specifier and "T" is on its own as we are using a single character format.
|'09:47:56'  (might not use colon in your locale) produced by  
* [[File:Badge v1.png]]<#LastDataReadT format=TT>
*[[File:Badge vMx.png]]<#LastDataReadT format=T>
|}
|}


Line 387: Line 409:
**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)
**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"
**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.")
**It appears that language settings in many locales (not "en-gb"), add a full stop to any abbreviations  
*** 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
and in that case the 3-letter "MMM" is turned into a 4-letter output (e.g. Australia settings default would output from "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 in a web tag output if your locale uses it
*In the following table "MMMM" is shown as producing the full name for a month
*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
**The output you get will depend on the language defined in your locale
**In English locales, this will be "January" - "December"
**In English locales, the output will be in the range "January" - "December"
{| class="wikitable" border="1"
{| class="wikitable" border="1"
|-
|-
Line 427: Line 450:
All locales offer both numerical and alphabetical formats for representing a day.
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.   
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.
{| class="wikitable" border="1"
{| class="wikitable" border="1"
|-
|-
Line 436: Line 458:
!style="width:600px" | Example
!style="width:600px" | Example
|-
|-
|d
| d (single character)
|%d
| %d
|Displays the day as a number without a leading zero (1-31). [[File:Badge vMx.png]]Note that Cumulus MX requires a ' ' (space), '%' or other modifier to be included, as 'd' on its own returns full 'short date').
|Displays the day as a number without a leading zero (1-31).  
|27 produced by [[File:Badge v1.png]]<#metdate format="d">[[File:Badge vMx.png]]<#metdate format="%d">
 
[[File:Badge vMx.png]]Note that Cumulus MX requires a ' ' (space), '%' or another modifier to be included, as 'd' on its own is inconsistent - see [[#Date formats]] table).
| 27 produced by:
* [[File:Badge v1.png]]<#metdate format="d">
* [[File:Badge vMx.png]]<#metdate format="%d">
|-
|-
|dd
|dd (2 characters long)
|dd
|dd
|Displays the day as a number with a leading zero (01-31).
|Displays the day as a number with a leading zero (01-31).
|07 produced by <#metdate format="dd">
|07 produced by <#metdate format="dd">
|-
|-
|ddd (3 characters long)
|ddd
|ddd
|ddd
|Displays the day as an abbreviation (in UK English will output Sun-Sat) using the strings appropriate to the Locale.
|Displays the day as an abbreviation (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)
|'Wed' produced by <#metdate format="ddd"> (English locale)
|-
|-
|dddd
|dddd (4 characters long)
|dddd
|dddd
|Displays the day as a full name (Sunday-Saturday) using the strings appropriate to the Locale.
|Displays the day as a full name (Sunday-Saturday) using the strings appropriate to the Locale.
|'Friday' produced by <#metdate format="dddd"> (English locale)
|'Friday' produced by <#metdate format="dddd"> (English locale)
|-
|ddddd
|d (as single character format)
| [[File:Badge v1.png]]Cumulus 1.x.y: Displays the date using the format given by the Short Date format.  [[File:Badge vMx.png]]This MX parameter (when on its own) displays inconsistent behaviour as its effect depends on the tag name with which it is used (see examples).
|e.g. '22/03/2019' (British Locale) produced by [[File:Badge v1.png]]<#metdate format=dddd>
[[File:Badge vMx.png]]<#metdateyesterday format=d> ''but not''  <#yesterday=d> which would return just '22'
|-
|dddddd
|D  (as single character format)
|Displays the date using the format given by the Long Date format.  [[File:Badge vMx.png]]The MX parameter cannot be combined with any other parameters.
|e.g. '22 March 2020' (British Locale)
|}
|}


===Year formats===
====Date formats====
 
The [[#Year formats]], [[#Month formats]], and [[#Day formats]] listed above can be combined to make up a date output modifier, but there are some other modifiers available that can produce whole dates.
 
[[#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.


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:
If you are in the USA, Cumulus will not use your month first date internally or in any files in the [[Data folder|'''data''' sub-folder]], but you can see your preferred format asan output from web tags, as you can can combine the month specifier, with the day 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</big>.
{| class="wikitable" border="1"
{| class="wikitable" border="1"
|-
|-
!style="width:150px" | Specifier
!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" | Displays
!style="width:600px" | Example
!style="width:600px" | Example
|-
|-
|yy
|c
|Displays the year as a two-digit number (00-99).
|G  (as single character format)
|19 produced by <#LastDataReadT format=yy>  
|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)
|d (as single character format)
| Flavour issues:
* [[File:Badge v1.png]]Cumulus 1.x.y: 'ddddd' will output the date using the format given by the Short Date format. 
* [[File:Badge vMx.png]]This MX parameter (when on its own, without space or '%' prefix) 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]] '22' returned by e.g. <#yesterday=d>
 
Short date format e.g. '22/03/2019' (British Locale) produced by:
* [[File:Badge v1.png]]<#metdate format=ddddd>
* [[File:Badge vMx.png]]<#metdateyesterday format=d>
|-
|dddddd (6 characters long)
|D  (as single character format)
|Displays the date using the format given by the Long Date format. 
 
[[File:Badge vMx.png]]The MX 'D' parameter '''cannot be combined''' with any other parameters.
|e.g. '22 March 2020' (British Locale)
|-
|"D MMMM YYYY"
|D
|Long date format
|e.g.4 December 2009
|-
|"D MMMM"
|M
|Day of month followed by Month name (except USA locales).
 
Compared with next table where '''format=%M''' used, '''format=M''' on its own returns both Month and Day according to local format
| e.g. 22 July (English Locale)
|-
|"MMMM D"
|"MMMM d" if M alone does not work
| USA format of month before day of month
| e.g. July 4 (USA format)
|-
|-
|yyyy
|TT
|Displays the year as a four-digit number (2000-9999).
|T  (as single character format)
|2009 produced by <#LastDataReadT format=yyyy>  
|Displays the time using the '''Long Time format'''.
 
[[File:Badge vMx.png]] Note that this is a full time specifier and "T" is on its own as we are using a single character format.
|'09:47:56'  (might not use colon in your locale) produced by  
* [[File:Badge v1.png]]<#LastDataReadT format=TT>
*[[File:Badge vMx.png]]<#LastDataReadT format=T>
|}
|}


===Time formats===
===Time formats===
Line 720: Line 785:




== Migrating from legacy to MX==
== Migrating from legacy Cumulus 1 to MX==


If you use NOAA type report functionality, and choose to transfer your existing [[Cumulus.ini (Cumulus 1)|existing configuration file (cumulus.ini)]] to [[Cumulus.ini|MX]], you need to be concerned about how to represent a month.
If you have created any legacy cumulus template files, then in each template, you will need to do some editing. Everywhere a web tag appears with an output modifiers that is used to specify a date and/or time format, has to be edited before that template will work for 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:
Here are the main reasons:
* the reserved characters are different in C1 and MX (affecting use of literals like "on" and "at" that appear in many English time-stamps)
* the reserved characters are different in C1 and MX (affecting use of literals like "on" and "at" that appear in many English time-stamps)
* the Delphi in legacy Cumulus is case insensitive, so for example "H" and "h" have the same meaning
* MX is case sensitive, and symbols mostly have different meanings when one symbol is used to when that symbol is used with others, so for example "H" and "h" have different meanings, and if not used with other symbols will need to be preceded with a "%" to have same meaning as they have in combination with other symbols
* In the legacy cumulus, a symbol like "d" has the same meaning for any tag
* MX is inconsistent, a symbol like "d" changes its meaning depending on the tag it is used with (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)
* the symbols used for representing such modifiers as minutes, month, am/pm, are different between C1 and MX.
* 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 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 the legacy Cumulus, a space is a gap between characters
* 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).
* In MX, a space must be within a literal, as a space before a symbol has the same effect as "%", (it changes 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.
'''Confused even more now?''' I'm not surprised, but maybe some examples will help.


=== Examples ===
=== Examples ===
Line 753: Line 823:
** but alternatively you can escape each verbatim character with a backslash as prefix (Cumulus MX).  
** 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.
* 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==
== Past history for this page==
Line 764: Line 833:
== Forum reference ==
== Forum reference ==


Steve Loft published a table showing comparison between output date modifiers for Cumulus 1 and MX at [https://cumulus.hosiene.co.uk/viewtopic.php?f=39&t=17888 Cumulus MX forum].  The table there was based on the table that was originally created when only the original Cumulus existed.
Steve Loft published a table showing comparison between output date modifiers for Cumulus 1 and MX at [https://cumulus.hosiene.co.uk/viewtopic.php?f=39&t=17888 Cumulus MX forum].  The table there was based on the table that appeared in this Wiki when only the original Cumulus existed, so it was designed to help people migrate to his MX beta, it was not intended as a definitive list of what modifiers were available for MX (Steve instructed people to look them up on some Microsoft sites).


The subsequent comments in the forum suggested his layout got people confused. Most of that confusion came in two circumstances:
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 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
*When someone who had been using Cumulus 1 swapped to MX and wanted to replace a combination of output modifier characters that was not explicitly shown in his table.
 
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" had two meanings depending whether it was combined with "H" or "h" (when it represented minutes), or on its own or with any other code (when 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.


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 using a space or a "%" to modify the meaning of the character.  


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.  


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.
If we want the typical Cumulus date-stamp of day of month number and month, then we have two choices, because both "d M" and "M" will work. This illustrates how "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.
Hopefully, the way that information is now presented on this page makes any use of parameters for web tags much easier now.
Sfws
5,838

edits

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

Navigation menu