Php webtags

Cumulus automatically processes a number of template pages into HTML web pages. These template files contain webtags which Cumulus replaces with actual values from your weather station.

If you adopt PHP Hypertext Processing on your web site; there are two main approaches:

1. Either Simply 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.
2. 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.

Cumulus produces webtags that can be incorporated in files that it processes and then the output has the appropriate values where those place-holders were encountered. The standard web templates use some of these webtags and genrate 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, 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.

Options available

• 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;
• 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. 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.
• 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. $LatestError = "Latest Error: 'Some filename was locked" recorded'; as the embedded ones are double quotes, single quotes are used in $LatestError='<#LatestError>'; 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 $longitude=<#longitude dp=5>;
• 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.
• Remember some webtags are specific to particular station types and may not return any useful information for your station.
• Yet another complication (for Cumulus 1 users) is that the values for 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. $LastDataReadTDM='<#LastDataReadT format=h:nn'.' on '.'<#LastDataReadT format="d mmm">';, 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.

The Four Main Approaches

1. One approach is to create an array $WX
   • Within it have elements for all the Cumulus web tags, choosing which parameter combinations to implement;.
   • A file to do this is called CUtags.txt and can be downloaded from Saratoga-Weather.org.
   • 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 <#xxyyzz optional_parameter> by a PHP array element $WX[xxyyzz] [optional_additional_selector] (some elements include the m=10 type selector).
     
     
2. 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 another cumulus support forum thread link.
   • In this case your customised pages would replace any reference to a Cumulus web tag <#xxyyzz optional_parameter> by a PHP variable or array - either $xxyyzz[optional_index] or $xyyxwx.
   • In your customised pages, use the instruction require cumuluswebtags.php.
   • To produce this PHP file, you need a template file that is processed by Cumulus.
   • You may prefer the template that you can download at 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.
     
     
3. There was another project XML webtags but that is now obsolete.
   
   
4. An alternative approach is to use JSON for transferring the variables in a portable way.
   • 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 2 - implementation details

The installation, usage, and example sections below apply to option 2 "cumuluswebtags.php", but are similar for the other options.

Installation

1. 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.
2. 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
   • $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">';
   • $LastTimeStamp='<#LastDataReadT format="h:nn 'on' d mmm">';
   • $metdateM='<#metdate format="mmm">';
   • $metdateMM='<#metdate format="mmmm">';
   • $monthYear='<#metdate format="mmmm yyyy">';
   • $monthStart='<#metdate format="yyyy-mm-01">';
3. you can also delete any rows with web tags that are not relevant to your weather station model for greater efficiency;
4. then save the resulting file in the local directory (that Cumulus can read) where you store your customised templates (rather than use the "cumuluswebtagsT.php" type convention, the suggestion is to retain the name as "cumuluswebtags.txt".
   
5. On the 'Cumulus main screen', in the Configuration menu, select the Internet option;
6. On the 'Internet Settings' screen, select the Files tab;
   
   
7. Edit the screen columns as indicated by red in the figure:
   • in one of the local side boxes (under the 'Local filenames' header), enter the path (directory\file) to where you have stored the template:
     e.g. your_customised_template_location\cumuluswebtags.txt
     (you can use the 'Browse' button to find and select the exact location of the file);
     
     
   • in one of the remote side boxes (under the 'Remote filenames' header), enter the name cumuluswebtags.php:
     • -- if needed add the relative server path (see Cumulus Help for explanation) before the file name;
     • (-- if you are using a local server, and want Cumulus to do a 'copy' instead of using 'FTP' then specify the full path for the destination file here);
     • -- notice that the file extension has been changed from txt (on the left side) to php (on the right side) as the remote file needs to be recognised by the PHP processor on the web server;
   • 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 is normally not appropriate, but if any of your PHP pages are using this file because they require any web tags not in the realtime file, then you might need to select this option);
   • place a check mark in the box under the 'UTF-8' header;
   • place a check mark in the box under the 'FTP?' header;
     • -- this tells Cumulus that the processed file must be uploaded by file transfer to the remote Web server with all the other files;
     • (if you use a local web server, you can leave this un-checked and Cumulus will copy across the processed file to the location specified in the right hand box, but for this you need to specify the full path there);
   • place a check mark in the box under the 'UTF-8?' header:
     • -- this tells Cumulus to output the web page using the standard UTF-8 encoding as used by its standard files;
8. Finally, click on the lower-right OK button to save the newly entered settings.

Usage

Use the PHP include/require command to include the Cumulus webtags into your PHP file.

All PHP variable names are identical to their webtags equivalent. For example, the Cumulus webtag <#forecast> would be referred to as $forecast in your PHP file.

See Sensor_Contact_PHP for an example script that uses this file.

Example

A simple PHP file:

<?php 
 require_once("cumuluswebtags.php");
 echo $time;
 echo "<br/>";
 Echo "The current forecast is " . $forecast;
?>

The results:

20:31 on 02 September 2009
The current forecast is Precipitation, very unsettled

Debugging

If you wish to view all the values contained within the cumulswebtags.php file, append the parameter ?source=view to the end of the URL.

Example

www.myweathersite.com/cumuluswebtags.php?source=view

This will display the source code of the file, listing all the variable names and the values Cumulus has assigned to the webtags during it's processing cycle.