Webtags/Parameters (preserving history): Difference between revisions

This page is about parameters used for modifying Cumulus web tags. To put these into context, let us learn the terminology with cross-references to where those features are explained further.

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.

*a [[Xml_webtags|eXtensible Mark-up Language (XML)]] file.

In the position in the file where Cumulus is to insert the relevant data, place a web tag in the '''general format''' specified here:   

<pre><#tag_name [optional input selection parameters] [optional output modification parameters]></pre>

The tag_name in the general format above is case sensitive, so please type the tag name exactly as shown in the web tag columns in the tables on the [[Webtags|web tags page]].

*Input modifying

*Output modifying

These are explained below, after the warning on case sensitivity.

The optional input parameters always use lower case, so please type them exactly as shown in the sections dealing with input parameters on this page.

The optional output parameters are case insensitive when used in Cumulus 1. But for Cumulus 2 and later, so this includes MX, the output parameters are case sensitive and also dependent on what other output formatters are being used if any, so please read the sections on output parameters and study the examples in the tables carefully.

'''Most web tags do not require any input parameters'''.  

|   '''d''' specifies number of days ago, '''h''' specifies number of hours ago, and '''m''' specifies number of minutes ago.  

| Cumulus 1.9.3 beta build 1033

* <#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.

* '''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.

'''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!'''

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

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

| Listed web tags take '''r=-ww'''

* Monthly tags also take: '''m=N y=nnnn'''

* <#SunshineHoursMonth r=-1> for last months total

Yearly examples:

* <#SunshineHoursYear r=-2> total for the year before last (if current year is 2021, that is same as previous example)

*A few web tags always need an output format specifier

*Some web tags never use an output format specifier

*The majority of web tags either can use an output format parameter, but they have a default output if there is no output format modifier.

 

This page does not tell you which web tags fall into each of the above 3 types.

To make life more complicated, the availability of output format parameters for particular web tags is dependent on which Cumulus release you are running.  There is a general [[Webtag_Applicability|discussion about applicability]], but that does not yet specify dependencies for individual [[Webtags|web tags]].  

The output modification options available, if you are using a MX release, include:

* if your locale specifies that integer and decimal parts of real numbers are separated by a comma, there is an ouput parameter to replace that decimal comma by a decimal point for any script that does not recognise decimal commas

==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 tc=y></tt>  

#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

#*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.

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

Internally, Cumulus stores numbers in binary. You cannot represent base 10 decimal places exactly in base 2. Therefore, Cumulus stores to a precision that would generally give about 24 significant figures when expressed in base 10.  

The number of decimal places output by default in any web tag varies, as each is coded individually. The default output from a web tag is generally rounded to one, or two decimal places, although in a few cases it is rounded to nearest integer. People have found that default does not always suit them, maybe they feel their instrumentation does not produce measurments to that precision, and so gradually Cumulus has allowed more and more of its output to take an output format modifier that allows people to control number of decimal places shown with rounding.

*<tt>dp=i</tt> is used for both Cumulus 1 and MX.

**The value '''i''' following the attribute '''dp''' is an integer, it represents how many decimal places you want for the output you see.

Whilst many people want Cumulus to round output as done by the previous parameters, there are circumstances when rounding down (or truncation) gives the result desired. This output format modifier is only available in MX.

*<tt>tc=y</tt> is the truncation parameter, the attribute '''tc''' takes the value 'y' to remove decimal places by truncation. e.g. <#MoonAge tc=y>.

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

# 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''.

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

# 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]].

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.