Webtags/Parameters: Difference between revisions

From Cumulus Wiki
Jump to navigationJump to search
26,774 bytes removed ,  16:07, 4 October 2022
m
(6 intermediate revisions by the same user not shown)
Line 141: Line 141:


=== Multiple Output Format Modifier parameters for times and dates ===
=== Multiple Output Format Modifier parameters for times and dates ===
In general '''all date/time tags will accept format strings''' with some exceptions. CumulusMX just passes the format string to the datetime formatter, it does not do any of its own formatting and therefore the Microsoft page are the only valid reference:
# [https://learn.microsoft.com/en-us/dotnet/standard/base-types/standard-date-and-time-format-strings Standard date and time format strings]
# [https://learn.microsoft.com/en-us/dotnet/standard/base-types/custom-date-and-time-format-strings Custom date and time format strings]
The user is advised to study those pages, relate to what he wants and experiment before getting to the forum and ask questions.
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 "--:--".  Equally, many of the tag names that describe extreme records for this month/year/all-time are not defined until the respective period reaches its second day, so again those tags may output hyphens. When hyphens are output, output modifiers have no effect.


To give you an idea what these modifiers are about let's start with a simple example. Suppose you want date/time in ISO 8601 format:
To give you an idea what these modifiers are about let's start with a simple example. Suppose you want date/time in ISO 8601 format:
# This means, something like ''2019-02-28 06:59:05''.
# This means, something like ''2019-02-28 06:59:05''.
# Take the tag name (from tables on the [[Full_list_of_Webtags|Full list of Webtags]] page)
# Take the tag name (from tables on the [[Full_list_of_Webtags|Full list of Webtags]] page)
# Next check [[#Which tag names take date/time output formatting modifiers|the next paragraph]] to see if that tag accepts both time and date 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 2, but all the rest is typed as shown.
# If your 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 links above.
# To explain each element in that format value, look in [[#Time formats|Time formats]], [[#Year formats|Year formats]], [[#Month formats|Month formats]], [[#Day formats|Day formats]], [[#Use of spaces|Use of spaces]], [[#Including literals in format parameters|Including literals in format parameters]].
 
Should you want a different date/time format, then the sub-sections just referenced should help you to select a different arrangement, although there are some more options in [[#Date formats]].


==== Which tag names take date/time output formatting modifiers ====
'''NOTE:''' The character '''%''' used in the format strings defines the following character as a custom format specifier. E.g. ''<#date format=%h>'' produces the hour while ''<#date format=h>'' produces an error because the 'h' as single standard format character does not exist.
In general '''all date/time tags will accept format strings''' with some exceptions. Given the sheer number of Webtags it is deemed not useful to indicate which webtags exactly do not conform to this rule. The user is invited to use the default Webtag for its purpose and then try a modification if it is not satisfactorily.  


If you think a formatting is in error (e.g. you can't get what you want) please report in the forum: you may have made an error or it is a bug or it needs to be documented specifically.
'''NOTE:''' The character '''\''' used in format strings takes the next character as a literal in the output string. E.g. ''<#date format="%h \h">'' produces '10 h'.


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 "--:--".  Equally, many of the tag names that describe extreme records for this month/year/all-time are not defined until the respective period reaches its second day, so again those tags may output hyphens. When hyphens are output, output modifiers have no effect.
'''NOTE:''' Any other character is copied to the result string unchanged. E.g. ''<#date format="Some text %h \h">'' produces 'So16e aexa 10 h' and ''<#date format="So\m\e \tex\t %h \h">'' produces 'Some text 10 h'.


==== Locales ====
==== Locales ====
Line 166: Line 169:
For CumulusMX date and time formats within Windows Operating System, you must use the '''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.
For CumulusMX date and time formats within Windows Operating System, you must use the '''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.


For CumulusMX running on most operating systems (other than Microsoft Windows),  type <code>locale</code> to see the default locale that will be adopted when mono-complete is installed as CumulusMX will, by default, take locale setting from Mono. When you start CumulusMX, you can ask it to use a different locale to that picked up by Mono, by adding the parameter "-lang locale-code", see examples at [[MX_on_Linux#Parameters]].  For example, the Australian English language with UTF-8 encoding locale is defined as: en_AU.UTF-8. The available locales on your computer in Linux are listed by <code>locale -a</code>.
For CumulusMX running on most operating systems (other than Microsoft Windows),  type <code>locale</code> to see the default locale that will be adopted by CumulusMX. It will, by default, take locale setting through Mono. When you start CumulusMX, you can ask it to use a different locale to that picked up by Mono, by adding the parameter "-lang locale-code", see examples at [[MX_on_Linux#Parameters]].  For example, the Australian English language with UTF-8 encoding locale is defined as: en_AU.UTF-8. The available locales on your computer in Linux are listed by <code>locale -a</code>.


For 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 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.
Line 174: Line 177:
All web tag outputs are in local time, except '''<#timeUTC>'''.  
All web tag outputs are in local time, except '''<#timeUTC>'''.  


In most MX releases, 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.
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. To actually do that it would require programming in some language.


====Time resolution====
====Time resolution====


Seconds are supported but may be rounded down or up to 00 (e.g. <#LastDataReadT> supports seconds, but <#LastRainTip> is reported rounded back to previous minute and <#TrrateTM> is reported rounded forward to the next minute). It is up to the user to format what he wants and adjust that format if not useful.
Seconds are supported but may be rounded down or up to 00 (e.g. <#LastDataReadT> supports seconds, but <#LastRainTip> is reported rounded back to previous minute and <#TrrateTM> is reported rounded forward to the next minute. It is up to the user to format what he wants and adjust that format.


==== Conversion from legacy Cumulus to CumulusMX ====
==== Conversion from legacy Cumulus to CumulusMX ====
Line 184: Line 187:
You have to change, at least check, all date/time formatting for Webtags you use when moving from the legacy Cumulus 1 to CumulusMX.  
You have to change, at least check, all date/time formatting for Webtags you use when moving from the legacy Cumulus 1 to CumulusMX.  


Best method probably is to migrate and look at your website or reports - wherever you use your Webtags - and check your date/time formats. Then modify where you think it is required.
Best method probably is to migrate to CumulusMX. Then first check your log on Webtag error and then look at your website or reports - wherever you use your Webtags - and check your date/time formats. Then modify where you think it is required.
 
====Year formats====
 
There are only two options
 
{| class="wikitable" border="1"
|-
!style="width:150px" | Specifier
!style="width:600px" | Displays
!style="width:600px" | Example
|-
|yy
|Displays the year as a two-digit number (00-99).
|19 produced by <#LastDataReadT format=yy>
|-
|yyyy
|Displays the year as a four-digit number (2000-9999).
|2009 produced by <#LastDataReadT format=yyyy>
|}
 
====Month formats====
There are four specifiers:
 
{| class="wikitable" border="1"
|-
!style="width:150px" | Specifier
!style="width:600px" | Displays
!style="width:600px" | Example
|-
|%M
|Displays the month as a number without a leading zero (1-12).
 
Note that including a '%' before the M makes it a custom modifier giving a different output to the '''format=M''' (which produces e.g. '3 october').
|10 produced by <#date format=%M>
|-
|MM
|Displays the month as a number with a leading zero (01-12).
|'03' produced by <#LastDataReadT format=MM> or  <#metdate format="MM">
|-
|MMM
|Displays the month using the strings defined for '''short month name''' in the Locale.
 
Note that some locales produce a dot after the three letter abbreviation!
|'Jun.' produced by <#metdate format="MMM"> depending on the locale
|-
|MMMM
|Displays the month as a full name using the strings appropriate to the Locale.
|'June' produced by <#metdate format="MMMM"> (English locale)
|}
 
[VERIFY!!]
'''CAUTION:''' Cumulus MX has yet another complication, a web tag can return different months depending on whether the output modifier for month is used with, or without, an output modifier for day.  Take two examples <code><#metdateyesterday format=yyyy-MM-dd></code> and <code><#metdateyesterday format=yyyy-MM></code>, these can produce different months when processed by MX on same day at near enough same time! Let us assume the first is reporting (in a particular year) the first day of June, the second would report the month of May in same year!
 
====Day formats====
 
All locales offer both numerical and alphabetical formats for representing a day.
 
The table below shows the specifications for the day part of any date specifications. 
 
{| class="wikitable" border="1"
|-
!style="width:150px" | Specifier
!style="width:600px" | Displays
!style="width:600px" | Example
|-
| %d
|Displays the day as a number without a leading zero (1-31).
 
Note that Cumulus MX requires '%' to be included, as 'd' on its own is inconsistent.
|27 produced by <#metdate format="%d">
|-
|dd
|Displays the day as a number with a leading zero (01-31).
|07 produced by <#metdate format="dd">
|-
|ddd
|Displays the day as an abbreviation using the strings appropriate to the Locale. It may produce a dot at the end of the string.
|'Wed' produced by <#metdate format="ddd"> (UK English locale)
|-
|dddd
|Displays the day as a full name using the strings appropriate to the Locale.
|'Friday' produced by <#metdate format="dddd"> (English locale)
|}
 
====Date formats====
 
The [[#Year formats|Year formats]], [[#Month formats|Month formats]], and [[#Day formats|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.
 
The [[#Locales|locale]] 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''') listed at the start.
 
If you are in the USA, Cumulus will only use your month first date internally for the start date (see [[Cumulus.ini]]), that format will not be used in any files in the [[Data folder|data sub-folder]], but you can see your preferred format in the settings pages, in the extreme record editing pages, and by default as an output from many (not all) web tags.  For any web tags that do permit use of output date modification format parameters, you can can combine any month specifier, with any day of month specifier, in that order, to get an output where the month appears first (see example in table below).
 
{| class="wikitable" border="1"
|-
!style="width:150px" | Specifier
!style="width:600px" | Displays
!style="width:600px" | Example
|-
| G
| 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.
| '22/03/2019 09:47:25' produced by <#time format=G>
|-
| ddddd
| Displays the date using the format given by the Short Date format.
 
Note: 'd' (when on its own, without '%' prefix) displays seemingly inconsistent behaviour as its effect depends on the tag name) with which it is used.
| '22/03/2019' (British Locale) produced by <#metdate format=ddddd>
|-
|D
|Displays the date using the format given by the Long Date format. 
| '22 March 2020' (British Locale)
|-
|M
|Day of month followed by Month name. 
 
Note this is different output to '''format=%M''' (see [[#Month formats]]). Not applicable to USA locales.
| 22 July (English Locale)
|-
|"MMMM d"
| USA format of month before day of month if M alone does not work
| July 4 (USA format)
|}
 
====Time formats====
 
 
Here context matters, so both standard (single character) and custom (two or more characters) formats are shown in the following table.  As explained earlier, time formats can be used with both time-duration reporting and clock time reporting.
 
In some rows of this table, square brackets [] indicate optional items, they are included just to make it clearer how items can be combined in a single output parameter.  If you want to include what is shown in square brackets you don't type the square brackets e.g. <tt><#LastDataReadT format="h:nn am/pm"></tt>
{| class="wikitable" border="1"
|-
!style="width:150px" | Mono/.NET Specifier for Cumulus MX
!style="width:600px" | Displays
!style="width:600px" | Example
|-
|T  (as single character format)
|Displays the time using the '''Long Time format'''.
 
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 <#LastDataReadT format=T>
|-
|%h
|Displays the hour (12 hour clock) without a leading zero (1-12)
| 7
|-
|%h ''tt''
|Displays the hour (12 hour clock) without a leading zero (1-12)  in combination with AM/PM.
 
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).
| 7 PM
|-
|%h:mm [''tt'']
|Displays the hour (using 12 hour clock) without a leading zero (1-12) followed by 2 digit minutes [optionally in combination with AM/PM whose case varies as explained in previous entry].
|'10:27 am' produced by <#LastDataReadT format="h:mm tt">
|-
|%H
| Displays the hour part of any duration or clock time, without a leading zero (0-23).
 
Note that '%' before the "H", this makes it a custom modifier, needed because H is on its own.
|7 produced by
<#daylength format=%H>
|-
| H:mm
| Displays the hour part of any duration or clock time, without a leading zero (0-23) followed by 2 digit minutes for that duration or clock time.
|'6:27' or '17:49' produced by <#LastDataReadT format="H:mm">
|-
|HH
| Displays the hour part of any duration or clock time, using 24 hour clock with a leading zero (00-23).
|'06' or '17' produced by <#LastDataReadT format=HH>
|-
|hh [''tt'']
| Displays the hour part of any duration or clock time, (12 hour clock) with a leading zero (01-12) [optionally, if it is a clock time, in combination with am/pm].
 
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
<#LastDataReadT format="hh tt"> if locale specifies lower case
|-
|hh:mm [''tt'']
| Displays the hour part of any duration or clock time, (12 hour clock) with a leading zero (01-12) followed by 2 digit minutes [optionally, if it is a clock time, in combination with am/pm].
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
<#LastDataReadT format="h:mm tt"> if locale specifies lower case
|-
|%m
|Displays the minutes of any duration or clock time, without a leading zero (0-59).
 
As other examples show, the % is only needed when "m" is on its own.
| 7 produced as a duration in minutes by
<#daylength format=m>
|-
|mm
|Displays the minutes of any duration or clock time, with a leading zero (00-59).
|'07' produced as a duration in minutes by
<#daylength format=mm>
|-
|%s
|Displays the seconds for any duration or clock time, that has resolution to less than a minute, without a leading zero (0-59).
| 9 produced by <#metdate format=%s>
|-
|ss
|Displays the second with a leading zero (00-59).
|'06' or 19 produced by <#LastDataReadT format=ss>
|-
|FFF
|Displays the millisecond without a leading zero. Displays either nothing or displays 1-999. So don't write any code that assumes the MX output is numeric.
 
Note that the system clock (before Windows 10 64-bit systems) only has precision to 15 ms, so don't use this modifier if your Cumulus is running on an old version of Microsoft Windows.
|
|-
|ff (or ''f'')
|Displays hundredths of a second (or tenths) with leading zero(s)
|
|-
|fff
|Displays the millisecond with a leading zero (000-999).
 
Note that the system clock (before Windows 10 64-bit systems) only has precision to 15 ms, so don't use this modifier if your Cumulus is running on an old version of Microsoft Windows.
 
The 'fff' modifier can actually be extended to 'ffffff' for output to a millionth of a second!
| 09:47:25.000' produced by
<#time format=hh:mm:ss.fff>
|-
| zzz
|Displays the offset of any time from UTC in hours and minutes 
| e.g.-07:00
|-
|"h:mm K"
|Effectively another way of including time zone after a time, but it can only be used for time-zones never matching UTC (if understood correctly)
|(no examples supplied yet)
|-
|%t
|Displays the time using the Short Time format.
 
Remember that 't' combined with other specifiers (or preceded by space or '%') has a different meaning - see below.
| '09:47' produced by <#LastDataReadT format=t> (might not use colon in your locale)
|-
|tt
|'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".
|
|-
|h t
|Uses the 12-hour clock for the preceding h or H (clock time) specifier, and displays 'a' for any hour from midnight until before noon, and 'p' for noon or any hour after noon.
 
whether it displays the "a" or "p" in capitals or lower case is determined by the locale settings, not the case of "t".
| see previous example
|-
|/
|Displays the date separator character given by the Date Separator. It might not display a slash.
| '/' for typical British locale
|-
|:
|Displays the time separator character given by the Time Separator, this might not display a colon.
 
Note that by default Cumulus MX expects a locale to use ":" for any time separator.
|':' for British locale
|}
 
==== Literals ====
 
If you are considering use of literals (such as a space) within a output format modifier in a script, '''then don't'''.
 
Instead include whatever precedes the literal in a tag specification, then concatenate on the literal, and finally concatenate another tag specification for whatever is to follow the literal. 
 
An '''example''' to make this clearer is <code>$MXDateTime = '<#date format=yyyy-MM-dd>' . 'T' . '<#time format=hh:mm:ss>';</code>, which is written in PHP Hypertext Pre-processor format, the literal 'T' has been inserted by using two separate web tags surrounding the literal.  The same approach applies if you wanted to replace that "T" with a space.
NOTE: the same string is actually created by  <code>$MXDateTime = '<#date format=s>'</code>.
 
The reason is preventing complex mixup of single and double quotes between the script language and CumulusMX.
 
====Use of spaces====
 
[[File:Badge vMx.png]]The first complication is that the parser that interprets time/date characters has two ways of interpreting a space character, depending on what immediately follows.  In the tables, below, I have used a "%" in various places. In any of those places with a "%", you can insert a space instead,  understanding that space is not a gap between format characters, but simply an alternative to "%" as a special character.  To explain the two ways of interpreting spaces consider as an example '''<#TpressTH format=" h:mm tt">'''. In that example the two spaces are interpreted in two different ways! The "space" before "h" is treated as the same as "%", but as the ''mm'' and ''tt'' are multi-character symbols, that does insert a space after the minutes but before the am/pm. I discuss this later in [[#Migrating from legacy Cumulus 1 to MX]] section.
 
 
If you want spaces to appear between symbols in an output format:
* [[File:Badge v1.png]]Cumulus 1.x.y: Add double quotation marks around everything after equals sign if spaces are present anywhere after that equals sign.
* [[File:Badge vMx.png]] In MX, add double quotation marks around everything after equals sign if spaces are wanted as separators, but you also need to add single quotation marks around the included space. 
** If the first symbol after equals sign is a single character modifier, then it has a different meaning depending on whether it is first specificatiion or is preceded by a "%" or "space" as in example above. If the first modifier inclues more than one letter, then it does not ever take a prefix.
** If the space appears after double characters and the symbol that appears after the space is also double characters (as in example above) the single quotes round the space are optional. 
** If we have single character specifiers, then a space has to be enclosed in single quotes to mark it as a literal, not a modification of the subsequent single character.
 
Literals are discussed fully in the [[#Including literals in format parameters]] sub-section later. If we want to include other characters not to be interpreted by the date time parameter parser, and spaces, then both double and single quotes must be used, and the spaces must be within the single quotes.  An example, that shows all the options that MX allows, with literals is <code> <#TpressH format="\a't 'h:mm'&nbsp;' tt' <nowiki><small>on 'd/M/yyyy' </small></nowiki>'"> </code>.
 
=Some Extra Information=
 
Having covered the basics of both date and time modifiers above, it is time to talk about incorporating other information in an output modifying date/time format specification.
 
 
Basically, we can include literal characters, and we can include HyperText Manipulation Language tags, in our specifiers.
 
Finally, there will be a section on migrating from the legacy Cumulus to MX and how to modify the web tags in your templates to keep them working.
 
==Including literals in format parameters==
 
[[#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.
 
#For example, the word "on" contains the character "n", which for Cumulus versions 1.9.1 to 1.9.4 will be interpreted as a time format modifier unless you put it into single quotation marks. Example of valid Cumulus 1 syntax: <#TtempH format="'at' hh: mm 'on' dd / mm / yyyy">.
#You can include HTML tags (but they cannot have any attributes because both single and double quote characters have defined meanings) and special characters as quoted text within the 'format' parameter.<br>  Example of valid syntax: <#TapptempH format="'at 'h:nn'&nbsp;'am/pm '&lt;small&gt;on' d/m/yyyy'&lt;/small&gt;'">.
#* See next sub-section for more information on incorporating HTML if you are using MX.
 
 
[[File:Badge vMx.png]]Note for MX - you can use single quotation marks round spaces and text (e.g. ' on '), but you can also use '\' as escape character (e.g. for 'on' use '''\o\n''').  However for '''at''' the only alternative is '''\a't''''  because the character t has another meaning and escape followed by a "t" i.e. "\t" becomes a tab!
 
 
{| class="wikitable" border="1"
|-
!style="width:150px" | {{Version badge 1}}Delphi Specifier for Cumulus 1.9.x
!style="width:150px" | [[File:Badge vMx.png]]Mono/.NET Specifier for Cumulus MX
!style="width:600px" | Displays
!style="width:600px" | Example
|-
|'xy'
|'xy' or ''\x\y''
|Characters enclosed in single quotation marks are displayed as such, and do not affect formatting.
 
[[File:Badge vMx.png]]In MX each character to be displayed as it was typed can be prefixed by a backslash. Also remember that any spaces in a MX modifier might need to be within single quotes as space is also used to change what a modifier represents. I told you MX modifiers were more complicated!
|Hyphens are added in this PHP language example  '<#LastDataReadT format=yyyy>'.'-'.'<#LastDataReadT format=MM>'.'-'.'<#LastDataReadT format="dd">'
|}
 
== Using HTML tags within format parameters (available in MX only) ==
 
'''Example using a class to change the look of part of the output'''
 
<pre><#TapptempH format="dd'&nbsp;'MMM'&nbsp;'yyyy'<span class=\'xx\'> at 'HH:mm'</span>'"></pre>
the output from this will look like ''04&nbsp;Dec&nbsp;2018<span class='xx'> at 10:12</span>''
 
'''Note where the quotes are, and where you need to use '\' escape characters'''.
 
'''Example using HTML tags'''
 
<pre><#RecentTS d=2 format="h:mm'&nbsp;'tt'<small>on' d/M/yyyy'</small>'"></pre>
This puts the date in a smaller font than the time
 
 
 
 
== Migrating from legacy Cumulus 1 to MX==
 
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.
 
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 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)
* In the legacy Cumulus, a space is a gap between characters
* 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.
 
=== Examples ===
 
*Examples related to case selection
*#[[File:badge v1.png]] In Delphi, "nn" means "minutes" for Cumulus 1, [[File:Badge vMx.png]]but "minutes" is "mm" for .NET or MONO in Cumulus MX.
*# The hour in 24-hour format with leading zero, in non case sensitive Delphi (Cumulus 1) 'HH' or 'hh' would be treated as same, but in .NET or MONO it must be "HH" (Cumulus MX).
*# The hour in 24-hour format without leading zero, in non case sensitive Delphi (Cumulus 1) 'H' or 'h' would be treated as same, but in .NET or MONO it must be "%H" (Cumulus MX).
*# For 12-hour specifiers, please see the table, as this is far more complicated.
*[[File:Badge vMx.png]]You might be put off by references within .NET and MONO (Cumulus MX) to single/standard characters and custom modifiers, the following 3 examples may add clarity:
*#For example, ''<#MonthTempHD format="d">'' is a single character format modifier, therefore the 'd' acts as a standard modifier, and causes for a date of 22 July 2014 for the highest temperature in the month to be returned in the standard short date format e.g. '22/07/2014' (exact contents for any one date vary by locale).
*#Similarly, ''<#MonthTempHD format="M">'' is a single character format modifier and therefore the 'M' acts as a standard modifier and causes the date for the highest temperature in the month to be returned in the standard day and month format e.g. '22 July' (exact contents for any one date vary by locale).
*#Whilst ''<#metdate format="d M">'' is not a single character format modifier and therefore both the 'd' and the 'M' are interpreted as custom modifiers and cause the current date to be returned as a digit(s) for the day and a digit(s) month (in a without leading zeroes format) e.g. '6 7' would be returned for 6 July.
*#Alternatively,  ''<#MonthTempHD format="%d">'' is NOT a single character format modifier, therefore the 'd' acts as a custom modifier, and causes a date of 22 July 2014 for the highest temperature in the month to be returned as the day of the month only '22' in all locales.
*#Similarly, ''<#MonthTempHD format="%M">'' is NOT a single character format modifier and therefore the 'M' acts as a custom modifier and causes the same date for the highest temperature in the month to be returned as the month number '7'.
 
In both Cumulus 1 and MX if you want a space character within your output, the output specifiers must be enclosed in double quotes. If that space character is next to a non modifier (e.g. around word "at") then the single quote needing to surround the at should be widened to include the spaces in MX, but Cumulus 1 does not care if single quotes excluded spaces. However, with MX, single quotes enclose multiple characters, but there is an alternative way to deal with some single verbatim characters to cover next.
 
So let us compare these two alternative ways that MONO and .NET  escape any characters that are not being used as format specifiers.
* In [[File:badge v1.png]]Delphi you can put the 'verbatim' characters inside single quotes (Cumulus 1); this is often used to (in English) include words like ' on ' and ' at ' in the formatted output.
*in [[File:Badge vMx.png]].NET or MONO you can still use single quotes (as mentioned above extended to include adjacent spaces),
** 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.
 
== Past history for this page==
 
This page is a complete redesign of how to present information that was previously on the [[Webtags]] page, so look there for past content by selecting "history" tab.
 
Trying to make the old design made for the original Cumulus software, work for MX which is now very different, made the old page unwieldy.
 
 
== 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 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:
*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 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.
 
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.
 
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, 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.

Navigation menu