Php webtags

Introduction

What are web tags for?

• Cumulus defines marker tokens called web tags that can be incorporated in template files that it processes.
  • When Cumulus is processing these templates, whenever those place-holders are encountered Cumulus inserts actual values into its output file that might be a web page or a script file
  • Those inserted values are derived from processing information supplied from your weather station
  • Other content from the template file is inserted unchanged (apart from encoding in format defined by settings) into the output file.

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 might choose to use script running on your web server to produce the HTML you want on your web site, (instead of asking Cumulus to process templates and upload the resulting output web pages), but you still need a way to get the derived values that Cumulus calculates locally into those web based scripts:
  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. 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.

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

• 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. However, 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 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).
  • 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 more difficult to do arithmetic with them, and may insert unwanted leading zeroes.

• 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. Of course Cumulus actually outputs dates either in the format used by the locale selected or in the ISO format of year first with hyphens between date parts.
  • Check your choice of read-made script can cope with dates in the format you prefer.

• 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. If you are writing your own script, bear this in mind.

station and/or sensor specific tags

• 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. In general these sensors will be reporting values that do need to be updated at real time interval, if you do have that sensor.

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;
• 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 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.
  • 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).
  • 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 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.
• Cumulus MX web tags do allow embedding of HTML, see the Web tags article for details.

Ready made PHP Web Tag templates

Instead of producing your own template as described in Option 2 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:

Be aware that if you are using Cumulus 1, it ignores any web tags it does not recognise. If you are using MX 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.

Based on original by David Jamieson and Ray Beriau

These all work with Cumulus 1. They all contain PHP variables for all the web tags available in Cumulus 1.

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

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. You will notice the USA style month first bias of the original authors in some of the date formats below.

Note there is an error in every single one of these files - they contain a "?>" at the end, that should not be used in pure PHP files - see PHP manual instruction. Should white-space or new lines being added after the PHP closing tag, even accidentally, there may be unwanted effects because PHP will start output buffering when there is no intention from the programmer to send any output at that point in the script. That applies even if the extra is after the include/require in the script using this file.

$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 version 3.5.3 (build 3074), a single template file can be downloaded from CumulusMX PHPwebtags topic in the support forum, posted by the administrator (water01) as an update to the one below.
• An equivalent for version 3.0.x is at this page on support forum also posted by the administrator (water01), and developed from the . This one does not contain any web tags added since 2015, but use this one also for versions before 3.5.3 to avoid any errors being reported and accept it may not include some of the web tags available in in-between versions.
• An alternative approach in the early days of MX was taken by Duke. You can download his version from this storm rain topic. 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. It contains all tags used by either Cumulus 1 or MX in September 2014. 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 it stripping out the HTML space characters used by Steve Loft for latitude and longitude. For Recent History web tags there are up to 27 different input parameters in some cases. 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).
• For the final version 1.9.4 of Cumulus 1 use the download file available on 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.
  • 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.

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.
• Another approach is to create an array $WX that holds a sub-set of Cumulus web tags, choosing some parameter combinations to implement:
  • 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]
  • 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.
  • 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.
  • A template file to do this is also called CUtags.txt and it 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.

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 (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 METAR in traditional alphanumeric characters. Those were 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, but being machine readable makes it easier for computer driven flying to take account of changing weather conditions.

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.