5,838
edits
WebsitedataT.json: Difference between revisions
m
Further readability improvements
m (Further readability improvements) |
|||
| Line 4: | Line 4: | ||
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. | ||
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 it in detail: | =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 it in detail: | |||
"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 "}" | ||
==Example of using arithmetic with two Cumulus web tags in value== | |||
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 tocalculate it, therefore that value has to be calculated in this template, and you would add a new line like this: | |||
"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. | |||
(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). | |||
=How the file is used= | =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 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. | |||
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. | |||
For example <code><span data-cmxdata="recordsbegandateISO"></span></code> would be processed in the "setpagedata.js" script and result in an insert of the date in the JSON line that we examined in detail at the start of this Wiki page. | |||
Similarly, <code><span data-cmxdata="temperatureChange24hours"></span></code> would make that script insert the temperature difference we defined earlier, to show how arithmetic can be used in what can be added as a modification to the JSON template. | |||
In the tables below, that explain the data represented by various lines in the template file, there are multiple columns: | In the tables below, that explain the data represented by various lines in the template file, there are multiple columns: | ||