PHP
Incorporating Script
There are various script languages that can be used to enhance what can be done in pure HTML as described on the Customisation page.
Using JavaScript
JavaScript comes in different versions, depending on the browser, generally it obeys the "ECMA-262 standard". Internet Explorer, especially old versions, offers jScript instead, and so there may be problems with writing code that all browsers can understand. Normally, you should include <noscript> ... </noscript> around some alternative HTML to be used when the browser does not offer JavaScript, or it has been switched off (for security reasons) by the user. So many sites do use JavaScript now that modern browsers like Firefox do not offer an easy way to turn JavaScript off.
Incidentally, Java is yet another programming language, and it is very different to JavaScript.
A quick comparison between pure HTML and HTML with JavaScript can be seen from this example. Essentially, the Browser produces a page structure by reading the HTML, and then the browser will run the JavaScript instructions as it meets them (or a call to the separate file containing that code) and that can be interpreted to modify what is seen on the web page. A user can normally ask their browser to see the original HTML (display source) and to display the script that is modifying that. The user may be able to stop the script from running or run a different script, so JavaScript can have security implications. It can however be an advantage that code can be run easily to update part of a page, leaving the rest. A disadvantage is that different browsers may offer different versions of JavaScript, so the page designer cannot make assumptions about what JavaScript code will be available to all potential users.
Using PHP Hypertext Pre-processor
Original material by DAJ, but moved to this new page; on a former web-site he used PHP to generate his page, JavaScript to update his page frequently making use of information gathered using AJAX method and the jQuery library of JavaScript code to actually make his script browser independent - see support forum.
Update by Sfws (talk) 17:18, 22 April 2015 (PDT) based on material formerly on Customised templates page.
Many web servers support the PHP scripting language, this means that the web server will parse the contents and obey all the script instructions to generate a pure HTML page that it forwards to a user agent (e.g. browser).
More about PHP
PHP regularly issues new versions, with major and minor upgrades. You need to ensure that your development server and your production server use the same version, or that you only use features that are common to both versions. If somebody else runs your web server, you need to track what PHP version they use. But since the PHP parser creates a HTML page to pass to each user, it does not matter what any user has on their device.
There are volumes of information available on writing PHP scripts, both in your local bookshop, or library, and on the web. Some of these books cover a database query language and maybe running a web server as well as PHP.
- Easy lessons on W3 school
- Reference tutorial on Getting Started (php.net).
However, below is a basic introduction to understanding and writing your own PHP to generate your web-page. This Wiki article cannot teach you PHP because it includes a very large number of functions, nor can I tell you if your web server supports PHP, but the examples below give a brief hint of how PHP could be used and should help you to get started.
One possible advantage of this type of script is that by default the script cannot be seen (unless the developer has added some code (see this forum topic) allowing a query-string to be added to the url asking for some or all of the PHP source to be shown to the browser). This makes for a more secure script, because it only runs on the web site server. For instance if information is read from a database or in another way involves a password of some kind, all that code can be hidden, the end-user then has no way to modify the script to get information that should not be seen by others. A disadvantage is that it can be more complicated to update information on a page, requiring the whole page to be regenerated. (Consequently, a mix of scripts may be used with updating by AJAX or JSON, added to the PHP that generates the basic page. That is beyond the scope of this article).
What about Ajax?
Ajax is, in essence, a concept not a new language. It's basically JavaScript being used to request information, and it works in the background while you are viewing a page on the browser.
When to use JS (Javascript) or PHP ?
- Using PHP is much faster (usually); as all the work, of deciding what to include on the web page, is done on the web-server (which should be fast) and only the resulting HTML is sent to the browser.
- JavaScript is slower as the initial page, then all the JS code, is sent to the browser; then code is executed on the PC, and then the page is updated.
- A user may have JS disabled, so you might need to consider how your page will work without it (see above).
- If you do not have PHP on your web-server you need to use JS!
Using PHP in Cumulus templates
This approach incorporates some PHP script in a page that still contains Cumulus web tags so still requires processing by Cumulus.
This is suitable when you have been using Cumulus and its standard web site. Sine then you have gained some grasp of Stylesheets, some grasp of HTML and now want to try PHP, but do not want a big redesign of your set-up.
- Assume initially your have a customised template that contains just pure HTML and Cumulus web tags (like in a standard Cumulus template page), indeed it might be a simple edit of a standard cumulus template.
- Assume it is no longer a standard page, so it has to be listed on the Files tab of the Internet screen within the 'Configuration' menu; the remote file name currently has the extension ".htm" or ".html".
- Now change the file extension to ".php" so that the PHP pre-processor will parse the file, before it is passed to the browser as a HTML page.
- The php script might be used for a decision more complicated than the boolean options that can be achieved just with standard HTML.
An example of a Cumulus template using PHP
In the UK vehicle headlights must be used between half-an hour after sunset to half-an-hour before sunrise, so maybe you want to modify a standard "xxxxT.htm" page that is currently processed into "xxxx.htm" and it has sunrise/sunset times on it. Change it to be processed into "xxxx.php" instead and incorporate 2 new chunks of code:
<?php // start of PHP script
// setting PHP variables using web tags available in Cumulus (version 1.x.x)
$latestDay = '<#metdate format=yyyy>'.'-'; # Year could be treated as integer converted to string, but easier to make it literal
$latestDay .= '<#metdate format=mm>'; # Read as literal so any leading zeros do not make it Octal integer
$latestDay .= '-'.'<#metdate format=dd>'; # Read as literal so any leading zeros do not make it Octal integer
$sunrise = "<#sunrise format=h:nn>"; # use format to remove any leading zero, so can not read it as Octal integer
$sunset = "<#sunset>";
// setting new PHP variables (not available in Cumulus web tags)
// end of lighting up time (hours of darkness)
$darkness_end = new DateTime($latestDay.' '.$sunrise); // sunrise
$darkness_end -> sub(DateInterval::createFromDateString('30 minutes')); // subtract 30 minutes
// start of lighting up time (hours of darkness)
$darkness_start= new DateTime($latestDay.' '.$sunset); // sunset
$darkness_start-> add(new DateInterval('P0Y0DT0H30M')); // add 30 minutes
?> <!-- end of PHP script -->
....
<tr>
<th title="Darkness times calculated by PHP">Darkness starts</th>
<td><?=($darkness_start->format('g:i a'));?></td>
</tr><tr>
<th>Darkness ends</th>
<td><?= ($darkness_end->format('g:i a'));?></td>
</tr>
This example shows that PHP instructions can be inserted into a normal HTML page simply by preceding the PHP instructions by the tag <?php, you then return to HTML using the tag ?>. All PHP instructions end in a semicolon (;) and to concatenate two strings you use full stop (.) so to concatenate something extra to an existing string you use full stop equals (.=). If the instruction is simply to place the contents of a PHP variable into HTML, the standard is to precede the PHP variable by <?=. Normally, PHP variables use names that start with dollar sign ($). Comments may be inserted into PHP code in several ways, but double slash (//) is used for annotations where you want the instruction before to be processed, but then the PHP parser should ignore everything after the double slash in the same line.
Incidentally, do look at the Cumulus FAQ or web tags where what Cumulus reports as Sunrise time is explained as the last one before any midnight GMT, and what it reports as Sunset time refers to that occurring after the midnight GMT, so they are frequently on different days.
If you want sunrise, sunset, darkness start, and darkness end to all refer to the same day, you will probably choose to use PHP functions for sunrise, sunset rather than Cumulus web tags. The example above was just to show what can be done, not what you should do!
Using PHP scripts not processed by Cumulus
- A more efficient approach, this is a bigger implementation change, is to set Cumulus to process just something like this file to read the Cumulus web tags you want to use (some may have parameters to indicate what period to use or how to format the date they output) and then the processed file will create PHP variables/arrays for your other PHP web pages to use.
- Then you create a new PHP script that does not get processed by Cumulus. For example "thismonth.php" would start with the same HTML5 as normal, but the table is output by the PHP script:
<!DOCTYPE HTML>
<html>
<head>
<meta charset="UTF-8">
<meta name="description" content="<#location> weather data" />
<meta name="keywords" content="Cumulus, <#location> weather data, weather, data, weather station" />
<title><?php
include 'cumuluswebtags.php';
echo "$location";
?>weather</title>
<link href="weatherstyle.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="content">
<h1><?php
echo "$location";
?> weather</h1>
....
<table style="width:100%;border-collapse: collapse; border-spacing: 0;" >
<caption>This month's highs and lows</caption>
<tr>
<td colspan="3" class="tableseparator_temp">Temperature and Humidity </td>
</tr>
<tr class="td_temperature_data">
<?php
echo "<th>Highest</th>";
echo "<td>$MonthTempH $tempunit</td>";
echo "<td>$MonthTempHT on $MonthTempHD</td>";
echo "<th>Lowest</th>";
echo "<td>$MonthTempL $tempunit</td>";
echo "<td>$MonthTempLT on $MonthTempLD</td>";
?>
</tr>
....
echo <<< END_OF_QUOTE
<tr>
<td colspan="2" class="spacer">Pressure (sea level)</td>
</tr>
<tr>
<th class="labels">Lowest</th>
<td class="site_data">$MonthPressL {$pressunit}</td>
<td class="time_stamp">at $MonthPressLT on $MonthPressLD</td>
</tr>
<tr>
<th class="labels">Highest</th>
<td class="site_data">$MonthPressH {$pressunit}</td>
<td class="time_stamp">at $MonthPressHT on $MonthPressHD</td>
</tr>
</table>
END_OF_QUOTE;
....
Note that only excerpts from the code are shown. Earlier in this article we saw the shorthand to output content of a variable into HTML used '<?=', now we see the two ways of getting PHP to output more complicated HTML code, either by using separate echo commands for each line or using the "heredoc" approach so that one echo can be applied to multiple lines. In the latter way, the syntax requires a space after echo and after <<< but does not allow any other spaces (nor tabs) in the two enclosing lines (that precede and follow all the listed output). PHP is even more useful if we want to use conditional instructions or loops. For example, by default Cumulus will set the time-stamp of the highest hourly rain in a day to your rollover time if there is no rain in the day. A conditional could test the PHP variable containing the highest hourly rain, and only output the time-stamp if that conditional is not zero:
<th>Rainfall (Highest Hourly)</th> <td><?= $hourlyrainTH;?> <td> <?php if($hourlyrainTH) echo $ThourlyrainTH; ?> </td>
Other PHP examples
PHP is commonly used with a database, Cumulus MX can append log data to a database, and so PHP will enhance what you can do with web pages. Even if you are using Cumulus 1 you may load the daily summary log file (and possibly other log files) into a database. See Daily_Summary article for several PHP scripts that can be used if you have a table with daily summary values on your database.
The support forum includes many ideas for using PHP code, here are just a couple of them that are easy to implement:
