Php webtags

• Cumulus defines webtags that can be incorporated in files that it processes and then where those place-holders are encountered Cumulus inserts actual values from your weather station in the output file.
• 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,
  1. this page describes a way to have cumulus process all the web tags that it defines, in one single file that is uploaded frequently,
  2. 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

• Some web tags contain content that never changes, I will leave you to work out which these are; equally some web tags identify the month or year and only change when a new month or new year starts. It does not make for efficient use of resources if you make both PHP and Cumulus process every web tag each time Cumulus does a real time update. So although this article talks about a single script assigning Cumulus web tags to PHP variables, it actually makes better sense to have multiple scripts, each processed only when the tags they contain may change. How to arange this is beyond the scope of this article, you need to have a very good understanding of PHP and Cumulus and you might seek help via the support forum.
• 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.
  • 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.
  • 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, you must understand the script language and be prepared to edit the file supplied into one that meets your own requirements.
• 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 comparisions, 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).
  • Also 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 notation $longitude=<#longitude dp=5>;
  • Some webtags 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 $monthHighDailyTempRange='<#MonthHighDailyTempRange>'; will return dashes as that particular item is not calculated by Cumulus until at least one complete day is available.
• Remember some webtags are specific to particular station types and may not return any useful information for your station. For example $light=<#Light>; is a value that only applies to those Fine Offset stations that have a solar sensor and not to any other make or type.
• 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 so let us briefly review those.

The Four Main Approaches to data transfer

Option 1: Single PHP array

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).

Option 2: Multiple PHP Variables

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.

IMPORTANT This file is only for use with Cumulus v1.9.4, it will not work with Cumulus MX.

• 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.

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 very focussed on being machine-readable but both software and hardware independent.

You can see more about this approach on the XML webtags page, but that approach is now considered an obsolete one by some who find languages like PHP easier for humans to read, while XML is considered as the best approach for the future by others (for example the WMO and ICAO have recently specified a XML and geographical based approach for reporting weather conditions at airports and are persauding those running airports to swap from METAR in traditional alphanumeric characters as introduced when the shortness of the code was easiest for transmission by telex).

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.

• 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.

Using PHP script

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

1. Either simply customise the 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.

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

1. 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.
   2. 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 implementation, 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 expected, consequently my cumuluswebtag template 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 (you could use the "cumuluswebtagsT.php" type convention as I do because of all my customisations, but to keep it simple the suggestion here is to retain the name as "cumuluswebtags.txt" if you are basically using the provided code).
   
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 may not be appropriate),
     • -- 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;
     • -- 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.

In the download on this page the PHP variable names are identical to their webtags equivalent, but of course if you are editing the file you might choose different names. For example in provided code, the Cumulus webtag <#forecast> would be referred to as $forecast in your PHP 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

See Sensor_Contact_PHP for another example script that uses this file.

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.