|
|
| (7 intermediate revisions by the same user not shown) |
| Line 1: |
Line 1: |
| This page is the new ''Webtags Parameters'' page. This page is part of a complete rewrite of the ''Webtags'' page. As long as this message exists please refer to [[Webtags/Parameters (preserving history)]].
| |
|
| |
| This page is Work in Progress until this message is deleted.
| |
|
| |
| If any questions or remarks please send a PM to [https://cumulus.hosiene.co.uk/memberlist.php?mode=viewprofile&u=9016 HansR] on the forum. Do not use the ''discussion'' tab unless accompanied by a PM: there is no automated signal to HansR if you use that page.
| |
|
| |
| This page and its subpages will document the Webtags from the point of view of the CumulusMX software and not the Cumulus 1 legacy software. Cumulus 1 is no longer maintained and will eventually disappear. If you are still using it, please refer to the original [[Webtags_(preserving_history)|Webtags]] page where @sfws has tried to give both packages equal value. That effort is no longer maintained in this page. We hope you will understand this approach.
| |
|
| |
| Please do not edit this page while it is being worked on i.e. while this message is still here.
| |
|
| |
| <hr/>
| |
| = Introduction = | | = Introduction = |
|
| |
|
| Line 66: |
Line 55: |
|
| |
|
| '''NOTE:''' Some Cumulus users say that using <#RecentOutsideTemp d=1 m=1> is more reliable at getting the temperature (or whatever tag name you have quoted) at a similar time the day before, the extra minute apparently gives better results when you might not be using Cumulus all the time, or your weather station might have some drift on when it supplies readings. See which works best for you. | | '''NOTE:''' Some Cumulus users say that using <#RecentOutsideTemp d=1 m=1> is more reliable at getting the temperature (or whatever tag name you have quoted) at a similar time the day before, the extra minute apparently gives better results when you might not be using Cumulus all the time, or your weather station might have some drift on when it supplies readings. See which works best for you. |
| '' REMARK HansR for review:'' This seems a strange explanation to me. It seems more having something to do with updating the Recent History database while being queried as the processes in CMX most likely are independent.
| |
|
| |
|
| === Examples for Monthly Records === | | === Examples for Monthly Records === |
| Line 130: |
Line 118: |
| If the tag name gives an output that is defined as text, or as an integer, then none of these can be used. | | If the tag name gives an output that is defined as text, or as an integer, then none of these can be used. |
|
| |
|
| ''[Remove this after review?? HansR]''
| | ====== Intermezzo ====== |
| Weather stations report [[Calculate_Missing_Values#Source_value|values]] as integers. Cumulus converts these to the user's desired units, and that processing can add decimal places, as it may involve division by a factor of 10, or multiplication by a conversion factor. Obviously, the sensor has a particular accuracy, and this conversion process can introduce additional errors, as can the storing in binary, Cumulus generally (not in every case) stores to a precision that would generally give about 24 significant figures when expressed in base 10. | | Weather stations report [[Calculate_Missing_Values#Source_value|values]] as integers. Cumulus converts these to the user's desired units, and that processing can add decimal places, as it may involve division by a factor of 10, or multiplication by a conversion factor. Obviously, the sensor has a particular accuracy, and this conversion process can introduce additional errors, as can the storing in binary, Cumulus generally (not in every case) stores to a precision that would generally give about 24 significant figures when expressed in base 10. |
| | | |
| The handling of each tag name is coded individually, so there are no simple rules for defining the default number of decimal points that will be shown by default. In general, Cumulus does consider the units chosen for outputs. As Cumulus has been developed, people have commented that these defaults do not reflect the precision of their instrumentation (weather stations used with Cumulus tend not to have the accuracy of those used by meteorologists, or are not re-calibrated as often). | | The handling of each tag name is coded individually, so there are no simple rules for defining the default number of decimal points that will be shown by default. In general, Cumulus does consider the units chosen for outputs. As Cumulus has been developed, people have commented that these defaults do not reflect the precision of their instrumentation (weather stations used with Cumulus tend not to have the accuracy of those used by meteorologists, or are not re-calibrated as often). |
| ''[END Remove this after review?? HansR]''
| |
|
| |
|
| From release 3.12.0, you can set the default number of decimal places to output for all derivatives of temperature, pressure, etc. by [[Cumulus.ini#Units.2C_Derivative_Options.2C_and_Decimal_Places|advanced settings]]. Those settings can force output as integers, in which case the parameter for controlling number of decimal places have no effect. | | From release 3.12.0, you can set the default number of decimal places to output for all derivatives of temperature, pressure, etc. by [[Cumulus.ini#Units.2C_Derivative_Options.2C_and_Decimal_Places|advanced settings]]. Those settings can force output as integers, in which case the parameter for controlling number of decimal places have no effect. |
| Line 141: |
Line 128: |
|
| |
|
| === 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 thereore the Microsoft page are the only valid reference: | | 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/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] | | # [https://learn.microsoft.com/en-us/dotnet/standard/base-types/custom-date-and-time-format-strings Custom date and time format strings] |
| Line 152: |
Line 139: |
| # 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) |
| # 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. | | # 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. |
| # To explain each element in that format value, look in links above. | | # To explain each element in that format value, look in links above. |
|
| |
|
| 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. | | '''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. |
|
| |
|
| 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'. | | '''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'. |
|
| |
|
| 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'. | | '''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 177: |
Line 164: |
| 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==== |
| Line 189: |
Line 176: |
| 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. | | 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. |
|
| |
|
| =Some Extra Information=
| | [[Category:Cumulus_MX]] |
| | |
| 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' 'am/pm '<small>on' d/m/yyyy'</small>'">.
| |
| #* 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' 'MMM' 'yyyy'<span class=\'xx\'> at 'HH:mm'</span>'"></pre>
| |
| the output from this will look like ''04 Dec 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' '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.
| |
