Webtags/Parameters (preserving history): Difference between revisions

From Cumulus Wiki
Jump to navigationJump to search

Webtags/Parameters (preserving history) (view source)

Revision as of 08:37, 18 June 2021

3,816 bytes added ,  08:37, 18 June 2021
m
→‎Input modification Parameters: added beware taken from a forum post in July 2012
m (→‎Forum reference: correction of references to this Wiki)
m (→‎Input modification Parameters: added beware taken from a forum post in July 2012)
(18 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 25: Line 25:


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


Now we get to the terminology for what this Wiki page will document.
Now we get to the terminology for what this Wiki page will document.
Line 44: 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 '''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]] 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
|-
| [[Webtags#Recent_History|'''recent history tags''']]
| 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.
* You can use any combination of the three parameters.
* The same d, h, and m, parameters are used by Cumulus 1 and 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 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.
* 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.
* 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
=== Input Modification Parameters for Recent History ===
| Only one input parameter applies:
 
* The value of "N" supplied should be an integer between 1 and 12
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.
* 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.
 
|-
All values supplied for parameters must be whole numbers.
| Only <#SunshineHoursMonth> and <#SunshineHoursYear>
 
| Values available for current month/year, and for past month/year
If you don't supply any parameters, the result is undefined for Cumulus 1, and an illegal web tag for MX.  
| All web tags take '''r=-ww'''
 
* Monthly tags also take: '''m=N y=nnnn'''
<#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>).
* Yearly tags also take: '''y=nnnn'''
 
Omit input modification parameter to get value for current month/year
<#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.
| MX release 3.12.0
 
| Monthly examples:
<#RecentOutsideTemp d=1 h=1 m=1> will give the temperature one day, one hour and one minute ago.
* <#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
'''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.
* <#SunshineHoursMonth r=-1> for last months total
 
* <#SunshineHoursMonth r=-12> for same month as current month, but one year ago
 
Yearly examples:
=== During catch-up ===
* <#SunshineHoursYear> gives total sunshine hours since 1 minute past midnight on New Year's Day
 
* <#SunshineHoursYear y=2019> for the total for 2019
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.
* <#SunshineHoursYear r=-2> total for the year before last (if current year is 2021, that is same as previous example)
 
| Returns the sunshine hours total in selected period
=== Variations between Builds/Versions ===
|}
 
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 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.


= Output modification parameters =
= Output modification parameters =
Line 107: Line 134:
*if the web tag name represents a real number with integer and decimal parts
*if the web tag name represents a real number with integer and decimal parts
*if you are using MX
*if you are using MX
** It was initially only implemented on a few new web tags (#MoonPercent, #MoonPercentAbs, #MoonAge) for MX versions up to and including 3.5.3. From version 3.6.6 onwards, all web tags that can output real numbers can now use this
**From beta release 3.0.0,  build 3047 (3 February 2019), up to and including release 3.5.3, only implemented on a few new web tags (#MoonPercent, #MoonPercentAbs, #MoonAge)
**From release 3.6.6 onwards (1 June 2020), it was extended to other web tags that output real numbers.
**From release 3.10.5 onwards (29 March 2021), the use of <tt><#tag_name rc=n></tt> became also possible, to ensure decimal comma shown when locale specifies it




Line 114: 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 124: 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 132: 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 159: 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 182: Line 221:
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").
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").


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 231: Line 270:


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 276: Line 316:




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.
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 [[MX_on_Linux#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.
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.
Line 291: Line 331:
|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 {{Version badge 1}}<#time format=c>[[File:Badge vMx.png]]<#time format=G>
|-
|"D MMMM YYYY"
|D
|Long date format
|e.g.4 December 2009
|-
|-
|"D MMMM"
|"D MMMM"
|M
|M
|format=M on its own returns both Month and Day according to local format
|Day of month followed by Month name.
 
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)
|-
|-
Line 329: Line 376:
|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.
*{{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 vMx.png]]Cumulus MX: Note that including a ' ' (space) or '%' before the M makes it a custom modifier e.g. '7' is returned for July as any initial zero is suppressed.
*[[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
|-
|-
Sfws
5,838

edits

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

Navigation menu