5,838
edits
WebsitedataT.json: Difference between revisions
m
Improved the initial explanation about this file, in response to feedback
m (Improved the initial explanation about this file, in response to feedback) |
|||
|
This [[Cumulus template file]] is found in the [[Web folder|'''web''']] sub-folder of the MX distribution from release 3.10.1 onwards.
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]].
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 it in detail:
"recordsbegandateISO":"<#recordsbegandate format=yyyy-MM-dd>",
# The first string <code>"recordsbegandateISO"</code> defines the object name.
# The colon separates that object name from the value, think of it like an equals sign in ordinary arithmetic.
# 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>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 > 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 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 "}"
Later on this Wiki page, it is explained that you can edit this template file, but if you keep the current name you risk your edit being lost when you upgrade to a new release as the release distribution includes a file with this name. If you do edit this file, then remember it is JavaScript, so you could define a parameter using arithmetic e.g. Suppose you wanted to include the temperature difference between now and 24 hours ago, add a new line like this:
"temperatureChange24hours":"<#RCtemp> - <#RCRecentOutsideTemp d=1>",
=How the file is used=
Like any other [[Cumulus template file]], MX has to be told to [[Customised_templates#What_is_meant_by_.27Cumulus_processes_templates.27|process]] the template in order to generate "CumulusMX/web/websitedata.json" which is a JavaScript file where the tags have been replaced by values. [[Cumulus.ini#Optional_Web_Server|Settings for Optional_Web_Server]] describes how choosing the default web pages enables the processing and uploading of this file with values onto your web server.
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 the JavaScript file "/CumulusMX/webfiles/js/setpagedata.js" (after uploading this file once to web site), it is that script that will 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 JSON object name. For example <code><span data-cmxdata="recordsbegandateISO"></span></code> would instruct the "setpagedata.js" script to insert the object we examined in detail earlier and <code><span data-cmxdata="temperatureChange24hours"></span></code> would make it insert the temperature difference we added as a modification earlier.
In the tables below, the [[webtags|tag name]] together with any [[Webtags/Parameters|input/output modification parameter]], and the span attribute value of a JSON object is also shown because they do not always match. Please note that in the tables below, for simplicity, not every element is shown, often just an example, this is enough to show you the format, again the JSON attribute and the ID do not always match.
The default web pages, even if you customise them, can only display JSON variables that are defined in this file (as per tables below) and formats for content are fixed.
==Tailoring the file==
If you want to use this file as the basis of your own JSON based file uploads (either because you want to change the fixed formats in provided file, or because you are not using the default web site):
* Should you wish to tailor it, the best practice is to take a copy into a new folder, edit that copy, possibly into 3 separate files, and use the '''Extra Web Files''' settings to get
*# First file, upload using the '''EOD''' selection
*#*
*#* Equally
*# Most of the rest of the information can change during a day, and is best uploaded in a second file at your real-time interval (if that is enabled)
*# 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.
==Options==
There are 3 fixed pieces of information conveyed by this file refering to Cumulus web tags for defining options:
# "useApparent" = whether Apparent Temperature or Feels Like temperature is required
# "showSolar" = whether a solar sensor is providing solar information or not
# "showUV" = whether a UV sensor is providing Ultra Violet information or not
The content values for these JSON object names as included in this file depend upon [[Cumulus.ini#Display_Options|selections]] at '''Station Settings → Display Options'''.
==List of variables==
|"recordsbegandate" and "recordsbegandateISO"
| e.g. <nowiki><span data-cmxdata="recordsbegandate"></nowiki>
|Date when usage of MX began. The default format for first JSON parameter depends on the locale you use to run Cumulus, the second JSON parameter always returns a four digit year, then a hyphen, then a 2 digit month number, then a hyphen, then a 2 digit day of month number; this is using the date formatting element of '''ISO 8601 Data elements and interchange formats''' and was explained as an example in detail at the start of this Wiki page
|-
|<#forum>
| |||