5,838
edits
WebsitedataT.json: Difference between revisions
From Cumulus Wiki
Jump to navigationJump to search
m
no edit summary
m (Improved the initial explanation about this file, in response to feedback) |
mNo edit summary |
||
| (5 intermediate revisions by the same user not shown) | |||
| 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) 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]]. | ||
JSON files are written in JavaScript, and that script language supports defining objects. Thus this template file defines a number of objects, each is assigned to a [[Webtags|Cumulus web tag]]. 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 | =Explanatory Introduction= | ||
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 object | # The first string <code>"recordsbegandateISO"</code> defines the name for this variable in the object. | ||
# The colon separates that object name from the value, think of it like an equals sign in ordinary arithmetic. | # The colon separates that object variable name from the value, think of it like an equals sign in ordinary arithmetic. | ||
# The <code> | # The <code><#</code> prefix defines the start of a Cumulus web tag. | ||
# The <code>recordsbegandate</code> is the tag name, the definition of this particular one can be found near the end of the table in [[Webtags#Date_.26_Time|'Date & Time' section on webtags page]]. | # The <code>recordsbegandate</code> is the Cumulus tag name, the definition of this particular one can be found near the end of the table in [[Webtags#Date_.26_Time|'Date & Time' section on webtags page]]. | ||
# The <code>format=</code> is an output format modifier attribute defined in [[Webtags/Parameters#Multiple_Output_Format_Modifier_parameters_for_times_and_dates|Multiple_Output_Format_Modifier_parameters_for_times_and_dates section on the parameters sub-page]]. | # The <code>format=</code> is an output format modifier attribute defined in [[Webtags/Parameters#Multiple_Output_Format_Modifier_parameters_for_times_and_dates|'Multiple_Output_Format_Modifier_parameters_for_times_and_dates' section on the parameters sub-page]]. | ||
# The <code>yyyy-MM-dd</code> defines the output format required, as explained in the last cross-reference, this represents a four digit year, then a hyphen,then a two digit month code, then another hyphen, and finally a two digit day of month. | # The <code>yyyy-MM-dd</code> defines the output format required, as explained in the tables on the Wiki page in the last cross-reference, this represents a four digit year, then a hyphen, then a two digit month code, then another hyphen, and finally a two digit day of month. | ||
# The > symbol ends the Cumulus web tag definition. | # The > symbol ends the Cumulus web tag definition. | ||
# The double quotation marks round the Cumulus web tag ensure the output is treated as a string | # The double quotation marks round the Cumulus web tag ensure the output is treated as a string | ||
# The comma at the end of the line I have used as an example is there because another parameter is defined on the next line. | # The comma at the end of the line I have used as an example is there because another parameter is defined on the next line. | ||
# The whole object definition is enclosed in brackets "{" to "}" | # The whole object definition, of all the variables in the file, (not seen in single line extract above) is enclosed in brackets "{" to "}" | ||
=How the file is used= | |||
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, 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. Note that "js/setpagedata.js" uses a querystring for adding the current time to make the request unique, that 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 HTML, <code><span data-cmxdata="recordsbegandateISO"></span></code> would be found and then processed in the "setpagedata.js" script. The HTML as displayed by the browser will then have a date within that span element. As explained at the start of this Wiki page, that date originated from MX processing a web tag in the template file. | |||
In the tables below, that explain the data represented by various lines in the template file, there are multiple columns: | |||
* Cumulus tag name (including whether any input/output modification parameters) | |||
* JSON object variable name | |||
* The span sequence used in HTML file to relate to this variable | |||
* A description | |||
The tables show the tag name and the JSON variable name because these might not agree. The tables show the span sequence because you might be looking at the HTML file and use what you see there as a starting point for working back to either the description or the Cumulus tag name (or the [[Webtags/Parameters|input/output modification parameter]]). | |||
''Please note for simplicity, not every line in the file is explained, sometimes just one example is given representing multiple lines, this is enough to show you the format (with or without parameters), and whether the tag name and JSON object variable name do match.'' | |||
=File details= | =File details= | ||
{{TOCright}} | {{TOCright}} | ||
This file is designed to work with the MX default web pages (that you upload just once from the '''webfiles''' sub-folder of your MX installation) | * This file is designed to work with the MX default web pages (that you upload just once from the '''webfiles''' sub-folder of your MX installation). | ||
* This template file lists all the JSON variables that those pages require to be uploaded to your web server so the default HTML pages can be used as a background structure to permit displaying your weather data. As explained above, a JavaScript file on your web site loads the file with JSON data and inserts the data in appropriate places on the web page. | |||
* The file has to cater for the majority of people using the default web site, and assumes use of a Davis weather station, therefore its content might not be optimised for your use. | |||
* The default web pages, can only display JSON variables that are defined in this file (as per tables below) and formats for content are fixed. | |||
Note that the variables included in this file represent the degree symbol <sup>o</sup> in two different ways: | |||
# As an HTML encoded entity <nowiki>&deg;</nowiki> that always translates to ° if you are using in HTML web page | # As an HTML encoded entity <nowiki>&deg;</nowiki> that always translates to ° if you are using in HTML web page | ||
# As a binary character (equates to decimal 176), that only translates to ° if you are using UTF-8 encoding '''(select this on ''Internet Settings'' → ''Web/FTP Settings'' → ''General Settings'' → tick ''UTF-8 encoding'')''' to create this file with that encoding (to match the [[Reports_folder#Encoding|encoding]] used by the [[New_Default_Web_Site_Information#Installing_the_new_template_for_new_users|web pages]] included in ''webfiles'' folder) | # As a binary character (equates to decimal 176), that only translates to ° if you are using UTF-8 encoding '''(select this on ''Internet Settings'' → ''Web/FTP Settings'' → ''General Settings'' → tick ''UTF-8 encoding'')''' to create this file with that encoding (to match the [[Reports_folder#Encoding|encoding]] used by the [[New_Default_Web_Site_Information#Installing_the_new_template_for_new_users|web pages]] included in ''webfiles'' folder) | ||
==Tailoring the file== | ==Tailoring the file== | ||
If you | If you have experience with how JSON files are coded, you can choose to use a different file to that provided with MX. | ||
To avoid loss of you file when you are upgrading to a new MX release, best practice would be to create a template file with a different name, and/or in a different folder, and use the '''Extra Web Files''' settings to get your tailored template [[Customised_templates#What_is_meant_by_.27Cumulus_processes_templates.27|processed]] and uploaded at your preferred interval to become "webbsitedata.json" on your web server and disable the settings that get the default file processed and uploaded. | |||
If the remote file setting on the extra web files uses the same "webbsitedata.json" name, then "js/setpagedata.js" will load it (<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)) and process whatever object names it finds, so all you need to do is edit the HTML file to use span definitions that match the object names. | |||
If you have even more experience, you can also edit "js/setpagedata.js", perhaps so it can process multiple JSON files, so you can upload data that is static (see tables) or only changes when day changes at EOD in extra web files settings, and reduce the size of upload at your real-time interval. Of course you might even consider adding extra JavaScript that takes two json objects and outputs the difference between them, or you might make use of [[PHP]] that can also do a simple calculation or a much more complex one. | |||
==Options== | ==Options== | ||
There are 3 fixed pieces of information conveyed by this file | There are 3 fixed pieces of information conveyed by this file (referring to Cumulus web tags for defining options): | ||
# "useApparent" = whether Apparent Temperature or Feels Like temperature is required | # "useApparent" = whether Apparent Temperature or Feels Like temperature is required | ||
# "showSolar" = whether a solar sensor is providing solar information or not | # "showSolar" = whether a solar sensor is providing solar information or not | ||
| Line 233: | Line 244: | ||
|(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 250: | Line 261: | ||
|(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 352: | Line 363: | ||
|"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 484: | Line 495: | ||
|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> | ||
