5,838
edits
WebsitedataT.json: Difference between revisions
m
Tried to correct all typos
m (Further readability improvements) |
m (Tried to correct all typos) |
||
| Line 2: | Line 2: | ||
[[Category:JSON Files]] | [[Category:JSON Files]] | ||
This [[Cumulus template file]] is found in the [[Web folder|'''web''']] sub-folder of the MX distribution from release 3.10.1 onwards. | This [[Cumulus template file]] is found in the [[Web folder|'''web''']] sub-folder of the MX distribution from release 3.10.1 onwards. '''The content of this page is based on the template file included in release 3.10.1 of MX; hopefully anybody updating this Wiki page, for a later release with an updated file, will also update this paragraph.''' | ||
It supplies the variable information that can be included in a web page by using Cumulus web tags to create a [[Php_webtags#Option_3:_JavaScript_Object_Notation|JavaScript Object Notation (.json) data file]]. | It supplies the variable information that can be included in a web page by using Cumulus web tags to create a [[Php_webtags#Option_3:_JavaScript_Object_Notation|JavaScript Object Notation (.json) data file]]. | ||
| Line 8: | Line 8: | ||
=Explanatory Introduction= | =Explanatory Introduction= | ||
JSON files are written in JavaScript, and that script language supports defining objects. Thus this template file defines a number of objects, each has a variable name that is assigned to a [[Webtags|Cumulus web tag]], when MX [[Customised_templates#What_is_meant_by_.27Cumulus_processes_templates.27|processes]] the template file the values replace the tags and you end up with a data file. In the supplied file, some of these web tags employ [[Webtags/Parameters|input and/or output modification Parameters]]. Let me take one line, and explain | JSON files are written in JavaScript, and that script language supports defining objects. Thus this template file defines a number of JavaScript objects, each has a variable name that is assigned to a [[Webtags|Cumulus web tag]], when MX [[Customised_templates#What_is_meant_by_.27Cumulus_processes_templates.27|processes]] the template file the values replace the tags and you end up with a data file. In the supplied file, some of these web tags employ [[Webtags/Parameters|input and/or output modification Parameters]]. Let me take one line from the file, and explain that line in detail in the hope you can then understand other lines: | ||
"recordsbegandateISO":"<#recordsbegandate format=yyyy-MM-dd>", | "recordsbegandateISO":"<#recordsbegandate format=yyyy-MM-dd>", | ||
# The first string <code>"recordsbegandateISO"</code> defines the name for this variable in the object. | # The first string <code>"recordsbegandateISO"</code> defines the name for this variable in the object. | ||
| Line 25: | Line 25: | ||
Later on this Wiki page in [[#Tailoring the file]], it is explained that you can edit a copy of this template file. I say a copy, as if you edit the original file you risk your edit being lost whenever you upgrade to a new MX release as the release distribution includes a file with this name. In [[#How the file is used]], it is explained how a JavaScript file "setpagedata.js" loads this data file, and transfers values from the data file into HTML pages. | Later on this Wiki page in [[#Tailoring the file]], it is explained that you can edit a copy of this template file. I say a copy, as if you edit the original file you risk your edit being lost whenever you upgrade to a new MX release as the release distribution includes a file with this name. In [[#How the file is used]], it is explained how a JavaScript file "setpagedata.js" loads this data file, and transfers values from the data file into HTML pages. | ||
If you do edit this template file, then remember it is JavaScript, there are rules for using arithmetic in this script language, but we won't go technical and list such rules here, instead we will use an example to explain. Let us suppose you wanted to include the temperature difference between now and 24 hours ago in your HTML page. How you edit HTML is covered elsewhere in this Wiki and in many tutorials available online. To get the value to our web server, we must ask MX | If you do edit this template file, then remember it is JavaScript, there are rules for using arithmetic in this script language, but we won't go technical and list such rules here, instead we will use an example to explain. Let us suppose you wanted to include the temperature difference between now and 24 hours ago in your HTML page. How you edit HTML is covered elsewhere in this Wiki and in many tutorials available online. To get the value to our web server, we must ask MX to calculate it, therefore that value has to be calculated in this template, and you would add a new line like this: | ||
"temperatureChange24hours": | "temperatureChange24hours":(<#temp rc=y> - <#RecentOutsideTemp d=1 rc=y>), | ||
Here, we still define a single variable name before the colon, but after the colon we subtract one web tag value from another remembering that we need to specify that decimal points not decimal commas are needed for JavaScript to understand the values as being numerical in order for the subtraction to work. | Here, we still define a single variable name before the colon, but after the colon we subtract one web tag value from another remembering that we need to specify that decimal points not decimal commas are needed for JavaScript to understand the values as being numerical in order for the subtraction to work. Note that brackets surround the calculation to ensure the expression within those brackets is evaluated, and the lack of quotation marks ensure the expression is treated as numerical rather than a string. | ||
(By the way, if we were doing an adding operation, we have to be very cautious as "+" is normally understood in this script language as indicating concatenation of strings. Please see [[Feels_Like#Script_for_setting_values|here for an example of how addition is used]], essentially '+' can be used for adding by always using a numerical constant before the plus sign and always having any variable after the plus sign). | (By the way, if we were doing an adding operation, we have to be very cautious as "+" is normally understood in this script language as indicating concatenation of strings (see [[#Tailoring the file]] for example of plus sign being used for concatenation). Please see [[Feels_Like#Script_for_setting_values|here for an example of how addition is used]], essentially '+' can be used for adding by always using a numerical constant before the plus sign and always having any variable after the plus sign). | ||
=How the file is used= | =How the file is used= | ||
| Line 35: | Line 35: | ||
This wiki page is about a [[Cumulus template file]]. [[Cumulus.ini#Optional_Web_Server|Settings for Optional_Web_Server]] describes how choosing the default web pages enables the processing of this file into a data file with values, and how that can be uploaded onto your web server. If we decide to tailor this template file, as described later, then we might use [[Cumulus.ini#Extra_Web_Files|Extra web files]] settings within the [[MX Administrative Interface|settings interface]] to process and upload our tailored file(s). | This wiki page is about a [[Cumulus template file]]. [[Cumulus.ini#Optional_Web_Server|Settings for Optional_Web_Server]] describes how choosing the default web pages enables the processing of this file into a data file with values, and how that can be uploaded onto your web server. If we decide to tailor this template file, as described later, then we might use [[Cumulus.ini#Extra_Web_Files|Extra web files]] settings within the [[MX Administrative Interface|settings interface]] to process and upload our tailored file(s). | ||
MX has to be told to convert that to a data file. There is a full explanation of what is meant by 'Cumulus processing any template' [[Customised_templates#What_is_meant_by_.27Cumulus_processes_templates.27|here]]. In this case, MX will generate a file that is stored as "CumulusMX/web/websitedata.json". This data file is still coded as JavaScript file, but now the tags have gone as they have been replaced by values. | MX has to be told to convert that to a data file. There is a full explanation of what is meant by 'Cumulus processing any template' [[Customised_templates#What_is_meant_by_.27Cumulus_processes_templates.27|here]]. In this case, MX will, while processing the template, generate a data file that is stored as "CumulusMX/web/websitedata.json". This data file is still coded as JavaScript file, but now the tags have gone as they have been replaced by values. | ||
The data file is used with the [[New Default Web Site Information|Web Pages]] supplied in the [[Webfiles folder|'''webfiles''']] sub-folder of the MX distribution from release 3.10.1 onwards. On your web server, each HTML page will call another JavaScript file "/CumulusMX/webfiles/js/setpagedata.js" (after uploading this file once to web site), it is that script that will both read the uploaded data file, and insert the relevant value into HTML pages in a span which has the "cmxdata" attribute, with a value for that attribute set to the appropriate variable name for the relevant JSON object. | The data file is used with the [[New Default Web Site Information|Web Pages]] supplied in the [[Webfiles folder|'''webfiles''']] sub-folder of the MX distribution from release 3.10.1 onwards. On your web server, each HTML page will call another JavaScript file "/CumulusMX/webfiles/js/setpagedata.js" (after uploading this file once to web site), it is that script that will both read the uploaded data file, and insert the relevant value into HTML pages in a span which has the "cmxdata" attribute, with a value for that attribute set to the appropriate variable name for the relevant JSON object. | ||
| Line 69: | Line 69: | ||
*# You might chose to upload some information in a third file that is uploaded at the defined standard interval | *# You might chose to upload some information in a third file that is uploaded at the defined standard interval | ||
You will need to modify your JavaScript file "/CumulusMX/webfiles/js/setpagedata.js" (and don't forget to upload this file after editing once to web site), because it includes the loading of the data file: <code>$.getJSON('websitedata.json?_=' + Date.now(),</code>, the query-string (bit prefixed by question mark) just ensures a fresh copy is loaded each time, preventing your browser thinking because you have loaded the file before it can reuse the copy it cached. In the tailored copy of this script, it will need to load each of the tailored data files. | You will need to modify your JavaScript file "/CumulusMX/webfiles/js/setpagedata.js" (and don't forget to upload this file after editing once to web site), because it includes the loading of the data file: <code>$.getJSON('websitedata.json?_=' + Date.now(),</code>, here the plus sign is used to indicate concatenation within the query-string (bit prefixed by question mark), adding the current time to make the request unique just ensures a fresh copy is loaded each time, preventing your browser thinking because you have loaded the file before it can reuse the copy it cached. In the tailored copy of this script, it will need to load each of the tailored data files. | ||
==Options== | ==Options== | ||
| Line 251: | Line 251: | ||
|(Fairly static information as only changes at start of rollover) The date of the meteorological day that has most recently finished. Using the date formatting element of '''ISO 8601 Data elements and interchange formats''' | |(Fairly static information as only changes at start of rollover) The date of the meteorological day that has most recently finished. Using the date formatting element of '''ISO 8601 Data elements and interchange formats''' | ||
Note: The JSON name chosen indicates this is in ISO 8601 format, not your locale format. | Note: The JSON object variable name is different to the tag name, the variable name chosen indicates this is in ISO 8601 format, not your locale format. | ||
|- | |- | ||
|<#date> | |<#date> | ||
| Line 268: | Line 268: | ||
|(Only changes when calendar month changes) The current '''calendar month''' using words defined for your locale. Example format: July | |(Only changes when calendar month changes) The current '''calendar month''' using words defined for your locale. Example format: July | ||
Note: If you use 9 am or 10 am rollover, on the first day of a month this will (before rollover) display wrong meteorological month | Note: If you use 9 am or 10 am rollover, on the first day of a month this variable will (before rollover) display wrong meteorological month | ||
|- | |- | ||
|<#temp> | |<#temp> | ||
| Line 370: | Line 370: | ||
|"rmonth" | |"rmonth" | ||
| <nowiki><span data-cmxdata="rmonth"></nowiki> | | <nowiki><span data-cmxdata="rmonth"></nowiki> | ||
|The total rainfall (derived from | |The total rainfall (derived from summing daily rainfall amounts) for the month so far | ||
|- | |- | ||
|<#ryear> | |<#ryear> | ||
|"ryear" | |"ryear" | ||
| <nowiki><span data-cmxdata="ryear"></nowiki> | | <nowiki><span data-cmxdata="ryear"></nowiki> | ||
|The total rainfall (derived from | |The total rainfall, (derived from summing daily rainfall amount, plus any adjustment defined in Settings for this calendar year) for the rain season (starting month defined in Settings, so does not have to align with calendar year) | ||
|- | |- | ||
|<#rhour> | |<#rhour> | ||
|"rhour" | |"rhour" | ||
| <nowiki><span data-cmxdata="rhour"></nowiki> | | <nowiki><span data-cmxdata="rhour"></nowiki> | ||
|The total rainfall in last hour (derived from count now minus count one hour ago). Equivalent to <#rfall> - <#RecentRainToday h=1> (unless rollover happened within last hour) | |The total rainfall in last hour (derived from count now, minus count one hour ago). Equivalent to (<#rfall> - <#RecentRainToday h=1>) (unless rollover happened within last hour) | ||
|- | |- | ||
|<#LastRainTip format="d MMM"> | |<#LastRainTip format="d MMM"> | ||
| Line 502: | Line 502: | ||
|Highest USA Heat Index, derived by MX for this meteorological day, and time, taken from '''today.ini''' | |Highest USA Heat Index, derived by MX for this meteorological day, and time, taken from '''today.ini''' | ||
Note: | Note: You could tailor the template to use Canadian Humidity Index (Humidex) instead by replacing <#heatindexTH> and <#TheatindexTH> with <#humidexTH> and <#ThumidexTH> | ||
|- | |- | ||
|<#humTH> and <#ThumTH> | |<#humTH> and <#ThumTH> | ||