5,838
edits
Php webtags: Difference between revisions
m
no edit summary
m (→Options available: sequence change to make alternative more obvious) |
mNo edit summary |
||
|
*Cumulus
*The standard web templates use some of these webtags and generate HTML pages that can be viewed on a web site.
*If you are customising your web site, then you might choose to use script to produce what you want on your web site,
*#this page describes a way to have cumulus process all the web tags that it defines, in one single file that is uploaded frequently,
*#and make the resulting values available in script variables for you to use anywhere on your site in other files that do not need to be processed first locally and then uploaded to your site.
= Web tag Complications =
If you adopt PHP Hypertext Processing on your web site; there are two main approaches:▼
#Either Simply [[Customised_templates|customise]] those standard template pages by adding some PHP script that will be obeyed after the template has been processed by Cumulus before the resulting HTML is sent to the browser.▼
#Or write a web page including PHP code that does not need to be processed by Cumulus. To get the information that Cumulus provides, all your new pages can "'''include'''" (if you want the page to fail without that cumulus information - use "''require''" instead) another single PHP file that Cumulus does process in which all the [[webtags]] values are assigned to PHP variables. This is more efficient for those using PHP on their website.▼
*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
*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.
▲If you are customising your web site, then you might choose to use script to produce what you want on your web site, and this page describes a way to have cumulus process a single file, and make the resulting values available in script variables for you to use anywhere on your site.
**There are now a vast number of possible combinations and it would be in-efficient for all those combinations to be generated whether needed or not.
**Consequently anyone devising a sample file in any of the formats listed below can only guess which parameters are most useful.
▲*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 PHP could use;
**Because of this 'guessing'; '''do not assume''' that a file from some one else, will meet your requirements
▲*Because of this 'guessing' '''do not assume''' that a file from some one else will meet your requirements '''out of the box'' ''and be prepared to edit it''.
*Note that Cumulus web tags can return either numerical or string information, and 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 notaion <code>$longitude=<#longitude dp=5>;</code>
*Depending on how long you have been running Cumulus, some webtags that might be expected to return numerical information may contain dashes. You may get an error if that particular PHP variable is treated as numerical.
*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.
All the examples above are assigning to PHP variables, but similar arguments apply for XML or JSON approaches so let us briefly review those.
▲'''The Four Main Approaches'''
=== Option 1: Single PHP array ===
#*That download includes elements for the recent history tags at 5, 10, 15, 20, 30, 45, 60, 75, 90, 105 and 120 minutes. If you want older values or values at other times, then you will need to add these to the array yourself. #*Using this array your customised pages would replace any reference to a Cumulus web tag <code><#xxyyzz optional_parameter></code> by a PHP array element <code>$WX[xxyyzz] [optional_additional_selector]</code> (some elements include the m=10 type selector).<br/><br/>▼
*That download includes elements for the recent history tags at 5, 10, 15, 20, 30, 45, 60, 75, 90, 105 and 120 minutes. If you want older values or values at other times, then you will need to add these to the array yourself.
# Another approach is to create a separate PHP variable (or in a few cases an array) for each Cumulus web tag.▼
▲
#*For a discussion about problems with delimiting strings see [http://sandaysoft.com/forum/viewtopic.php?f=4&t=1 another cumulus support forum thread link].▼
#*In this case your customised pages would replace any reference to a Cumulus web tag <code><#xxyyzz optional_parameter></code> by a PHP variable or array - either <code>$xxyyzz[optional_index]</code> or <code>$xyyxwx</code>.▼
#*In your customised pages, use the instruction '''require cumuluswebtags.php'''.▼
=== Option 2: Multiple PHP Variables ===
#*To produce this PHP file, you need a template file that is [[Customised_templates#What_is_meant_by_.27Cumulus_processes_templates.27|processed]] by Cumulus.▼
#*You may prefer the template that you can download at [http://sandaysoft.com/forum/viewtopic.php?f=6&t=10424 cumulus web tags support forum link].▼
▲
#*The download file on this page (download [[File:Cumuluswebtags.txt]]) contains all current [[webtags]] produced by Cumulus v 1.9.4.▼
▲
#*Note that in download above 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 so if you want to use them you need to put in the necessary time selectors yourself.<br/><br/>▼
▲
# There was another project [[xml webtags|XML webtags]] but that is now obsolete.<br/><br/>▼
▲
#*Cumulus MX has one array per weather variable; each element being a sub-array containing a time-stamp and the value at that time. Again you may need to choose the interval between such sub-arrays that suits your use in your web pages.▼
▲
▲
▲
=== Option 3: EXtensible Markup Language alternative ===
Extensible Markup Language (XML) is a mark-up language that defines a set of rules for defining data in a format which is machine-readable but both software and hardware independent.
▲
=== Option 4: JavaScript Object Notation ===
This is a lightweight data-interchange format that is easy for humans to read and write, but critically it is easy for machines to parse and generate for transferring the variables in a portable way.
▲
= Using PHP script =
▲If you adopt PHP Hypertext Processing on your web site; there are two main approaches:
▲#Either
▲#Or write a web page including PHP code that does not need to be processed by Cumulus. To get the information that Cumulus provides, all your new pages can "'''include'''" (if you want the page to fail without that cumulus information - use "''require''" instead) another single PHP file that Cumulus does process in which all the [[webtags]] values are assigned to PHP variables. This is more efficient for those using PHP on their website.
The single file idea of the second choice above might use approach option 1 or option 2, the latter is described further below.
=Option 2 - implementation details=
The installation, usage, and example sections below apply to option 2 "cumuluswebtags.php", but are similar for the other options.
==Installation ==
#For the file you have downloaded at option 2 above, open it in any text editor (preferably one that works in "UTF-8 without BOM") and edit first line. Find the following sequence of 4 characters "'''&''' '''l''' '''t''' ''';'''" and replace all of those with just one "''<''" (so the first line becomes "''<php''") NOTE - the Wiki cannot have a PHP script uploaded to it, so changing the first line stops the Wiki from treating it as PHP script, but after Cumulus has processed it (Cumulus does not care what it processes, but will copy anything it does not recognise across unchanged) we do want the generated file to be treated as a PHP script.▼
##For the file you have downloaded at option 2 above, open it in any text editor (preferably one that works in "UTF-8 without BOM") and edit first line.
#Next add any parameter combinations that you need for your own implementation. For example, for my site I replaced '''thismonthT.htm''' with '''thismonth.php''' and found that my customisation of the template version had used many more Cumulus web tags with parameters than I realised, consequently my cumuluswebtag file has the following extras▼
▲#
▲#Next add any parameter combinations that you need for your own implementation. For example, for my
#*$LastDataReadTDM='<#LastDataReadT format=h:nn'.' on '.'<#LastDataReadT format="d mmm">';
#*$LastDataReadTDMY='<#LastDataReadT format="h:nn am/pm"> on calendar day <#LastDataReadT format="dddd d mmmm yyyy">';
#*$monthStart='<#metdate format="yyyy-mm-01">';
#you can also delete any rows with web tags that are not relevant to your weather station model for greater efficiency;
#then save the resulting file in the local directory (that Cumulus can read) where you store your customised templates (
#On the 'Cumulus main screen', in the '''Configuration''' menu, select the ''Internet'' option;
#On the 'Internet Settings' screen, select the ''Files'' tab;<br><br>
#* place a check mark in the box under the 'Process?' header;
#** -- this tells Cumulus that the file '''cumuluswebtags.txt''' contains tags which need to be replaced by actual values when it processes the template into a web page;
#*(there is no red arrow under the 'Realtime' header as it
#** -- If any of your PHP pages require the latest information at your chosen real-time interval (rather than the 'normal' web site '''updating''' interval) they could be using this file because they require any web tags not in the realtime file, then you might need to select this option (indeed I have on my implementation);
#*place a check mark in the box under the 'UTF-8' header;
#* place a check mark in the box under the 'FTP?' header;
Use the PHP [http://www.w3schools.com/PHP/php_includes.asp include/require] command to include the Cumulus webtags into your PHP file.
See [[Sensor_Contact_PHP]] for an example script that uses this file.▼
==Example==
The current forecast is Precipitation, very unsettled
</pre>
==Debugging==
| |||