Webtags/Parameters (preserving history): Difference between revisions

From Cumulus Wiki
Jump to navigationJump to search

Webtags/Parameters (preserving history) (view source)

Revision as of 19:35, 23 July 2021

7,429 bytes added ,  19:35, 23 July 2021
m
→‎Use of spaces: ok, now finally the code shows correctly
m (→‎Output Modification Parameter for Removing Commas: add dates beside release references)
m (→‎Use of spaces: ok, now finally the code shows correctly)
(23 intermediate revisions by the same user not shown)
Line 4: Line 4:


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


Line 26: Line 26:
== What is a web tag parameter?==
== What is a web tag parameter?==


{{TOCright}}
 
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.


Line 45: Line 45:
'''Most web tags do not require any input parameters'''.  
'''Most web tags do not require any input parameters'''.  


An input parameter is used where the same web tag can represent a value for a number of different past time instants. Each of those past time instants is represented by a different value for the input parameter. So a combination of web tag name and input parameter lets Cumulus to pick the value you want to see.  
* An input parameter is used where the same web tag can represent a value for a number of different past time instants.  
* Each of those past time instants is represented by a different value for the input parameter.  
* So a combination of web tag name and input 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
* 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.


There are currently only two groups of tags where an input parameter is mandatory:
{| class="wikitable" border="1"
#The [[Webtags#Recent_History|'''recent history tags''']] where a separate value exists for potentially every individual minute in last week.
|-
#* These tags need between one and three input parameters  as explained below.
!style="width:30px" | Web Tags
#The [[Webtags#Monthly_All_Time_Records|'''monthly all-time records''']] where a separate value exists for each particular month (of any year).
!style="width:100px" | Values Available
#*These tags need an input parameter specifying which month.
!style="width:300px" | Input Modification Parameters
#*To save you looking up the linked section, a single input parameter is needed (which is 1 for January to 12 for December, or 0 for current month).
!style="width:60px" | Introduced
 
!style="width:500px" | Examples
 
!style="width:600px" | Description
==Input Modification Parameters for Recent History tags ==
|-
 
| [[Webtags#Recent_History|'''recent history tags''']]
You specify which value you want from the array by using parameters on the web tags for number of days ago, hours ago, and minutes ago. The same d, h, and m, parameters are used by Cumulus 1 and MX.
| 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.  
All values supplied for parameters must be whole numbers.
* You can use any combination of the three parameters.
 
* The same d, h, and m, parameters are used by Cumulus 1 and MX.
If you don't supply any parameters, the result is undefined for Cumulus 1, and an illegal web tag for MX.  
| Cumulus 1.9.3 beta build 1033
 
| 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. '''Please note:''' Some Cumulus users say that using <#RecentOutsideTemp  d=1 m=1> is more reliable at getting the temperature at a similar time the day before, the extra minute apparently gives better results when you might not be using Cumulus all the time, or your weather station might have some drift on when it supplies readings. See which works best for you.
* <#RecentOutsideTemp d=1 h=1 m=1> will give the temperature one day, one hour and one minute ago.
 
|All values supplied for parameters must be whole numbers.
<#RecentOutsideTemp d=1 h=1 m=1> will give the temperature one day, one hour and one minute ago.
* 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.
'''Please note that parameters specify time-stamped array element to retrieve based on counting back from current local time''' so the result for ''any period including when clocks change'' may not be quite what you anticipated.
* When Cumulus is re-started the array it sets up will be based on reading 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.
* 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''']]
| 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)
| 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.


 
<#ByMonthTempH mon=3> gives highest temperature in any March, <#ByMonthTempHT mon=3> gives the date and time for that highest temperature
=== During catch-up ===
| Only one input parameter applies:
 
* The value of "N" supplied should be an integer between 1 and 12
When Cumulus is re-started the array it sets up will be based on reading the logs, so the contents will initially have a resolution according to the logger interval you have set in Cumulus and/or your station.  You'll get the nearest value if you ask for a time for which there is currently no exact match, and the first tag listed tells you that nearest time.
* 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.
 
|-
=== Variations between Builds/Versions ===
| Only <#SunshineHoursMonth> and <#SunshineHoursYear>
 
| Values available for current month/year, and for past month/year
Before build 1098, the recent history array did not initialise correctly from the station logger for the period since Cumulus was last run.
| All web tags take '''r=-ww'''
 
* Monthly tags also take: '''m=N y=nnnn'''
The input parameters are same for Cumulus 1 and Cumulus MX, they always use lower case d, h or m.
* Yearly tags also take: '''y=nnnn'''
 
Omit input modification parameter to get value for current month/year
The list of tags available has not changed between last Cumulus 1 release and any MX release. Any new derivatives reported elsewhere have not resulted in equivalent new recent history tags.
| MX release 3.12.0
 
| Monthly examples:
==Input Modification Parameters for Monthly all-time tags==
* <#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
Each Monthly All Time Records web tag has an optional input parameter "mon=N" where N is the index of the month of the year that you want the value for (January=1 and so on).
* <#SunshineHoursMonth r=-1> for last months total
 
* <#SunshineHoursMonth r=-12> for same month as current month, but one year ago
If you don't supply an input parameter (or supply an invalid value like zero) the current month will be used. This is useful if you want to write a template that will always supply values for the current month and don't want to use a script to enter the correct input parameter by processing with that script before Cumulus processes the template.  
Yearly examples:
 
* <#SunshineHoursYear> gives total sunshine hours since 1 minute past midnight on New Year's Day
The corresponding date/time web tags are formatted just like the all time records. You can customise the date and time formats by adding the output  'format' modification parameters (shown later on this page) to the web tag.
* <#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)
To supply both optional input modification, and optional output modification parameters, separate them with spaces, e.g. <#ByMonthTempHT mon=7 format=hh:nn>. In that example,  the highest ever temperature in July is returned in the value after processing by Cumulus.
| Returns the sunshine hours total in selected period
|}


= Output modification parameters =
= Output modification parameters =
Line 102: Line 118:
This page does not tell you which web tags fall into each of the above 3 types.
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 does not yet 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]].  


The output modification options available, if you are using a MX release, include:
The output modification options available, if you are using a MX release, include:
Line 127: Line 143:
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").
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 [[Setting_up_Raspberry_Pi#Parameter_for_changing_Locale|-lang]] parameter when starting MX.
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 137: Line 153:
|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
| Both <#tempYH> and <#tempYH rc=n> will return yesterday's highest temperature using what is specified by locale to separate integer and decimal parts
|-
|-
|rc=y
|rc=y
|the attribute '''rc''' takes the value 'y' to replace any commas defined by the locale with full stops to separate integer and decimal parts of the output value.  
|the attribute '''rc''' takes the value 'y' to replace any commas defined by the locale with full stops to separate integer and decimal parts of the output value.  
| <#tempYH rc=y> will return yesterday's highest temperature as integer part then full stop then decimal part, regardless of local
|}
|}


Line 145: Line 163:
'''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 ==
==Two Output (format modifier) parameters for decimal places ==
 
This functionality was trialled in the original Cumulus, but has been properly implemented in MX.
 
From release 3.10.5 (which did a big rewrite of web tag handling), you can modify the way real numbers (with integer and decimal parts) are output using output modification parameters in either of the following formats:
* <tt><#tag_name dp=i></tt> and
*<tt><#tag_name tc=y></tt>
These can be applied to any tag names that represent real numbers (with integer and decimal parts).


The latest MX release can use both the following formats <tt><#tag_name dp=i></tt> and <tt><#tag_name tc=y></tt> to modify the output of all tag names that represent real numbers (with integer and decimal parts). If you are using an early release of MX:
If you are using an early release of MX:
#Modification of latitude and longitude is also available in MX, from beta releases (3.0.0) onwards.
#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
#MX when it came out of beta added usage in the moon tags <#MoonPercent> and <#MoonPercentAbs>). Specifically, <#MoonAge> gives "11" but <#MoonAge dp=3> gives "11.234"  
#*But this output modification parameter could not be applied to any other tags in the MX beta.
#MX when it came out of beta, added this output modification parameter usage in the moon tags <#MoonPercent> and <#MoonPercentAbs>).  
#*Specifically, <#MoonAge> gives "11" but <#MoonAge dp=3> gives "11.234"  
#In later releases of MX, any tag that gives a decimal output, can use the "dp=n" modifier.
#In later releases of MX, any tag that gives a decimal output, can use the "dp=n" modifier.


If you are using the legacy Cumululus (1.9.4), only <tt><#tag_name dp=i></tt> format is available, and only for latitude and longitude e.g. <#latitude dp=5> gives "59.24250".  
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".  


===Controlling the number of decimal places===
===Controlling the number of decimal places===
Line 172: Line 199:
**If you are using an early release of MX, you will need to research whether this is available for particular web tag names  
**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.
**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 178: Line 204:
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===
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.


===Where date format codes are used===
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.


Time/Date format codes are used in two places:
That approach would not work if we wanted to use single character specifiers, 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.  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>.
# As part of report names for NOAA style reports (see [[Reports_folder#Additional_Information_for_NOAA_reports|this page]] for full details)
# As part of web-tags that report either times or dates, or report both a date and a time (this is what the rest of this page covers)


===Which web tag names take date/time output formatting modifiers===
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.


Cumulus includes a lot of web tags that can output dates, times, or both.  In many cases, it will not be obvious from the web tag name whether it can return both time and date information.  Sometimes, the default (without any output format modification codes) will reveal whether date and time information are both available, but unfortunately that does not always work.  The following table shows some examples of which web tags will accept time and/or date output modifiers.  '''Be aware''', some of the tags shown in the table may return "---" or "--:--" or some other non-numerical output  in two circumstances:
===Which tag names take date/time output formatting modifiers===
#where the event they report does not happen that day (e.g. moon rise and set do not always happen within a calendar day on Earth.
#where the related data is not defined until at least one whole day has been recorded (e.g. some monthly and yearly web tags do not contain data until second day of month/year)


Remember, the default format for web tags reporting date and/or time is often dependent on the locale you are using for running MX (and we will discover below the effect of some output format modifiers is also dependent on locale):
There are nearly a thousand different tag names.


If you run MX on a computer using Microsoft Windows, then the "locale" is determined by settings in either '''Control Panel''' (go to "Clock and Region" screen, choose "Change date, time or number formats", choose "Language preferences") or using "Settings app" (go directly to "Language").
There are a few tag names labelled as being fixed format, obviously they cannot take any output modifiers.


On computers running other operating systems, the locale is set when you install "Mono-complete".  You can overide the default locale with [[Setting_up_Raspberry_Pi#Parameter_for_changing_Locale|-lang]] parameter when starting MX.
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.


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.
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:
{| class="wikitable" border="1"
{| class="wikitable" border="1"
|-
|-
!style="width:100px" | Cross-reference
!style="width:100px" | Cross-reference to table on web tag names page
!style="width:300px" | Accept time only (examples)
!style="width:300px" | Tag names that accept only time output modifiers
!style="width:300px" | Accept date only (examples)
!style="width:300px" | Tag names that accept only date output modifiers
!style="width:300px" | Accept time and date modifiers (examples)
!style="width:300px" | Tag names that accept both time and date output modifiers
|-
|-
|[[Webtags#Date_.26_Time|Date &Time]], [[Webtags#Day/Night/Sun/Moon]]
|<#timehhmmss>, <#minute>, <#hour>, <#sunrise>, <#sunset>, <#dawn>, <#dusk>
|<#LatestErrorDate>, <#date>
|<#LastDataReadT>, <#time>, <#metdate>, <#metdateyesterday>, <#update>, <#LastDataReadT>
|-
|-
|[[Webtags#Today]], [[Webtags#Yesterday]]
| Any tag names that don't report times nor dates
| any tag in "Time" column of linked table
| None
|None
| None
|None
| None
|-
|-
|[[Webtags#Monthly]], [[Webtags#Yearly]]
| [[Webtags#No_Commas]]
| any tag in "Time" column of linked table
| None
| any tag in "Date" column of linked table
| None
|None
| None
|-
| [[Webtags#Date_.26_Time|Date &Time]], [[Webtags#Day/Night/Sun/Moon]]
| Only <#timehhmmss>, <#minute>, <#hour>, <#sunrise>, <#sunset>, <#dawn>, <#dusk>
| Only <#LatestErrorDate>, <#date>  (but no others)
| Only <#LastDataReadT>, <#time>, <#metdate>, <#metdateyesterday>, <#update>, <#LastDataReadT>
|-
| [[Webtags#Today]], [[Webtags#Yesterday]]
| Any tag name in "Time" column of linked table
| None
| None
|-
| [[Webtags#Monthly]], [[Webtags#Yearly]]
| Any tag name in "Time" 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
|-
|-
|[[Webtags#All_Time]], [[Webtags#Monthly_All_Time_Records]]
|[[Webtags#All_Time]], [[Webtags#Monthly_All_Time_Records]]
|n/a
| None (all tag names combine both time and date)
|n/a
| None (all tag names combine both time and date)
|any tag in "Date/Time" column of linked table
| Any tag name in "Date/Time" column of linked table
|}
|}
^ 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.
===Locales===
The default format for many tag names reporting date and/or time is dependent on the locale you are using for running Cumulus (1 or MX).
The effect of some output format modifiers is also dependent on locale.
For MX running on most operating systems (and therefore using Mono),  type <code>locale</code> to see the default locale that will be adopted when mono-complete is installed as MX will, by default, take locale setting from Mono. When you start MX, you can ask it to use a different locale to that picked up by Mono, by adding the parameter "-lang locale-code", see examples at [[MX_on_Linux#Parameter_for_changing_Locale]].  For example, the Australian English language with UTF-8 encoding locale is defined as: en_AU.UTF-8.
The available locales on your computer in Linux are listed by <code>locale -a</code>. For example, the Russian locale would be selected as the one your computer uses ''for the current session only'' by using <code>LANG=ru_RU.utf8</code> either typed into a terminal session before you start MX, or used as a parameter (preceded by "-") as you start MX interactively.
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.
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.
===Time zones===
Before I explain what time/date output modifiers can do, something they can't do.


===What can time/date output modifiers do?===
All web tag outputs are in local time, except '''<#timeUTC>'''.


These output format modifiers allow you to override the default display format for a particular web tag (subject to restrictions seen in last sub-section),
Although Cumulus 2 internally stored all date/times in UTC, no flavour of Cumulus is currently able to output the time-stamp for any weather extreme in UTC, if your current time is not in UTC.
using the format specifiers to be described later. The characters used to represent year, month, day, hour, minute, second, microsecond, and am/pm; all differ between C1 and MX.  


#You can choose whether 12-hour clock is used with am/pm, or the 24-hour clock is used.
However, for MX only, you can use a script to convert a time to UTC. This is not the place to tell you how to write the script, but taking time of highest pressure today as an example, you would use <#TpressTH format=Hh:mm> and <#TpressTH format=zzz>, the first gives hours and minutes in your local time, and the second gives the offset that needs to be applied to that time to convert it to UTC.
#You can choose to include/exclude leading zero for hours.  
#You can only report the hour if you don't care about the minutes, or only report the minutes if you don't need the hour.
#In most cases you can add seconds to the output, and in some cases either milliseconds or microseconds. This does not imply that Cumulus calculates everything every microsecond, in fact many are only calculated once a minute, but the flexibility is there for time outputs.


===Use of double quotation marks===
===Time resolution===


The general syntax is <tt><#tag_name format=x></tt> where '''x''' can represent a single chacter, or multiple characters without any spaces.
For the legacy software, there may be no point in asking for seconds, as Cumulus 1 did some actions at one minute intervals.


If we need to include spaces, then we have to add double quotation matrks round the right hand side as shown here <tt><#tag_name format="x y z"></tt>
If Cumulus obtained archive data, as part of the catch-up process it can do when it restarts, any time-stamps for that 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===
===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.
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.
[[Category:Cumulus MX]]


====For the legacy software====
====For the legacy software====
Line 275: Line 338:
**(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).
===Effect of Locales===
Locales have already been mentioned twice on this page, now it is time to say what is defined in these locales.


====Date formats====
====Date formats====


Cumulus works with dates specified in either a day before month before year format, or ISO 8601 date format where year comes first (yyyy-MM-dd).  If you are in the USA, you can can combine the month specifier in the previous sub-section, with the day specifier in this sub-section to get an output where the month appears first.
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).


Locales will define a '''Short Date Format''' and a '''Long Date Format'''.  Which date format is used as the default, depends on which web tag is used. What appears in short and long formats depends entirely on the selected locale. 
If you 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>.
 
If you run MX on a computer using Microsoft Windows, then the "locale" is determined by settings in the (now hidden) '''Control Panel''' (go to "Clock and Region" screen, choose "Change date, time or number formats", and enter the formats you want for long and short here).
 
 
On computers running other operating systems, the locale is set when you install "Mono-complete". That is determined by language settings when you set up your computer, but you may be able to edit the configuration to change what is defined for the long and short formats. You can overide the default locale with [[Setting_up_Raspberry_Pi#Parameter_for_changing_Locale|-lang]] parameter when starting MX.
 
There is a single character output format modifier ('''G''' or '''c''') that makes the output appear exactly as defined in short date format, followed by long time format. There are other format codes in table below for other date outputs.


[[#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" | {{Version badge 1}}Delphi Specifier for Cumulus 1.9.x
!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:150px" | [[File:Badge vMx.png]]Mono/.NET Specifier for Cumulus MX
!style="width:600px" | Displays
!style="width:600px" | Displays
Line 304: Line 356:
|G  (as single character format)
|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.
|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 {{Version badge 1}}<#time format=c>[[File:Badge vMx.png]]<#time format=G>
|'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"
|"D MMMM YYYY"
Line 313: Line 365:
|"D MMMM"
|"D MMMM"
|M
|M
|Day of month followed by Month name.
|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
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)
| 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
|TT
Line 324: Line 381:
[[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.
[[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  
|'09:47:56'  (might not use colon in your locale) produced by  
*{{Version badge 1}}<#LastDataReadT format=TT>  
* [[File:Badge v1.png]]<#LastDataReadT format=TT>  
*[[File:Badge vMx.png]]<#LastDataReadT format=T>
*[[File:Badge vMx.png]]<#LastDataReadT format=T>
|}
|}
Line 341: Line 398:
{| class="wikitable" border="1"
{| class="wikitable" border="1"
|-
|-
!style="width:150px" | {{Version badge 1}}Delphi Specifier for Cumulus 1.9.x
!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:150px" | [[File:Badge vMx.png]]Mono/.NET Specifier for Cumulus MX
!style="width:600px" | Displays
!style="width:600px" | Displays
Line 349: Line 406:
|%M
|%M
|Displays the month as a number without a leading zero (1-12).  
|Displays the month as a number without a leading zero (1-12).  
*{{Version badge 1}}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 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 different from the '''format=M''' included in previous table.
*[[File:Badge vMx.png]]Cumulus MX: Note that including a ' ' (space) or '%' before the M makes it a custom modifier, so different from the '''format=M''' included in previous table.
|2
|2
Line 356: Line 413:
|MM
|MM
|Displays the month as a number with a leading zero (01-12).  
|Displays the month as a number with a leading zero (01-12).  
*{{Version badge 1}}Cumulus 1.x.y:If the 'm' or 'M' specifier immediately follows an h, H, HH, or hh specifier, the minute rather than the month is displayed.
* [[File:Badge v1.png]]Cumulus 1.x.y:If the 'm' or 'M' specifier immediately follows an h, H, HH, or hh specifier, the minute rather than the month is displayed.
|'03' produced by <#LastDataReadT format=MM> or  <#metdate format="MM">
|'03' produced by <#LastDataReadT format=MM> or  <#metdate format="MM">
|-
|-
Line 378: Line 435:
{| class="wikitable" border="1"
{| class="wikitable" border="1"
|-
|-
!style="width:150px" | {{Version badge 1}}Delphi Specifier for Cumulus 1.9.x
!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:150px" | [[File:Badge vMx.png]]Mono/.NET Specifier for Cumulus MX
!style="width:600px" | Displays
!style="width:600px" | Displays
Line 386: Line 443:
|%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). [[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').
|27 produced by {{Version badge 1}}<#metdate format="d">[[File:Badge vMx.png]]<#metdate format="%d">
|27 produced by [[File:Badge v1.png]]<#metdate format="d">[[File:Badge vMx.png]]<#metdate format="%d">
|-
|-
|dd
|dd
Line 405: Line 462:
|ddddd
|ddddd
|d (as single character format)
|d (as single character format)
|{{Version badge 1}}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).
| [[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 {{Version badge 1}}<#metdate format=dddd>
|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'
[[File:Badge vMx.png]]<#metdateyesterday format=d> ''but not''  <#yesterday=d> which would return just '22'
|-
|-
Line 436: Line 493:
===Time formats===
===Time formats===


Here context matters, so both standard (single character) and custom (two or more characters) formats are shown in the following table.  
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 durations and clock times.


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>
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"
{| class="wikitable" border="1"
|-
|-
!style="width:150px" | {{Version badge 1}}Delphi Specifier for Cumulus 1.9.x
!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:150px" | [[File:Badge vMx.png]]Mono/.NET Specifier for Cumulus MX
!style="width:600px" | Displays
!style="width:600px" | Displays
Line 449: Line 506:
|%h
|%h
|Displays the hour (12 hour clock) without a leading zero (1-12)  
|Displays the hour (12 hour clock) without a leading zero (1-12)  
| 7
|-
|-
|h ''AM/PM''
|h ''AM/PM''
Line 454: Line 512:
|Displays the hour (12 hour clock) without a leading zero (1-12)  in combination with AM/PM.  
|Displays the hour (12 hour clock) without a leading zero (1-12)  in combination with AM/PM.  


{{Version badge 1}}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 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 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:nn [''AM/PM'']
Line 462: Line 521:
|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].
|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].


{{Version badge 1}}For Cumulus 1, the minutes can be represented by 'mm' (instead of "nn") only when appearing in combination with 'h'
[[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 {{Version badge 1}} <#LastDataReadT format="h:nn am/pm">[[File:Badge vMx.png]] <#LastDataReadT format="h:mm tt">
|'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 (or ''H'')
|%H
|%H
|Displays the hour '''using 24 hour clock''' without a leading zero (0-23). [[File:Badge vMx.png]]Note that including a ' ' (space) or '%' before the "H" makes it a custom modifier, needed because H is on its own.
| 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  
|7 produced by  
*{{Version badge 1}}<#daylength format=H>
* [[File:Badge v1.png]]<#daylength format=H>
*[[File:Badge vMx.png]]<#daylength format=%H>
*[[File:Badge vMx.png]]<#daylength format=%H>
|-
|-
|H:mm (or ''H:nn'')
|H:mm (or ''H:nn'')
|H:mm
|H:mm
|Displays the hour using 24 hour clock without a leading zero (0-23) followed by 2 digit minutes. [[File:Badge vMx.png]]Note that %, of previous example, is not needed when H is not on its own.
| 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.  
 
[[File:Badge vMx.png]]Note that %, of previous example, is not needed as the H is not on its own.
|'6:27' or '17:49' produced by <#LastDataReadT format="H:mm">
|'6:27' or '17:49' produced by <#LastDataReadT format="H:mm">
|-
|-
|HH (or ''hh'')
|HH (or ''hh'')
|HH
|HH
|Displays the hour using 24 hour clock with a leading zero (00-23).
| 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>
|'06' or '17' produced by <#LastDataReadT format=HH>
|-
|-
|hh [''am/pm'']
|hh [''am/pm'']
|hh [''tt'']
|hh [''tt'']
|Displays the hour (12 hour clock) with a leading zero (01-12) [optionally in combination with am/pm].
| 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].


{{Version badge 1}}For Cumulus 1 the case output for the optional 'am/pm' depends on the case used for that parameter as shown later in this table
[[File:Badge v1.png]]For Cumulus 1 the case output for the optional 'am/pm' depends on the case used for that parameter as shown later in this table


[[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
[[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
|'07 am' produced by
*{{Version badge 1}} <#LastDataReadT format="hh am/pm">
* [[File:Badge v1.png]] <#LastDataReadT format="hh am/pm">
*[[File:Badge vMx.png]] <#LastDataReadT format="hh tt">
*[[File:Badge vMx.png]] <#LastDataReadT format="hh tt"> if locale specifies lower case
|-
|-
|hh:mm (or ''hh:nn'' or 'HH:NN') [''am/pm'']
|hh:mm (or ''hh:nn'' or 'HH:NN') [''am/pm'']
|hh:mm [''tt'']
|hh:mm [''tt'']
|Displays the hour (12 hour clock) with a leading zero (01-12) followed by 2 digit minutes [optionally in combination with am/pm].
| 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].
*{{Version badge 1}}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, and the case output for am/pm depends on the case used for that parameter as shown later in this table. As Cumulus 1 is case insensitive there are variants with capital letters available.
* [[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, and the case output for am/pm depends on the case used for that parameter as shown later in this table. As Cumulus 1 is case insensitive there are variants with capital letters available.
*[[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
*[[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
|'8:27 am' produced by
* {{Version badge 1}} <#LastDataReadT format="h:nn am/pm">
* [[File:Badge v1.png]] <#LastDataReadT format="h:nn am/pm">
*[[File:Badge vMx.png]] <#LastDataReadT format="h:mm tt">
*[[File:Badge vMx.png]] <#LastDataReadT format="h:mm tt">
|-
|-
|n
|n
|%m
|%m
|Displays the minute without a leading zero (0-59).  
|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.
[[File:Badge vMx.png]] As other examples show, the % is only needed when "m" is on its own.
|7 produced by
| 7 produced as a duration in minutes by
* {{Version badge 1}}<#daylength format=n>
* [[File:Badge v1.png]]<#daylength format=n>
*[[File:Badge vMx.png]]<#daylength format=m>
*[[File:Badge vMx.png]]<#daylength format=m>
|-
|-
|nn
|nn
|mm
|mm
|Displays the minute with a leading zero (00-59).  
|Displays the minutes of any duration or clock time, with a leading zero (00-59).  
|'07' produced by  
|'07' produced as a duration in minutes by
*{{Version badge 1}}<#daylength format=nn>
* [[File:Badge v1.png]]<#daylength format=nn>
*[[File:Badge vMx.png]]<#daylength format=mm>
*[[File:Badge vMx.png]]<#daylength format=mm>
|-
|-
|s
|s
|%s
|%s
|Displays the second without a leading zero (0-59).  
|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.
[[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.
Line 550: Line 613:
[[File:Badge vMx.png]]The 'fff' modifier in MX can actually be extended to 'ffffff' for output to a millionth of a second!
[[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  
| 09:47:25.000' produced by  
*{{Version badge 1}}<#time format=hh:nn:ss.zzz>
* [[File:Badge v1.png]]<#time format=hh:nn:ss.zzz>
*[[File:Badge vMx.png]]<#time format=hh:mm:ss.fff>
*[[File:Badge vMx.png]]<#time format=hh:mm:ss.fff>
|-
|-
Line 570: Line 633:
|am/pm or Am/Pm or AM/PM
|am/pm or Am/Pm or AM/PM
|tt
|tt
|{{Version badge 1}}Uses the 12-hour clock for the preceding h or H specifier, and displays 'am' for any 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 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 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".
Line 577: Line 640:
|h a/p
|h a/p
|h t
|h t
|Uses the 12-hour clock for the preceding h or H specifier, and displays 'a' for any hour from midnight until before noon, and 'p' for noon or any hour after noon.
|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.
{{Version badge 1} The a/p specifier can use lower, upper, or mixed case, and the result is displayed accordingly.
 
[[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".
[[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".
Line 614: Line 678:
==Including literals in format parameters==
==Including literals in format parameters==


As stated long ago on this page, if you are going to include spaces, or any other characters not defined in tables above, you must put double quotes round the whole specifier folowing the equals sign e.g. <tt><#YearTempHT format="hh nn"></tt> can be used with Cumulus 1.9.x. Consequently, you cannot include double quote characters in any other position (see [[Php_webtags#Web_tag_Complications| here for work-around]]).
[[#Use of spaces]] explained how double quotes were needed for date/time output specifiers containing spaces. It briefly talked about including literals, and we will expand on that now.
 
Consequently, you cannot include double quote characters in any other position (see [[Php_webtags#Web_tag_Complications| here for work-around]]).


You should put anything that is additional, to the defined format modifier specification below, into single quotation marks to prevent it being interpreted as a date or time format modifier.  In MX, such single quotation marks should include the spaces round the additional literal text.
You should put anything that is additional, to the defined format modifier specification below, into single quotation marks to prevent it being interpreted as a date or time format modifier.  In MX, such single quotation marks should include the spaces round the additional literal text.
Line 658: Line 724:




== 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 691: Line 762:
** 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==
Sfws
5,838

edits

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

Navigation menu