Cumulus Wiki

Webtags/Parameters (preserving history): Difference between revisions

Webtags/Parameters (preserving history) (view source)

Revision as of 16:59, 31 July 2021

2,197 bytes added ,  16:59, 31 July 2021
m
→‎Multiple Output Format Modifier parameters for times and dates: improved explanations for d and multiple dd...
m (→‎Multiple Output Format Modifier parameters for times and dates: improved explanations for d and multiple dd...)
Line 207: Line 207:
# Take the tag name (from tables on [[Webtags]] page)
# 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
# Next check in [[#Which tag names take date/time output formatting modifiers]] to see if that tag accepts both time and date modifiers
# Assuming it can, simply modify the web tag as shown here <code><#tag_name format="yyyy-MM-dd HH:mm:ss"></code>.
# Assuming it can do this, we want the tag name to output using the ISO 8601 format something like ''2019-02-28 06:59:05''.
# Now the web tag will output using the ISO 8601 format something like ''2019-02-28 06:59:05''.
# To achieve this, 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]].
 
# 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]].
===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.
 
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>.
 
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.


===Which tag names take date/time output formatting modifiers===
===Which tag names take date/time output formatting modifiers===
Line 313: Line 300:


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.
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===
You cannot,in general, use the same date/time formatting for both the original (legacy) Cumulus and MX.


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.
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 332: Line 320:
====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 346: Line 337:
**".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).  


====Date formats====
===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.
 
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. 
 
Literals are discussed fully in the [[#Including literals in format parameters]] sub-section later. If we want to include other characters not to be interpreted by the date time parameter parser, and spaces, then both double and single quotes must be used, and the spaces must be within the single quotes.  An example, that shows all the options that MX allows, with literals is <code> <#TpressH format="\a't 'h:mm'&nbsp;' tt' <nowiki><small>on 'd/M/yyyy' </small></nowiki>'"> </code>.
 
Finally, the use of literals can cause you ''a problem if you want to use a date/time specification in a script'' because the script wants literal delimiters outside any web tags, so that delimiters remain when the web tag itself has been processed into a string by Cumulus.  This means the type of quotes (single or double) used outside the web tag, cannot be used within the web tag. The complicated sounding (but actually simple solution) is to avoid placing literals, and/or spaces, within any output format specifier, instead put single quotes round the whole content. What you thought of putting as literals within any web tag is instead typed outside with separate web tags for the part of the specification before and after each literal. An example to make this clearer is <code>$MXDateTime = '<#date format=yyyy-MM-dd>' . 'T' . '<#time format=hh:mm:ss>';</code>, which is written in PHP Hypertext preprocessor format, the literal 'T' has been inserted between two separate web tags.


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).
===Year formats===


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>.
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 400: Line 380:
**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 440: Line 421:
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 449: Line 429:
!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===
Sfws
5,838

edits

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