5,838
edits
Php webtags: Difference between revisions
m
no edit summary
mNo edit summary |
|||
| Line 1: | Line 1: | ||
*Cumulus defines [[webtags]] that can be incorporated in files that it processes | = Introduction = | ||
*The standard web templates use some of these | |||
*If you are customising your web site, then you might choose to use script to produce | *Cumulus defines [[webtags|marker tokens called web tags]] that can be incorporated in template files that it processes. Where those place-holders are encountered Cumulus inserts actual values derived from processing information supplied from your weather station into an output file that might be a web page or a PHP script. | ||
*#this page describes a way to have cumulus process all the web tags that it defines, in one | *The standard web templates provided with each flavour of Cumulus each use some of these web tags and after processing them Cumulus will generate HTML pages that can be uploaded to a web site. | ||
*#and make the resulting values available in script variables for you to use anywhere on your site in other files | *If you are customising your web site, then you might choose to use script to produce the HTML you want on your web site, instead of asking Cumulus to process templates, but you still need a way to get the values to those scripts: | ||
*#this page describes a way to have cumulus process all the web tags that it defines, in one or more template files that are uploaded at the appropriate time interval for the updating of the web tags contained, | |||
*#and make the resulting values available in script variables for you to use anywhere on your web site in other files | |||
*# these other files can be resident on your web server, they never need to be updated locally (and uploaded) as they do not need to be processed first locally. | |||
This article will first address some of the complications that make providing such a script more difficult than you might expect. This implies that you cannot have a ready made template script that will suit everyone, but also means if you are producing your own set of scripts there is quite a lot to think about. Next this article has links to a number of ready made fairly simple templates explaining which versions of Cumulus they will work with. After that this article helps you to produce your own set of templates, and finally it describes some alternative approaches. | |||
== Web tag Complications == | |||
=== Version specific tags === | |||
This should be obvious, but people choosing ready made scripts often get caught out by this, expecting their script to give them web tags added in latest release. Each script provided by someone will make its selection of what PHP variables to set based on those tags and parameters available when the script was generated. Individual web tags are added as releases progress, so very few were available in early versions of Cumulus 1, compared to latest versions. When Cumulus MX was first released it did not include all web tags available in the final release of Cumulus 1, now in its releases MX has many more web tags than Cumulus 1. Also the input or output parameters available may change at a particular version. | |||
=== static or rarely changing content=== | |||
*Some web tags contain content that either never or almost never changes, an example is those that are specific to your location. | |||
*Equally some web tags identify the month or year and only change when a new month or new year starts. | |||
*All the yesterday tags only change their content during the rollover process, their content is static throughout each day | |||
*Many tags that represent extreme records might change any time during the day, but those that represent extremes in a particular month can only be updated if it currently is that month. | |||
It does not make for efficient use of resources if you make Cumulus process every web tag each time Cumulus does a real time update (which on some sites is every second) and then every upload has to contain a long file defining all those PHP variables that have not changed as well as the few that have chnaged. So although this article has links to many single ready made scripts assigning every single Cumulus web tag to a PHP variable, it actually makes better sense to have multiple scripts, each processed only when the content might change for the tags in that script. | |||
=== station specific tags === | |||
*Remember some web tags are specific to particular station types and may not return any useful information for your station. For example <code>$light=<#Light>;</code> is a value that only applies to those Fine Offset stations that have a solar sensor and not to any other make or type (although note that stations manufactured by Fine Offset are sold by a number of different companies who brand those stations with their own name, and in the USA the Fine Offset brand name itself is never used). Equally Evapotranspiration and storm rain is specific to Davis models. | |||
Some ready made scripts will omit station specific tags, some will include them. Check if any script you choose to use includes the tags you want, and edit out any you can't use. | |||
=== parameters === | |||
*In early versions of Cumulus, its web tags did not take parameters and it was easy to assign each web tag to a variable that any data transfer approach could use; | *In early versions of Cumulus, its web tags did not take parameters and it was easy to assign each web tag to a variable that any data transfer approach could use; | ||
*From version 1.9.3 various web tags (such as "Recent History") always take parameters, others (like those reporting times and/or dates) can take parameters. | *From version 1.9.3 various web tags (such as "Recent History") always take input parameters, others (like those reporting times and/or dates) can take output parameters. | ||
**There are now a vast number of possible combinations and it would be in-efficient for large numbers of those combinations to be generated whether needed or not. | **There are now a vast number of possible combinations for such parameters in many web tags, and it would be in-efficient for large numbers of those combinations to be generated whether needed or not. | ||
**Consequently anyone devising a | **Consequently anyone devising a single template file has to guess which parameters are most useful, and in most of the ready made templates no parameters are included so a vast amount of the information accessible for a web page generated directly from a template file is not available for web pages generated from scripts on your web server. | ||
**Because of this 'guessing'; '''do not assume''' that a file from some one else, will meet your requirements ''out of the box'', you must understand the script language and be prepared to edit the file supplied into one that meets your own requirements. | **Because of this 'guessing'; '''do not assume''' that a file from some one else, will meet your requirements ''out of the box'', you must understand the script language and be prepared to edit the file supplied into one that meets your own requirements. | ||
== variable content == | ** A further complication is that output parameters are not the same for different flavours of Cumulus. So if a ready made template is selected that does contain some of the possible output parameters that are available, it will only work for Cumulus 1 or only work for Cumulus MX. | ||
So if you want to use a ready made script, check whether it does include any parameters, whether those parameters are correct for the flavour of Cumulus you are using and whether the parameters selected are those most useful to you. | |||
=== variable content === | |||
*When editing the file remember that Cumulus web tags can return either numerical or string information, when using the script variables you may wish to do numeric calculations or comparisons, and these might behave differently if numeric information is processed as a string (for example the month of March as a number returns '3', but as a string may return '03', some comparisons don't recognise those are same). | *When editing the file remember that Cumulus web tags can return either numerical or string information, when using the script variables you may wish to do numeric calculations or comparisons, and these might behave differently if numeric information is processed as a string (for example the month of March as a number returns '3', but as a string may return '03', some comparisons don't recognise those are same). | ||
**Some web tags that might be expected to return numerical information may contain dashes instead sometimes. You may get an error if that particular PHP variable is treated as numerical. As an example on the first day of a month <code>$monthHighDailyTempRange='<#MonthHighDailyTempRange>';</code> will return dashes as that particular item is not calculated by Cumulus until at least one complete day is available. | **Some web tags that might be expected to return numerical information may contain dashes instead sometimes. You may get an error if that particular PHP variable is treated as numerical. As an example on the first day of a month <code>$monthHighDailyTempRange='<#MonthHighDailyTempRange>';</code> will return dashes as that particular item is not calculated by Cumulus until at least one complete day is available. | ||
==embedded | |||
=== embedded content === | |||
**Also when returning string information Cumulus can include embedded quotes: e.g. <code>$LatestError = "Latest Error: 'Some filename was locked" recorded';</code> as the embedded ones are double quotes, single quotes are used in <code>$LatestError='<#LatestError>';</code> in the template file as delimiters for the whole string. Equally Longitude and Latitude web tags by default label the minutes and seconds part with the same symbols as used by quotes, so we have to choose the alternative decimal notation <code>$longitude=<#longitude dp=5>;</code> | **Also when returning string information Cumulus can include embedded quotes: e.g. <code>$LatestError = "Latest Error: 'Some filename was locked" recorded';</code> as the embedded ones are double quotes, single quotes are used in <code>$LatestError='<#LatestError>';</code> in the template file as delimiters for the whole string. Equally Longitude and Latitude web tags by default label the minutes and seconds part with the same symbols as used by quotes, so we have to choose the alternative decimal notation <code>$longitude=<#longitude dp=5>;</code> | ||
*Yet another complication (for Cumulus 1 users) is that the values for [[Webtags#Time.2FDate_.27format.27_Parameter|formatting parameters]] can include double and single quotes, but any assignment to a PHP variable requires the value to be quoted so it is treated as a string. There are two ways round this, one is to concatenate several uses of the same Cumulus web tag to build up the required layout without using both versions of quotation marks within any single formatting value e.g. <code>$LastDataReadTDM='<#LastDataReadT format=h:nn'.' on '.'<#LastDataReadT format="d mmm">';</code>, and the other is to use the PHP 'heredoc' approach - see PHP manual. | *Yet another complication (for Cumulus 1 users) is that the values for [[Webtags#Time.2FDate_.27format.27_Parameter|formatting parameters]] can include double and single quotes, but any assignment to a PHP variable requires the value to be quoted so it is treated as a string. There are two ways round this, one is to concatenate several uses of the same Cumulus web tag to build up the required layout without using both versions of quotation marks within any single formatting value e.g. <code>$LastDataReadTDM='<#LastDataReadT format=h:nn'.' on '.'<#LastDataReadT format="d mmm">';</code>, and the other is to use the PHP 'heredoc' approach - see PHP manual. | ||
*Cumulus MX web tags do allow embedding of HTML, see the [[Webtags|Web tags article]] for details. | *Cumulus MX web tags do allow embedding of HTML, see the [[Webtags|Web tags article]] for details. | ||
== Ready made PHP Web Tag templates == | |||
'''Instead of producing your own template''' as described below, there are a number already produced (if they contain output parameters they are specific to a particular flavour of Cumulus), of course ''none of them cover all web tag combinations'' possible using output parameters, but they might cover enough for your purposes: | |||
*For version 3.5.3 (build 3074), a single template file can be downloaded from [https://cumulus.hosiene.co.uk/viewtopic.php?f=14&t=17991 CumulusMX PHPwebtags] topic in the support forum, posted by the administrator (water01). | |||
* An equivalent for MX version 3.0.x is at [https://cumulus.hosiene.co.uk/viewtopic.php?f=39&t=13252&p=103860&hilit=cumuluswebtags.txt#p103830 this page on support forum] posted by the administrator (water01), but that was last edited in 2015 and does not contain any web tags added since then. | |||
*For the final version 1.9.4 of Cumulus 1 use the download file on '''this page''' (download [[File:Cumuluswebtags.txt]]). Note that in this download the recent history tags only occur with a single 3 hours ago parameter but if you use these tags it is likely you will want to include them for several other periods too. Edit this template file to put in the necessary time selectors yourself. | |||
*An alternative simpler template, that should work for Cumulus 1 or MX as it does not contain any output parameters, can be downloaded at [https://cumulus.hosiene.co.uk/viewtopic.php?f=6&t=10424&sid=123ca9bf91d769094eed72096c7920ea&start=15#p99549 by Brandon in this support forum link]. | |||
* Another simple template produced by BCJKiwi that works with both Cumulus 1 and MX is at [https://cumulus.hosiene.co.uk/viewtopic.php?f=40&t=17985&p=140688#p140688 this post of mine in a zip], this one does not contain any web tags that are only available in MX, nor does it contain any that require output parameters. | |||
The main focus of this article is assigning to PHP variables, but similar arguments apply for XML or JSON approaches so let us briefly review those. | The main focus of this article is assigning to PHP variables, but similar arguments apply for XML or JSON approaches so let us briefly review those. | ||
| Line 63: | Line 104: | ||
'''For more information''' on how to write a template file or how to ask Cumulus to process files see [[Customised_templates#What_is_meant_by_.27Cumulus_processes_templates.27|processed by Cumulus]] topic. | '''For more information''' on how to write a template file or how to ask Cumulus to process files see [[Customised_templates#What_is_meant_by_.27Cumulus_processes_templates.27|processed by Cumulus]] topic. | ||
=== Option 3: EXtensible Markup Language alternative === | === Option 3: EXtensible Markup Language alternative === | ||