5,838
edits
Webtags (preserving history): Difference between revisions
From Cumulus Wiki
Jump to navigationJump to search
Webtags (preserving history) (view source)
Revision as of 08:19, 8 September 2020
, 08:19, 8 September 2020→What this article covers
| (19 intermediate revisions by the same user not shown) | |||
| Line 29: | Line 29: | ||
=What this article covers = | =What this article covers = | ||
At the last count, a 3.5.x version of MX produces nine and a half million '''web tags'''! But the file mentioned in previous section contains just 717 items (later versions of MX raise this count by another forty tags or so). How come this discrepancy? | #At the last count, a 3.5.x version of MX produces ''nine and a half million'' '''web tags'''! | ||
# Those millions of web tags can actually produce billions of different outputs! | |||
#But the file mentioned in previous section contains just 717 items (at 3.5.0, later versions of MX raise this count by another forty tags or so). | |||
#How come this discrepancy? | |||
Well each web tag has the general format <tt><#tag_name optional_input_parameter optional_output_parameter></tt> and it is adding | *Well each web tag has the general format <tt><#tag_name optional_input_parameter optional_output_parameter></tt> and it is adding the optional input parameters that allow 717 tag names to define 9½ million values! | ||
*Adding all possible different output parameters generates the billions of different outputs! | |||
Consequently, this article describes: | Consequently, this article describes: | ||
*Over 7 hundred web tags | *Over 7 hundred web tags -'''THIS ARTICLE MAY NOT CONTAIN ALL WEB TAGS AVAILABLE IN LATEST VERSION - It depends on someone updating this article if the developer does not have time to do so''' | ||
*A score of input parameters that modify some of those tags | *A score of input parameters that modify some of those tags (meaning some web tags can represent 12 different months for example) | ||
*The components that make up output parameters | *The components that make up output parameters (a guide to how you modify the output format) | ||
*The way that some of those date modifiers are used for naming NOAA reports | ** some control number of decimal places | ||
** one controls whether decimal comma (if used) is replaced by decimal point (useful for some script languages) | |||
**the majority modify the output from almost all web tags that report a time and/or date (there are so many ways to represent times and dates this multiples up the available output considerably) | |||
*The way that some of those date modifiers are used for naming NOAA reports (a simple, but useful table) | |||
The tables below are not able to indicate which of the billions of combinations possible are valid or invalid for | The tables below are not able to indicate which of the billions of combinations possible are valid or invalid for particular tag names nor for particular release versions.. | ||
==Applicability by version and build== | ==Applicability by version and build== | ||
The tip at the start of this article tells you how to check which tags are available in whatever build of Cumulus you are actually using. Given how often a new release alters either what web tags are available or what parameters can be used with particular web tags, it is | The tip at the start of this article tells you how to check which tags are available in whatever build of Cumulus you are actually using. Given how often a new release alters either what web tags are available or what parameters can be used with particular web tags, it is possible the tables below do not list all web tags at any version, and the tables can't say which modifiers are available at your version. | ||
Because Cumulus 2 is no longer available, it has been ignored in the tables below. | Because Cumulus 2 is no longer available, it has been ignored in the tables below. It never really worked for web page generation, so if you happen to have installed Cumulus 2 from when it was available, you probably don't care which web tags it supports. | ||
[[File:Badge v1.png]]This badge is used to highlight text that applies to Cumulus 1. | [[File:Badge v1.png]]This badge is used to highlight text that applies to Cumulus 1. | ||
| Line 252: | Line 259: | ||
===Inconsistency in use of "T"=== | ===Inconsistency in use of "T"=== | ||
* | *The newer web tags for '''today''' include a "T" as a suffix, the older ones do not. | ||
*"T" | **The lack of a "T" in some today tags causes some confusion with all-time record tags as they have a similar naming structure to these older today web tags. | ||
**This is particularly confusing and is why you must look up today, and all-time, tags in the tables in this article. | |||
*The time-stamp tags add a "T" to the corresponding web tag for the value, but in an inconsistent way: | |||
**the T is a prefix sometimes and | **the T is a prefix sometimes and | ||
**the T is a suffix sometimes | **the T is a suffix sometimes | ||
*This is particularly confusing and is why you must look up time-stamp tags in the tables in this article. | **This is particularly confusing and is why you must look up time-stamp tags in the tables in this article. | ||
===Choosing script variable names derived from tag names=== | ===Choosing script variable names derived from tag names=== | ||
| Line 575: | Line 584: | ||
|- | |- | ||
|(not available) | |(not available) | ||
| | | zzz | ||
|Displays the offset of any time from UTC in hours and minutes | |Displays the offset of any time from UTC in hours and minutes | ||
| e.g.-07:00 | | e.g.-07:00 | ||
|- | |- | ||
| Line 680: | Line 689: | ||
=The web tag application programming interface= | =The web tag application programming interface= | ||
[[File:Badge vMx.png]] Available from version 3.7.0 (build 3089). | [[File:Badge vMx.png]] Available from version 3.7.0 (build 3089) released 28 July 2020. It was proposed in January 2015, see Steve Loft [https://cumulus.hosiene.co.uk/viewtopic.php?p=101496#p101496 plan to add a call where you supply a list of items (probably web tag names), and you get back the equivalent data]. | ||
== Where to use == | == Where to use == | ||
| Line 686: | Line 695: | ||
This is meant for services either on the same computer as Cumulus or on your local network. It is not secure, and should not be available, nor requested, via any external network or the internet. | This is meant for services either on the same computer as Cumulus or on your local network. It is not secure, and should not be available, nor requested, via any external network or the internet. | ||
The [[MX Administrative Interface]] uses some application programming interface (api) calls to obtain the data each web page in that interface needs, and another api to return the results of any edit made. If you wanted your '''CumulusMX/interface/todayyest.html''' web page to include something else (e.g. snow falling/lying/depth) you would edit that HTML page to have the extra sub-table you want (you cannot extend the existing rainfall table as that is dynamically created by existing api) and you would edit the associated JavaScript file '''CumulusMX/interface/js/todayyest.js''' to add a new api call seeking snowdepth, snowfalling, snowlying tags for today (unfortunately there are no tags for yesterday's snow) and to place the returned values into your new sub-table (probably using jQuery to make it easy). In a similar way, you could add anything where today and yesterday tags are available such as UV Index. | |||
In earlier versions of Cumulus if you wanted to make use of values processed by Cumulus, you wrote a script file referencing the web tags you wanted to use, and let Cumulus process that file at an interval set in the settings, then you had to write something to process the results at the relevant interval. Now if you are running other software on your device that runs MX (or a computer or other device linked directly on your personal network), you can request web tags values on demand via an application programming interface (api hereafter) and don't need to worry about any timing issues. | |||
Obviously each api request creates a processing overhead on Cumulus so use this feature wisely (minimise the information you request and minimise the frequency of requesting it). You can use it for extra current information, but in that usage you might need to repeat the call. Consequently, maybe it is more likely that the api will be used to request information that does not keep changing, such as what units are being used for temperature, rainfall, and wind speed; or perhaps daily, monthly, or yearly, summary figures. | |||
Each admin interface web page uses api techniques for all the information it needs. Some api calls are repeated with AJAX requesting updates for the weather information on a frequent basis, but each page has another api request that is issued just once for the version and build being used. To my mind, the design of '''CumulusMX/interface/todayyest.html''' is crazy. The HTML appears to have a table structure, but that table structure is overwritten by each repeating api. So every time AJAX repeats that api call it returns in json format the whole table definition as well as table cell contents, despite that much of that json (all that HTML defining table header, table rows, table cells, etc.; and the units for each value) does not change and it is only some values and times buried within the json in the api that actually might change (and of those half of them, the yesterday values and times only change once a day). In some code I wrote (but later abandoned) I made use of the api calls that support the '''CumulusMX/interface/todayyest.html''' web page to get the units I wanted on another interface page, but I only called it once as it returned a lot of other information (as just mentioned) that I did not need. I later found a better way, as in example below, which gives me just what I need and no more. | |||
== "GET" approach == | == "GET" approach == | ||
You may have used GET as an attribute when defining the action of a HTML form. Equally you might in a script language access the query-string part of a Universal Resource Locator. Even if you don't understand the meaning of those technical terms, you probably have seen when using a browser a question mark (?) followed by one or [separated by ampersand (&)] more '''name=value''' parameters. | You may have used GET as an attribute when defining the action of a HTML form. Equally you might in a script language access the query-string part of a Universal Resource Locator to get parameters for what the script is to supply to the web page. Even if you don't understand the meaning of those technical terms, you probably have seen when using a browser (in the box where a URL is entered) that sometimes the URL seen there has a query-string. You will have seen a question mark (?) followed by one or [separated by ampersand (&)] more '''name=value''' parameters. | ||
The GET approach to using the api works in this way indicating the start of a query-string with a question mark and using ampersands to separate names. The difference is that a tag name is used instead of a name=value parameter. | The GET approach to using the Cumulus general api works in this way indicating the start of a query-string with a question mark and using ampersands to separate names. The difference is that a tag name (or list of tag names) is used instead of a name=value parameter (or list of name=value parameters). However, when the Cumulus api returns the values they will be in attribute=value format. Therefore if (like example below) you are coding in JavaScript, what is returned is a JavaScript Object and you extract the values by specifying the Object name and the Attribute name. If that technical terminology confuses you, look at the example. | ||
===Selecting values using GET=== | |||
Suppose you want to get the values for the following three web tags: | Suppose you want to get the values for the following three web tags: | ||
| Line 710: | Line 723: | ||
The first parameter is '''rc''' to indicate that the tags that follow are to use decimal points not decimal commas, which is how many script languages expect to see values. | The first parameter is '''rc''' to indicate that the tags that follow are to use decimal points not decimal commas, which is how many script languages expect to see values. | ||
Remember that in | Remember that in current version (and some earlier versions) of MX, the above three web tags are exactly same as: | ||
# <#temp rc=y> | # <#temp rc=y> | ||
# <#hum rc=y> | # <#hum rc=y> | ||
# <#dew rc=y> | # <#dew rc=y> | ||
Since '''rc=y''' can be applied to several web tags that don't appear in [[Webtags#No_Commas]] table, this shows how the api can access values without commas for | Since '''rc=y''' can be applied to several web tags that don't appear in [[Webtags#No_Commas]] table, this shows how the api can access values without commas for all those web tags that report in real numbers and allow that output modifier. | ||
If you are using the api in a context where it does not matter if decimal commas or decimal points are in the api, simply omit the '''rc''' as first item, and just include tag names separated by ampersands. | If you are using the api in a context where it does not matter if decimal commas or decimal points are in the api or for any tags that don't report in real numbers, simply omit the '''rc''' as first item, and just include tag names separated by ampersands. | ||
=== JavaScript example === | === JavaScript example === | ||
| Line 723: | Line 736: | ||
Some people might feel the admin interface could be improved on some of its pages by showing additional information. It is possible from MX 3.7.0 to obtain extra information. | Some people might feel the admin interface could be improved on some of its pages by showing additional information. It is possible from MX 3.7.0 to obtain extra information. | ||
I wanted to improve the log file editing pages, and that was partly by adding validation, and partly by changing the way the editing is done. For the standard log file editor I wanted to achieve even more, I added a script to calculate (and recalculate after any edit) the derived fields from the source fields. To make these calculations work for anyone, I needed to find out what units the Cumulus MX user is using. | I wanted to improve the log file editing pages, and that was partly by adding validation, and partly by changing the way the editing is done. For the standard log file editor I wanted to achieve even more, I added a script to calculate (and recalculate after any edit) the derived fields from the source fields. To make these calculations work for anyone, I needed to find out what units the Cumulus MX user is using. Before 3.7.0 release the snippet of script that obtained the units via various api calls was quite complex (I described above how the api returned lots of unwanted content), but with 3.7.0 my new api call was greatly simplified to what I show below. Please note my revised log file editing scripts did not make it into a public release, and it is only the units obtaining api that I am making available to public here. | ||
Here is the code (with the api call written using jQuery): | Here is the code (with the api call written using jQuery): | ||
| Line 744: | Line 757: | ||
*The jQuery get request takes the api URL as first parameter and the function to deal with the returned result as third parameter | *The jQuery get request takes the api URL as first parameter and the function to deal with the returned result as third parameter | ||
*The middle parameter is irrelevant in this context as only one object instance is returned, but if the qet was returning multiple results, "limit=1" would only return the first result | *The middle parameter is irrelevant in this context as only one object instance is returned, but if the qet was returning multiple results, "limit=1" would only return the first result | ||
*The function takes as its sole parameter an Object, this is what is returned by the api, | *The function takes as its sole parameter an Object (a JavaScript Object is a collection of properties), this is what is returned by the api, an object can be given any variable name | ||
*In JavaScript if a variable is defined outside the function, then given a value inside the function, that value can be accessed by later code outside the function (in my case by code within the other functions for calculating each derived value) | *In JavaScript if a variable is defined outside the function, then given a value inside the function, that value can be accessed by later code outside the function (in my case by code within the other functions for calculating each derived value) | ||
* | *We are only interested in 3 of the '''property_name = property_value''' items in the Object. | ||
* | *The JavaScript '''refinement''' syntax (starts with a dot) can be used to find the value for any parameter we name. We assign the variable already defined to the object and its refinement (that specifies the attribute we want). | ||
*The console.log command simply outputs all the items in the list within the brackets into the browser console that in many browsers is displayed by selecting '''F12''' on the keyboard | *The console.log command simply outputs all the items in the list within the brackets into the browser console that in many browsers is displayed by selecting '''F12''' on the keyboard. I included this instead of the lengthy rest of my code that uses the units to do the various calculations correctly. | ||
== "POST" approach == | == "POST" approach == | ||
The word "Post" in a computer environment means that the Hypertext Transfer Protocol (HTTP) used by the internet is being asked to transfer information enclosed in the body of the request message. Put slightly less technically in this approach you produce a text file with the details of what tags you want and send it to the api server. | The word "Post" in a computer environment means that the Hypertext Transfer Protocol (HTTP) used by the internet is being asked to transfer information enclosed in the body of the request message. Put slightly less technically in this approach you produce a text file with the details of what tags you want and send it to the api server. I suppose it is a bit like sending an email, its header (subject, author, date sent) is easy to view, but you need to open it to see what text is in the body. | ||
You may have used POST as an attribute when defining the action of a HTML form. In that context the form is sent as the contents of a message to whatever web page is going to process the contents of that form. | You may have used POST as an attribute when defining the action of a HTML form. In that context the form is sent as the contents of a message to whatever web page is going to process the contents of that form. | ||
The post approach has a few advantages over get: | The post approach has a few advantages over get: | ||
*The parameters are not shown in | *The parameters are not shown in any query-string, so are not obvious to the person looking over your shoulder, nor do they appear in a history list of sites that the browser has visited. | ||
*If you fill out a form online, the post approach will be used as the content needs to be kept secure. The get approach may be seen when you are navigating through a web site, and a selection is being remembered. | *If you fill out a form online, the post approach will be used as the content needs to be kept secure. | ||
* | **The get approach may be seen when you are navigating through a web site, and a selection is being remembered. | ||
*The POST approach can handle very long requests and return a lot of information. | |||
**In contrast, a URL with query-string is restricted in total length (the restriction is dependent on a number of other factors, but might be at something like 1000 characters in total), so GET comes with a restriction on how many parameters can be specified. | |||
See https://cumulus.hosiene.co.uk/viewtopic.php?p=145050#p145050 for post example | |||
=The Web Tags for Cumulus = | =The Web Tags for Cumulus = | ||
