5,838
edits
Customised templates: Difference between revisions
From Cumulus Wiki
Jump to navigationJump to search
m
Restructure of page with virtually no content change
m (Restructure of page with virtually no content change) |
|||
|
[[Category:WebTools]]
= HTML 5 - a very quick guide to structure =
It is possible to take the standard Cumulus web templates and customise these into totally new ones to your own requirements. A basic understanding of HTML is useful.
=== Standard HTML 5 start for a Cumulus template ===
A Cumulus template written in HTML 5 requires a simple start to the file:
<pre>
<!DOCTYPE html>
<!-- the above must be on the first line by itself and tells the browser that HTML 5 applies -->
<html lang="en"><!-- modify this to indicate your language -->
<head>
<meta charset="UTF-8"><!-- assigns the recommended standard encoding -->
<meta name="description" content="<#location> weather data"><!-- you can choose a different way to explain what the page contains -->
<meta name="author" content="<!-- put name of author here or leave this line out totally -->">
<meta name="keywords" content="Cumulus, <#location> weather data, weather, data, weather station"><!-- you can choose a different set of key words -->
<title><!-- insert here what is to appear in browser tab title --></title>
<link href="weatherstyle.css" rel="stylesheet"> <!-- This line links the standard Cumulus style-sheet
to the HTML page (and implies the HTML and CSS files are in the same web site directory) -->
<!-- in some customisations you may need to load code libraries or include script here ...
(The support forum includes code from various authors using various libraries and one of these examples might help you)
What you put here could be PHP code, JavaScript, or calls to libraries like jQuery, HighCharts or many others, anything that can be loaded before the page output starts -->
</head>
<body> <!-- This defines the start of what the browser is to display in its window -->
</pre>
The comments <code><!-- a comment goes here --></code> are place holders explaining the above code
== Structure that browser displays ==
The main part of the page (you can base that on what you can see in the closest standard template to what you are trying to achieve) goes next.
== Standard Finish ==
All templates should have this standard finish if you have created a Cumulus style template:
<pre>
<p class="credits"><br />
Page updated <#update><br />
powered by
<a href="http://sandaysoft.com/products/cumulus" target="_blank">Cumulus</a>
v<#version> (<#build>)
</p>
</div>
<!-- in some customisations you might need to load external JavaScripts here that run after the browser has created the page structure -->
</body>
</html>
</pre>
=The Standard Templates=
Cumulus has a number of template files that it uses if you select to 'Include standard files' within Internet Configuration:
[[File:SimpleInternet-StandardTicks.png]]
The '''template files''' are stored in the 'web' folder under your Cumulus installation on your PC. They all have a 'T' (for 'template') in their names:
{| border="1" class="wikitable"
|gaugesT.htm
|from version 1.7.11 21st June 2008
|Includes some free gauges originally written for FreeWX, displays the three wind gauges from the Cumulus main screen and
|-
|thisyearT.htm
|monthlyrecordT.htm
|from version 1.9.3 10th April 2012
|Shows extremes for a particular month
|}
== What is meant by 'Cumulus processes templates' ==
#When Cumulus is ready to perform a web site update, it will read each template file:
#*If ''Include Standard Files'' is selected it processes all the standard files (those listed in table above). The (built in, third party) component which handles the processing of the template file copes with a missing input file by creating an empty output file.
=Changing the Standard Templates=
Typically the templates are modified to include additional weather data, or remove it. This is generally done by adding or removing Cumulus [[webtags]], but you normally have to vary the HTML structure by adding/editing/removing table cell (<td> to </td>) elements and possibly add/remove a row (<tr class="..."> to </tr>) element.
*You can modify one or more of the template files listed above. For example, you may wish to
== Templates in cumulus\web\originals sub-folder ==
From version 1.8.9 onwards, the Cumulus installer installs the standard templates in a Cumulus subfolder called 'web/originals' so you can refer to them. '''Do not edit these.'''
==Editing to create one or more customised templates in the standard web sub-folder==
*Keep copies of any xxxT.htm files you modify. It is best to back up the whole Cumulus folder onto a different disc on a regular basis.
*If you edit one or more of the templates, listed in the table above, in the ''cumulus\web'' sub-folder, keeping their original names, this has the advantage that Cumulus will [[#What is meant by 'Cumulus processes templates' |process ]] the customised template as if it is an unmodified standard one.
=== Coding standard and character encoding for Customised Templates using the same names as Standard Cumulus Templates ===
[[File:Web settings.JPG|left]]Your edited template should be written in ''HTML 5'' using ''charset="UTF-8"'' encoding.
*If it is using one of the standard names in the table above and does not comply with that coding, then you need to unselect the 'UTF-8 encode' selection marked here by red arrow, get to it via '''Configuration''' menu, Internet option, ''Sites/Options'' tab and look for Web Settings frame in top centre.
*Finally, if it uses a name other than a standard one, treat as [[#Creating or Editing Templates in a Separate Folder]].
=== Navigation Links ===
On a standard Cumulus page there are some HTML headings and then a HTML table ending with a way to select another Cumulus page (a set of 'anchor' links). If you are modifying standard Cumulus templates or adding extra pages of your own to those existing, then you will need to modify the navigation links on all pages, so a page can access any other page. The support forum can be searched to see what problems others have encountered when doing this.
Essentially you need to surround the navigation bar links with suitable HTML elements (see standard templates for examples, often they are in a table cell defined by <td colspan="X"> and </td> where X is set to the number of cells in other rows).
<pre>class="td_navigation_bar">:<a href="index.htm">now</a>::<a href="gauges.htm">gauges</a>::<a href="today.htm">today</a>::<a
href="yesterday.htm">yesterday</a>::<a href="thismonth.htm">this month</a>::<a href="thisyear.htm">this year</a>::<a
href="record.htm">records</a>::<a href="monthlyrecord.htm">monthly records</a>::<a href="trends.htm">trends</a>:<#forum><#webcam></pre>
*If you have other pages on your web site not part of your weather reporting, you might wish to add a link to a 'Home' page, or
*for weather reporting you might add extra pages (such as the [[SteelSeries_Gauges|steel series gauges]], the [[AnnualDataSummary|daily summary]], [[Highcharts_-_Realtime|Extended graphs]]), or
*the support forum has many other ideas (just a few examples are find a way to show the weather for a year ago, to show the 10 highest or lowest, to find the most recent date when the latest extreme was last exceeded).
If you add extra items, the links may be too wide to fit within the screen, rectify this by adding a space between a pair of colons where you want to allow the browser to move to a new line (or defining two table rows each with half the anchor links). Alternatively, introduce drop-down selections where links are grouped into categories, too complicated to explain here, but examples appear in the support forum and are explained elsewhere on the web.
===Updating to a new Cumulus build===
[[File:Components_screen.JPG|right]]
*As soon as you edit templates, remember that when you update to a new build of Cumulus (or re-install the current version) the installer offers you the option of either installing the new build's standard 'HTML templates' in the 'cumulus\web' folder, or not replacing the current contents of that sub-folder. If on the installer screen shown you select to install the templates, any changes you made in the web subfolder will be lost as Cumulus will delete everything from the 'cumulus\web' folder before installing the new build's standard 'HTML templates' in that 'cumulus\web' folder.
*You can select your own local folder path.
*You do need to tell Cumulus the local and remote file names you require - as described in [[#Creating or Editing Templates in a Separate Folder ]]
= Some specific customisation examples =
Your weather station might be a sort that can accept [[Extra_Sensor_Files| Extra Sensors]] and if so you probably want to add web tags for those taking your cue from the various examples below.
== Adding indoor humidity, indoor temperature, soil temperature or any other 'extra' parameter to main page ==
The standard file includes a table where for each row (<tr class="..."> to </tr>) there are 4 cells (<td> to </td>) arranged as 2 pairs. The HTML tag <th> that starts the row uses a class to define its look, in the style-sheet linked to the HTML that class will have properties like background colour defined.
#The first cell of each pair consists of a label identifying the observation being reported
#The second cell contains a Cumulus web tag representing where the value is to appear followed by
#* either another Cumulus web tag representing where the unit is to appear,
#* or the unit directly typed in.
The standard page does not include any indoor temperature and humidity measurements that your station may offer, if you decide to add these see example below.
<pre>
<tr class="td_temperature_data">
<th>Indoor Temperature</th>
<td><#intemp> <#tempunit></td>
<th>Indoor Relative Humidity</th>
<td><#inhum> %</td>
</tr>
</pre>
Cumulus standard web pages use "<td>" tag for labels, but you could use "<th>" as shown in this example, and could add a reference to that tag in the CSS to change the look of label cells. See [[Stylesheets|styling page]] for more information.
Since on this web page there are two pairs of table cells per row, if you really want to add ''just one pair'' in a row, then you need to also add ''an empty pair of cells'' to keep the same count of cells in every row:
<pre>
<tr class="td_temperature_data">
<th>Indoor Temperature</th>
<td><#intemp> <#tempunit></td>
<td colspan="2"></td>
</tr>
</pre>
Similarly you can add any other observations, remember you need to add another 'tr' start tag with the appropriate class attribute value, then 4 table cells, and don't forget any of the end tags.
== Adding/removing Solar table cells for main page and trend graphs ==
Below are some examples relating to solar and UV sensors.
See [[FAQ#I don't have a solar sensor. How do I remove the solar data from the supplied web pages?|this FAQ]] for how to customise all relevant standard pages.
=== Simple customisation of indexT.htm ===
How to Customise your indexT.htm is described here, but the FAQ referenced just above repeats an excerpt from that and also covers todayT.htm and yesterdayT.htm.
The standard file includes a table where for each row (<tr class="..."> to </tr>) there are 4 cells (<td> to </td>) arranged as 2 pairs. The HTML tag <th> that starts the row uses a class to define its look, in the style-sheet linked to the HTML that class will have properties like background colour defined. Each pair of cells consists of a label identifying the observation being reported and a Cumulus web tag representing where the value is to appear.
<!-- End of solar data -->
</pre>
*Delete '''all''' of the above code segment if you do not have
*The <#ET> web tag only applies to Davis weather stations that include a solar sensor, if your solar sensor is another make, you might want to partly or completely change the code to the following so you can see your lux observation (Fine Offset solar measuring models only) and/or your ultraviolet observation instead of, or in addition to, whichever of the original parameters either does not apply, or does still apply:
<pre>
</pre>
=== Slightly less simple customisation of trendsT.htm ===
The standard template plots temperature range and rainfall on a day by day basis for the '''Daily Chart period''' as set on ''Display'' settings screen from '''Configuration menu''', but all the other graphs plot points at 10 minutes interval for thumbnails and 1 minute interval for the large graph (assuming you have left Cumulus running) for the '''Detailed Chart Period''' set in the same place.
There are many ways that ''trendsT.htm'' (this section applies to Cumulus version 1 only) can be modified.
If you want to change which lines appear on a particular graph, or any other feature of that graph, see Cumulus '''Help''' for the graphs option on the '''View''' menu.
# You can change which Cumulus produced graphs are included (the standard version includes indoor temperature but excludes solar related graphs). The necessary edits to do this are described below.
# The standard template uses JavaScript to action the change of the large graph when a thumbnail graph is clicked. All modern browsers support script, but you might want to eliminate script and just use pure HTML as explained [[Editing_content_of_a_webpage_using_either_HTML_or_Script| elsewhere in this Wiki]].
</table>
</pre>
If you look in 'web\images' sub-folder (this path can be changed in [[cumulus.ini]]) of where you have installed cumulus.exe, you will see 3 more pairs (solar, UV, and Sunshine) of images not mentioned in above code segment. You might want to add 1 or 2 of them taking hints from the revised segment below. Note that in two rows a 'colspan' attribute is used to place one piece of text across the entire row, and the value given to that parameter needs to match the number of 'td' elements in other rows. Also note that because an odd number of thumbnails is included split between the two rows, that one 'td' element is empty to ensure each row has same number of cells.
[[File:File_tab.JPG]]On the screen (extract) shown here, you select solar, uv or sunshine to determine which of the 3 extra graphs, are file transferred (or copied) to your web site. Remember, in practice your station will not support all 3, so you will need to edit the changes shown below to suit your instrumentation.
= Creating or Editing Templates in a Separate Folder =
If you are making anything but minor changes to the template, consider creating your own files with (same or preferably) different names in a separate folder.
== What to select on the 'Files' tab of the '''Internet Settings''' screen within the 'Configuration' menu ==
In this section, the instruction cover both template files (Cumulus has to be asked to 'process' these) and other files (such as images, web pages without cumulus web tags, log files etc) that are to be file transferred or copied multiple times each day.
[[File:Files tab settings.jpg|right]]
=== 'Remote filenames' and 'FTP?' columns for remote servers ===
If your web server is on a remote server, then the instructions for remote files require that file transfer is used:
*Sites/Options tab of the '''Internet''' screen within the 'Configuration' menu.
=== 'Remote filenames' and 'FTP?' columns for local servers ===
If your web server is on the same computer (or local network) as Cumulus, then the instructions for remote files are changed slightly because copying rather than file transfer is used:
*Sites/Options tab of the '''Internet''' screen within the 'Configuration' menu.
= Using PHP Hypertext Pre-processor =
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).
This Wiki article cannot teach you PHP, nor tell you if your web server supports it, but the examples below give a brief hint of how PHP can be used.
== Using PHP 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 want to try PHP, but do not want a big redesign of your set-up.
*The file still contains the HTML shown
*It still contains Cumulus web tags, but as it is no longer a standard page, it has to be listed on the ''Files'' tab of the '''Internet''' screen within the 'Configuration' menu; the remote file name must have the extension ".php" so that the PHP 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 [[Webtags_as_boolean_operators_in_HTML|boolean options]] that can be achieved just with standard HTML. For example, 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". 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>
</tr>
</
== Replacing HTML by PHP ==
#A more efficient approach, this is a bigger implementation change, is to set Cumulus to process just [[Php_webtags| something like this file]] to create PHP variables/arrays from the Cumulus web tags you want 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 shown above, but the table is output by the PHP script:
<pre>
<!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;
</code>
Note that only excerpts from the code are shown. Note the two ways of getting PHP to output 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 allows a space after echo and after <<< but does not allow any other spaces (or tabs) in the two enclosing lines (that precede and follow all the listed output).
| |||
