Php webtags

Introduction

What are web tags for?

1. Cumulus defines marker tokens called web tags, each of these represents an item it can report.
2. You write a template file and Cumulus will process it creating HTML, JSON, JavaScript, PHP or whatever type of Output file you want.
3. You also define what encoding format Cumulus is to use for this output file, most modern files will use "utf-8", but Cumulus also allows ISO-8859-1 encoding.
4. As Cumulus is processing these templates, it parses the text, copying most text straight to that output file, but whenever those place-holders are encountered Cumulus inserts actual values instead of the web tag into that output file.
   • Those inserted values are derived from processing information supplied from your weather station

Standard web pages

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

Customised web pages

• If you are customising your web site, then you don't need to follow the way that the Cumulus supplied standard web pages work.
• Just as a reminder standard ones are written as template files that Cumulus has to process and upload each time new data is to be displayed.

• You can write your own web pages that stay on your web server, and do not have to be uploaded again for each update.
• However, those web pages still need to get data from Cumulus somehow.
  1. 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,
  2. and make the resulting values available in script variables for you to use anywhere on your web site in other files.
  3. When someone wants to view your customised web pages, the web server simply copies into the web page the latest script variables and generates HTML that has up to date values.
  4. You can even use Ajax (a JavaScript that runs in Client's browser) to update that HTML with new values at regular intervals (when a new script variable files has been uploaded).

Using PHP script

If you adopt PHP Hypertext Processing (other alternatives described below) 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 parsed (interpreted) after the template processed by Cumulus has been uploaded to your web server, but 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 derived value information that Cumulus provides, all your new pages can "include_once" (if you want the page to fail without that cumulus derived information - use "require_once" instead) one, or more, PHP script file(s) that Cumulus has previously processed. In that processing all the webtags values were assigned to PHP variables. This second approach is more efficient for those using PHP on their website as the actual web pages are produced from PHP scripts on the web server and do not need to be uploaded each time the numbers they output change. After all having to upload multiple full HTML structure definitions for all web pages is a far larger uploading burden than uploading just the files containing the variables at their appropriate frequency.

This article will first address some of the complications that make providing such a variable assigning script more difficult than you might expect. The multiple complications imply that nobody can write a ready made single template script that will suit everyone. It also means if you are considering producing your own set of scripts to suit what you might do on your web site, 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, while it also describes some alternative approaches.

Web tag Complications

There is a widespread expectation that others can produce a template file that will give you exactly what you want to use on your PHP web pages, this is just not realistic as there are multiple permutations of many web tags and you cannot count on anyone else selecting the permutations you want to use. Don't think that making all web tags available as PHP variables on your web server is easy, let us see why.

Version specific tags

• This should be obvious, but the web tags available depend on which flavour of Cumulus is being used (Cumulus 1 or MX), and also on whether the latest version is being used. People producing a ready-made script for others to use have a number of choices:
  1. Make the script for the latest MX version, and assume all those who use it will also be using the latest MX version.
  2. Make the script just for MX, so it won't work for Cumulus 1, and choose to include only web tags that are available for a wide range of MX versions
  3. Make the script so it will return values for a large range of web tags in both Cumulus 1 and MX, but accept that some must return a sort of null if they are not available at version used by the person implementing the ready-made file(s).

• Each script provided by someone will make its selection of what PHP variables to define based on those tags and parameters available in the version they are using when their 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, adding permutations that were not available when any particular script was produced.

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. People do move to a new home, and may take their weather station with them, but any web tag based on location changes much more infrequently than any related to weather.
• 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 processing and uploading 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 been updated.

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.

Locale issues

Whether you are choosing a ready-made script produced by someone else, or you are writing your own script (which might or might not be used by someone else, or your web site might be viewed in a different country where their expectations are different), there is actually a lot to consider and that is what the next sub-sections are about.

Remember the script variables generated from web tags may be used in different ways, and different people might want outputs formatted differently:

For direct output on a web page

• Some locales use decimal commas, that is in any real numbers a comma separates the integer and decimal parts. So people in these locales expect to see any output in that format.
• Those writing scripts have to decide whether to treat
  1. as numeric output as a number (with either decimal comma or decimal point), which can be easily output and won't have unnecessary zeroes (leading or trailing zeroes won't appear in the output).
  2. or to treat as text (the Cumulus web-tag is enclosed in quotes), this is obviously needed if numbers can be replaced by hyphens when that web tag is not actually set (e.g. some monthly web tags are no set until at least one full day exists for that month); but this might mean the output includes leading or trailing zeroes.

For use in calculations, or Ajax updates

• You might want to vary the output, depending on the content of one of these script variables:
  • Maybe you vary the look of a page depending on whether it is being viewed during daytime or at night
  • Maybe you only want to display snow details when it has actually snowed
  • Maybe you want to display time of last rain when that is today, but not if there has been no rain this month.
  • Maybe you want to calculate a derivative not available as a script variable
  • Maybe you want to use the script variables to plot a graph (or some other transformation that requires a script to action)
• In all these cases, you are probably going to feed these script variables into another script, but to perform arithmetic on a number many script languages need that number to use a full stop as the separator for the decimal part.
  • Cumulus 1 makes available a selection of web tags with a "RC" prefix where the comma (if any used) is removed and the output always uses a decimal point (like a full stop).
  • The more recent version of MX allow a "rc=y" parameter than replaces any commas in the output with a full stop, this parameter is now available on any web tag that can output a number with decimal places.
• Many ready-made scripts present both the "RC" and normal versions of such tags, they have to enclose all tags (even numeric ones) in quotes so the locale does not worry about format
  • Having numeric values in quotes makes it possible the script variable includes unwanted leading zeroes, and that in turn makes it possible that any other script processing that variable might not recognise it as a number or might guess it is to base 16 instead of base 10.

Different locales may express dates differently

• • Some ready-made scripts assume that the separator between parts of the date are "/" and hard code the alternative outputs with that assumption (perhaps replacing "/" with ".").
  • Many ready-made scripts are derived from one written assuming the USA date format is being used with month before day of month, and year last.
  • Yet there are relatively few Cumulus users in the USA, and therefore the majority of Cumulus users want either day of month or year first.
  • Of course Cumulus has two different default formats for dates output from web tags
    • either in the format used by the locale selected
    • or in the ISO format of year first with hyphens between date parts.
  • Some scripts will define a number of variables from the same web tag by using different output format parameters.
  • Check your choice of read-made script can output dates in the format you prefer.

Time format =

• Do you prefer 24-hour clock (some call this timetable format or military format) or 12 hour clock with am/pm?
  • Some ready made scripts may express times in both formats so you can choose the format you want

If there are dates and times to output, Cumulus changes the date for certain web tags for times between midnight and rollover time (if 9am or 10am). Be sure you understand how any ready-made script is reporting combinations of date and time.

Tags that are specific to station type and/or sensor specific

• Remember some web tags 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 (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.
• If you look at a list of web tags, you may be surprised by how long the list is of web tags that are specific to either particular station types or to set-ups with particular sensors.
  • When looking at a ready made script, see if using it will upload a larger file than you need because it includes lots of script variable you will never use.
  • Remember, this file will need to be uploaded at real time interval because most sensors, even if you don't have all of them, update their values frequently, so the larger file than you need is being updated a lot using up your upload allowance.
• If you choose to use a ready-made script, check if it includes the tags you want, and edit out any you can't use.
  • Remember that the person producing the ready-made script might have left out tags that he/she had no interest in because of the make of weather station he/she used and/or the sensors he/she has.

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;
• From version 1.9.1, many web tags (like those reporting times and/or dates whether directly or as time/date stamps) can take output parameters that format how the date (if available) and time (if available) are output.
  • The number of different ways to specify a date or time is quite a lot, apply that to every web tag that can take output parameters and one could define perhaps a thousand different PHP variables!
• From version 1.9.3 (build 1033) some web tags (initially just "Recent History") always require input parameters, so any script turning web tags into script variables must choose which value to use for the input parameter and how many alternatives with different values for input parameter to include.
  • For each Recent History web tag there are more than 605 thousand different combinations that could be specified. Nobody wants to include all of those in any script they write as that is over 9 million PHP variables to define!

• 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 ready-made 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.
  • 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 might 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).
  • 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 $monthHighDailyTempRange='<#MonthHighDailyTempRange>'; will return dashes as that particular item is not calculated by Cumulus until at least one complete day is available.

embedded content

• • 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>;
• Yet another complication (for Cumulus 1 users) is that the values for time and date formatting parameters can include double and single quotes, but any assignment to a PHP variable of text like that requires the value to be quoted so it is treated as a string. There are some 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 another is to use the PHP 'heredoc' approach - see PHP manual. For MX then it may be possible to avoid single quotes by using the backslash to escape characters.
• Cumulus MX web tags do allow embedding of HTML, see the Web tags article for details.

Ready made PHP Web Tag templates

It is perfectly possible to produce your own templates, following the advice in Option 2 below, I know that might scare you.

• One approach, that is perhaps easier is to modify a ready-made script (as has happened for some of those listed below) by adding new lines, each with a PHP variable name (it must start with "$") on the left of an equals sign and a web tag (<#tag_name>) on the right, and end the line with a ";".
• You can add a comment at end of line using prefix "//".
• You can add a comment anywhere by enclosing it in /* and */.

• You don't need to know any more about PHP than I have said above (requirement for "$" as the first character of a PHP variable name, use of "=" between PHP variable name and Cumulus web tag, and requirement for ";" at end of each assignment).
• All you need is an understanding of the web tag syntax gained from studying the Web tags wiki page.
• The scary bit is understanding the right format to use in those web tags for the output parameters because it is easy to specify items like minutes, hour, or month, incorrectly, especially if you have moved from Cumulus 1 to MX.

• Be aware that if you are using Cumulus 1, when processing it ignores any web tags it does not recognise.
• If you are using MX when that is processing your file it issues a warning and a detailed error report for any web tag that is either not recognised in the particular version you are using or has output parameters where the interpretation is unclear. The latter is because parameters like 'h' and 'M' have different interpretations depending on context and might need a '%' before them as explained on Web tags page.

Ready-made scripts based on original by David Jamieson and Ray Beriau

They all contain PHP variables for all the web tags available in Cumulus 1, some contain all web tags available in MX. You will notice the USA style month first bias of the original authors in some of the date formats below, the assumptions for separators for date, time, and decimal)

Consequently a few of the PHP variables defined in these scripts might not work perfectly outside USA, all depending of course on which of the defined PHP variables you actually use.

For the files marked as for MX versions, the PHP variables that relate to web tags not available in MX have been given arbitrary fixed values, not nulls, so only really work for the system of the person who last updated the file.

For recent history tags the PHP variables are set to report only a few of the 9 million combinations:

1. In one approach, for each recent history web tag the PHP variable is set to the values for one day and one minute ago. These are used on a "Now" type page that compares the current values to the values at the closest time yesterday. The extra minute has to be added to the output parameters to cover the delay in retrieving the old values compared to the speed in updating of current values.
2. In another approach, a string is reported for each recent history web tag. That string contains 3 numeric values each separated by a "|". The first part is the value for 1 day ago (d=1), the middle for one hour ago (h=1), and the last for one minute ago (m=1). I am not sure why that combination was chosen, but you would need to understand how to use the PHP function "explode('|',variable_name)" to extract the values.

Otherwise, apart from a few web tags that report dates where alternative formats are added (as shown below) using output parameters and new variable names, most php variable names match the corresponding web tags name, there are no alternatives for the time-stamps and date-stamps in any weather derivatives.

Caution for some scripts

If you choose a ready-made script that includes a "?>" at the end, you will have a problem if you add even a single space or new line after that code, or in any of your own scripts that "include" the script with that code. That code is only supposed to be used when HTML commands follow it, not when there is more PHP after it.

Example of dates and times provided in these ready made scripts

Note that web tags <#hour>, <#minute> are amongst those not available in PHP variables, but also note that Greenwich Mean Time has had its abbreviation transposed by these Americans as well as month first date formats.

$date2           = strtotime(str_replace('/','-',"<#date>"));  //  current date (example format: 1346569200)
$dateU              = strtotime(str_replace('/','-',"<#date>"));  //  current date (Unix datestamp format)
$datelong           = "<#date format="dddd, MMMM dd, yyyy">";  //  current date (example format: Monday, January 23, 2011)
$dateshort          = "<#date format="MMM dd, yyyy">";  //  current date (example format: Jan 23, 2011)
$LastDataReadT2     = strtotime(str_replace('/','-',"<#LastDataReadT>"));
$LastDataReadTU     = strtotime(str_replace('/','-',"<#LastDataReadT>")); // (Unix timestamp format)
$time2              = strtotime("<#time format="hh:mm MMMM dd yyyy">");
$timelong           = "<#time format="hh:mm 'on' MMMM dd, yyyy">";  //  current time (example format: 12:34 on January 01, 2011)
$timeshort          = "<#time format="hh:mm">";  //  current time (example format: 12:34)
$timedatelong       = "<#time format="MMMM dd, yyyy">";  //  current date time (example format: January 01, 2011)
$timedateshort      = "<#time format="MMM dd, yyyy">";  //  current date time (example format: Jan 01, 2011)
$timeUTC2           = strtotime(str_replace('on ','',"<#timeUTC>"));  //  UTC (GTM) time (example format: 12:34 on 01 January 2011)
$timeUTCstd         = "<#timeUTC format="hh:mm 'on' MMMM dd, yyyy">";  //  UTC (GTM) time (example format: 12:34 on January 01, 2011)
$timeUTC_dd        = "<#timeUTC format=dd>";  //  UTC (GTM) time - date number (example format: 01)
$timeUTC_mm        = "<#timeUTC format=MM>";  //  UTC (GTM) time - month number (example format: 01)
$timeUTC_yyyy      = "<#timeUTC format=yyyy>";  //  UTC (GTM) time - year number (example format: 2011)
//$timeUTC_all     = "<#timeUTC format="yyyy' - 'MM' - 'dd' - 'hh' - 'MM">";  //  UTC (GTM) time (example format: 2011 - 01 - 01 - 12 - 34)
$timeUTC_all       = "<#timeUTC format="yyyy">|<#timeUTC format="MM">|<#timeUTC format="dd">|<#timeUTC format="hh">|<#timeUTC format="MM">";  //  UTC (GTM) time (example format: 2011 - 01 - 01 - 12-34)
$updated                    = "<#update format="'at' hh:mm:ss 'on' MMMM dd">";  //  date and time of the last web site update (example format: at 18:30:55 on 01 Jan)
$updateU                    = strtotime(str_replace('/','-',"<#update>"));  //  (Unix timestamp format)

• For latest MX version, a single template file can be downloaded from CumulusMX PHPwebtags topic in the support forum, posted by forum administrator (water01) soon after each MX update that changes web tags. It is the latest version of the American one referenced above.
• If you are not using the latest MX version, then use his earlier file that can be downloaded at this page on support forum. This one does not contain any web tags added since 2015, so will work for any earlier MX versions and won't report the errors that his latest version does for any web tag missing at your version. Equally you need to accept it may not include some of the web tags available in your particular version.
• If you are using Cumulus 1.9.4, then the download file available on File:Cumuluswebtags.txt) might suit you. 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.
  • The advantage of only choosing one possible input parameter is that this template can use PHP variable names that match the web tag name, and only use PHP arrays when the web tag returns an array.

Using an array

While the ready made scripts described above have a separate PHP variable name for each web tag, some authors have set up a single PHP variable as an array, and each web tag definition is coded as a separate element $WX[xxyyzz] of that array. The two described below differ only in their selection of input parameters for the recent history web tags; one has preselected 27 combinations, the other includes only 10. Neither offers a choice of output parameters.

• One ready-made script using an array $WX was made by Duke.
• You can download his version from this storm rain topic.
• If you use this script you need to call it by require_once 'cumulustags_no_description.php'; because it contains functions that can only be declared once to convert between decimal degrees and degrees, minutes, seconds formats in either direction, basically because it is stripping out the HTML space characters used by Steve Loft for latitude and longitude.
• His zip contains two files cumulustags_no_description.tpl and cumulustags_with_description.tpl, each uses the approach of defining an array $WX in which the index to the array elements is the web tag name for example $WX['rfall'] = '<#rfall>'; // total rainfall so far today.
• For Recent History web tags there are up to 27 different input parameters in some cases, you pick the array elements for each of the different times you require.
• It contains all tags used by either Cumulus 1 or MX in September 2014.
• It uses default output formatting, so that is why it will work with both flavours.
• The extra time and date parameters shown above appear, but as array elements e.g. $WX['timeshort'] = '<#time format="hh:nn">'; // current time (example format: 12:34).

• Another ready-made script using an array $WX was made by Ken True.
  • 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]
• It only holds a sub-set of Cumulus web tags relevant to the Saratoga template.
• For some of these web tags there are a number of output parameters that have been selected to implement:
  • For those web tags that do have a parameter defined (the recent history web tags include for example m=10 as an input parameter), you select the one you want using the optional second index.
  • Most of the web tags might not need any input or output parameters to be specified, you are using their default output, so the corresponding PHP element would not need a second index.
  • This template file is called CUtags.txt and it can be downloaded from Saratoga-Weather.org.
  • That download includes just 10 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.

Alternatives

These templates have not been influenced by the original template, but instead have tried to cover what suited each author at the time the template was written, and each author has made their own independent decision about what parameters to use.

• The simplest template of all, it essentially reproduces the layout used for tables on the web tags wiki page, so it is very nicely laid out. It was written from scratch by Brandon using all web tags available in November 2014 with Cumulus 1, although MX beta was available then, he has not identified the tags not available in MX at that time. Because Brandon has not used using any output parameters, it will work with Cumulus 1 and MX, but as it is also without any input parameters none of his Recent History PHP variables actually contain anything but rubbish. It can be downloaded in this storm rain topic.
• Another simple template, but this one includes far fewer web tags, is called CUtags.txt, it was produced by BCJKiwi as a single template file able to work with both Cumulus 1 and MX. It can be downloaded as part of his package or separately at this post of mine in a zip.
  • This template does not contain any web tags that are only available in MX, nor does it contain any web tags that require input or output parameters. The PHP variable names match Cumulus web tag names, but some of those PHP variables are set to "not used", instead of to the web tag contents, because this template file is designed for a specific set of web pages.
• This File:Web tag templates.zip contains a set of templates, each updated at different frequencies. It includes all web tags for either Cumulus 1 or MX. You may get an error reported locally when Cumulus processes an individual file as your version of Cumulus does not include every tag it will try to process. However, once it has been converted to a PHP script, it will test the version and should not give any errors as you use it on your production web site. I have taken the decision to write all the templates assuming your locale uses a fullstop as decimal separator. I am working on templates that use the Remove Comma options that Cumulus 1 and MX provide, but those are not ready to release.

Usage

Use the PHP include/require command to include the Cumulus web tags into your PHP file. (If you choose a template that includes function definitions as some of them do to permit you to list the source; then you must use include_once 'filename'; or require_once 'filename';). Then where you would insert a web tag if you were writing a template, you insert a command to "echo" the php variable

<?=$PHP_variable_name[any_index_needed];?>

The "=" in the above example is shorthand for " echo " with the spacing shown. In most of the ready made files listed for download on this page the PHP variable names are either identical to their webtags equivalent or have a name that reflects the output parameters selected, 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.

However the beauty of using script (PHP or another) is that you can add other aspects of the script language like conditions and control what HTML is output. For instance if a PHP variable tells you it is not raining you might leave out displaying the current rain rate. Or if it is night time you might report fewer derivatives than if it is day time. If it is the first day of a month, then you can leave out the rows in your table that would report the highest and lowest for the month that are not yet defined. Such php script might look something like this example that wants alternating rows to look different and has to adapt that if one row is left out:

<?php if ($show_apptemp){ ?>
               <tr class="even">
                  <td><span lang="en">Apparent Temperature</span></td>
                  <td style="text-align:right;"><span class="ajax" id="ajaxapptempNoU"><?php echo $RT_apptemp ?></span></td>
                  <td><?php echo $tempunit; ?></td>
               </tr>
               <tr class="odd">
                  <td><span lang="en">Heat Index</span></td>
                  <td style="text-align:right;"><span class="ajax" id="ajaxheatidxNoU"><?php echo $RT_heatindex ?></span></td>
                  <td><?php echo $tempunit; ?></td>
               </tr>
               <tr class="even">
                  <td><span lang="en">Humidex</span></td>
                  <td style="text-align:right;"><span class="ajax" id="ajaxhumidexNoU"><?php echo $RT_humidex ?></span></td>
                  <td><?php echo $tempunit; ?></td>
               </tr>
          <!--     <tr class="odd">
                  <td><span lang="en">Indoor Temperature</span></td>
                  <td style="text-align:right;"><span class="ajax" id="ajaxintempNoU"><?php echo $RT_intemp ?></span></td>
                  <td><?php echo $tempunit; ?></td>
               </tr> -->
<?php }else{ ?>
               <tr class="even">
                  <td><span lang="en">Heat Index</span></td>
                  <td style="text-align:right;"><span class="ajax" id="ajaxheatidxNoU"><?php echo $RT_heatindex ?></span></td>
                  <td><?php echo $tempunit; ?></td>
               </tr>
               <tr class="odd">
                  <td><span lang="en">Humidex</span></td>
                  <td style="text-align:right;"><span class="ajax" id="ajaxhumidexNoU"><?php echo $RT_humidex ?></span></td>
                  <td><?php echo $tempunit; ?></td>
               </tr>
               <tr class="even">
                  <td><span lang="en">Indoor Temperature</span></td>
                  <td style="text-align:right;"><span class="ajax" id="ajaxintempNoU"><?php echo $RT_intemp ?></span></td>
                  <td><?php echo $tempunit; ?></td>
               </tr>
<?php } ?>

The different Main Approaches to data transfer

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 all the different approaches.

Option 1: 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. Therefore it has great appeal to those writing packages that are designed to be very efficient code, very portable across different applications, where non-technical people just accept the outputs provided and don't need to understand what goes on within the black box. If you don't want to use PHP, or just don't understand how to use it, you might consider this and you will find more about this approach on the XML web tags page in this wiki.

Some people consider XML is too complicated and a long winded way to represent variables (they would say languages like PHP are easier for humans to read), but XML was the way that Steve Loft chose to implement the Weather Diary feature in Cumulus 1, so if you want to include whether snow is falling or lying (or the text entered into the diary) in your web pages you must use a routine that reads XML within the PHP you write if you are still using Cumulus 1.

Before leaving the subject of XML it is worth recording that XML is considered as the best approach for the future by many after it became a part of the standard for SQL from 2000. SQL is the most popular way to access and maintain data, so extending it from only working with relational (table based) databases, to updating XML formatted information has given XML a big boost (for example the WMO and ICAO have specified a XML and geographical location based approach for reporting weather conditions at airports and for some years have been persuading those running airports to swap from reporting METAR in traditional alphanumeric characters. The alphanumerical shorthand approach was introduced when the shortness of the code was critical for easy transmission by telex). The new approach is not designed for human observers and pilots to read the weather reports as reported, but being machine readable makes it easier for computer driven flying to take account of changing weather conditions and it can be presented to pilots in a more friendly graphical way, in the cockpit, changing the mix of information shown as they move along their route.

Option 2: PHP array or Multiple PHP Variables

Another approach is to create a separate PHP variable (or in a few cases an array) for each Cumulus web tag:

1. You write one or more Cumulus template files, each having a "<?php" in the first line, each then has a number of lines of the following format:

$_php_variable_name = '<#_cumulus_tag_name optional_input_parameters optional_output_parameters>';

2. One convention is to make the php_variable_name match the cumulus_tag_name. This breaks down if you use names like $version for other purposes, or if you get confused by the random naming standard adopted by Steve Loft (some yesterday tags have Y at end, some don't, sometimes Y means yesterday, other times Y means yearly), so feel feel free to invent you own consistent naming standard.

3. If the cumulus web tag always returns a numeric value, it is better to leave off the quotes, because then it can be used in PHP arithmetic more easily. To discover all available web tags for the Cumulus version you are using see top of Web tags page. See the examples at the start of this article for some monthly tags that don't return numerical values on the first day of a month.

4. I have shown single quotes in my example, but they do not always work, see the notes at the start of this page, there is further discussion about problems with delimiting strings at this cumulus support forum link.

5. In the format example, I mention input parameters, see the Web tags article page for full details of where you can use them, but they might indicate what information you are seeking if like Recent History you can get values for a range of different times. I also mention output formats, these are also explained on the web tags page, but they might select whether a time is shown in am/pm format or 24-hour format, whether a date uses the full month name or a number and so on. You might want to quote the same web tag with different selections and either assign each to a different variable name or to a different element of an array variable.

6. You can include PHP comments any where you like, if on a separate line delimit by "/*" to "*/", if at end of line prefix by "#" or "//". Don't put any special characters at the end of this file, it will become pure PHP, and that never uses a terminator "?>". That terminator is needed only in mixed content files when there are HTML statements after the terminator.

7. I say above "1 or more template files". Since you can tell Cumulus to process/upload files at different intervals, you might want to include those web tags that change frequently (now and today for example) in a template file that you will action at the real time interval, and include those web tags that rarely change (e.g. yesterday, station-related, units) in a template file that is only uploaded at end of day. Yet another template file can be uploaded at normal updating interval, that might include the monthly and yearly tags for example. You decide what suits your own restrictions on total size of files to upload at different frequencies.

8. Having produced this template file, give it a name that makes sense to you, some people include a T just before the extension to remind you it is a template file. The normal extension is ".txt", although some peole use '.tpl' to indicate it is a template, but you could be inventive and put ".cum" if you want; Cumulus will not care what extension is used for a file it is asked to process.

9. The template files are then listed in the "extra files" settings of Cumulus, so they are processed at a selected interval and turned into PHP scripts. 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.

10. To make use of the relevant script in your customised pages, use the instruction require cumuluswebtags.php, substituting whatever you set as the remote name.

For more information on how to write a template file or how to ask Cumulus to process files see processed by Cumulus topic.

The ready made templates referenced earlier are all template files using either PHP variables or PHP arrays and therefore alternatives to producing your own files using the instructions above.

Option 3: 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 uses this approach to provide variables for plotting the charts on your web site.

• To have the json files uploaded to your web site, you must enable Include standard files within the Web/FTP settings section of Internet Settings.
• Cumulus MX has one json file per weather chart
• Within each json file there is an array defined; each element of that array being a sub-array containing a time-stamp and the value at that time.
• The interval between sub-arrays depends on the chart, for daily rain and daily temperature there is a sub array for each day; but for most there is a sub-array for every minute (assuming Cumulus is left running for long enough) for a full 24 hours.

If you want to set up your own json files, you may follow the same approach but 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 a template file called "cumuluswebtags.txt", so if you are using a file with another name or multiple template files, adapt the instructions as relevant.

Choose your template(s)

First either download a read made template, choosing from those available as listed above; or write your own template(s) following the guidance above.

Edit your template(s)

If you have chosen a ready made template, or have realised you need a PHP variable for a different set of parameters to those coded already, you will need to edit your template.

1. It is best to use an editor that allows you to choose the encoding for the file it saves. Any editor designed for editing code should do this (e.g. Notepad++), but word processors and the popular online editors will add unwanted extra characters. The best encoding for files to work with Cumulus is "UTF-8 without BOM".
2. Open your file in your chosen editor.
   • If the first line contains the following sequence of 4 characters "<" then replace those 4 characters with a single "<" (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.
3. Add any new web tags that have been added for the Cumulus version you are using, that were not available when the template was created.
4. Next look at any web tags that can take input and/or output parameters; add any parameter combinations that you need for your own implementation.
   • For example, for my implementation, I found that my customisation of the template version had used many more Cumulus web tags with parameters than I expected, consequently my cumuluswebtag.cum template file has (amongst others) 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">';
5. Next delete any rows with web tags that are not relevant to your weather station model for greater efficiency;
6. Finally save your edited template file or files in either the "web" directory where Cumulus has the files it will process or where you store your customised templates.
   • The choice of filename and extension is up to you, it might make sense to use a different name or extension (e,g. "cumuluswebtagsT.cumMX"), if you have edited the file to be sure you don't confuse it and the original and you know which version of Cumulus it is for.
   • If you have several templates being uploaded at different intervals you might choose names like "webtagsRealtimeT.txt", "webtagsNormalT.txt" and "webtagsEoDT.txt".

Add your template(s) to Extra Files processing

Cumulus 1

Here is a screenshot for Cumulus 1 using the name as "cumuluswebtags.txt" if you are basically using the provided code).

1. On the 'Cumulus main screen', in the Configuration menu, select the Internet option;
2. On the 'Internet Settings' screen, select the Files tab;
   
   
3. 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;
4. Finally, click on the lower-right OK button to save the newly entered settings.

Cumulus MX

It is broadly similar for Cumulus MX.

1. Select Settings menu in the user interface, then select the Extra Files page. Scroll through to a page with empty rows if necessary.
   
2. The local file name column does not have the browse selection available in the equivalent Cumulus 1 feature. So be very careful that you type in the full path correctly. You don't need a drive selector, Cumulus will assume the file is on same drive as the MX executable, so only specify drive if it is somewhere else. You might have a feature that allows you to do a list of files and for the file picked show its path, if so you can copy that path into the box in the Local files column.
   • In the example illustrated there are 4 web tag templates, each containing the web tags that are to be processed at a different frequency, all following advice on this page:
     1. one ('static') only needs to be processed once, it is shown as using EOD here, but actually you would use real-time once, and then delete the local name so Cumulus did not try to process it again.
     2. one('real_time') is processed at real time interval and uploaded by FTP at same interval
     3. one ('standard_update') is processed and uploaded at the standard uploading interval
     4. the remaining one is processed and uploaded at the last task when the MX_End_of_Day_Process runs.
3. The remote filename column needs to contain the FTP path and required destination file name if you want Cumulus MX to FTP the processed file to your web server. If you have your web server on the same local network as the device where you run the MX engine, then MX can use copy to transfer the file to your web server and you need the full path and file name relative to where the Cumulus executable is stored (again you don't need the drive if same drive).
4. You must have a tick in the process column, your template file (or files) will not be valid PHP until Cumulus MX has processed it and each PHP variable has a value.
5. If you want your file processed and uploaded at the real-time interval you put a tick in the realtime column.
   • Note that Cumulus cannot process a file at the real-time interval unless you have enabled the real-time timer (Internet settings page, Web/FTP settings section, tick Enable Realtime)
   • Note that Cumulus cannot upload a file by FTP at the real-time interval unless you have set a FTP process to happen at real-time interval (Internet settings page, Web/FTP settings section, tick Enable realtime FTP)
6. Unless your web server is on the same local network as your Cumulus software, tick the FTP column.
7. If you have followed the instructions above and saved your file in UTF-8 encoding, tick the UTF8 column.
8. Leave the Binary column unticked.
9. If you have not ticked the realtime column, your file will be uploaded at the normal uploading interval unless you tick the End of Day column. If you do tick here, then your file will be uploaded right at the end of the rollover process, at this stage Cumulus will have the new date in every date type tag, it will have initialised the monthly tags to be empty, and the yesterday tags will have been set. In other words, you will only use this option if you have other web tag templates being uploaded during the day.

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 a template file , some files (e.g. the brandon script) let you do this by appending the querystring ?source=view to the end of the URL. Other templates expect you to add the querystring ?parse=source and still others use ?view=source. There may even be other variants. I tried hard to get standardisation see Source Listing suggestion in the forum, but I know of at least five other variants, source is abbreviated to 'sce' or 'src', and as well as parse, people use 'download'.

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 web tags during it's processing cycle. It won't show you the original template with web tags in it.