AnnualDataSummary

Name:	Annual Data Summary
Type:	HTML & Javascript
Author:	David Jamieson
Contact:	DAJ
Last update:	{{{updated}}}
Version:	{{{version}}}

An updated article, that supercedes this one is called Daily_Summary

'Annual Data Summary' is a small tool to read the dayfile.txt produced by Cumulus and summarise this in a table, arranged like a calendar, showing a full years worth of a selected field such as maximum daily temperature.

Requirements

• Web server space (could be on your own local machine or on a commercial server)
• The files you need to load onto the server are listed later
• JavaScript enabled browser (all modern browsers use JavaScript) as the script here uses library routines called 'jQuery'
• Use of Daily option (bottom left) on Sites/Options tab of Internet Settingsscreen (or Cumulus Toolbox) to call command to upload 'dayfile.txt' to your web server (See Cumulus Help for more details)
• Optionally, PHP enabled web server if you wish to use the PHP version
• Ability to edit programming scripts, and look up programming guidance, because you probably will need to do some tailoring for your site

The Source Code

Original Fileset

• The tool uses HTML, jQuery (a library script that produces Javascript) and a CSS file.
• The JavaScript version does not require a webserver with PHP services enabled. (Many of the free hosting services do not offer PHP so this was a solution to that problem).
• The alternative is a PHP version (included so you have the option to use either).
• Both provide identical looking output and functionality, however if you have PHP services on your web server use the PHP version as it is slightly faster.

An working example is here

• Download the following file...AnnualDataSummary.zip
• Unzip the contents (five files will be extracted, but you will only use 3 of them)

Instructions

• Edit the file 'readDayfile.js' or 'readDayfile.php' depending on your choice in a good text editor (for example, notepad++) and consider the variables in the top section of the script.

These are the configuration variables described below. If you need to adjust any of these settings, edit the appropriate file.

• Copy the necessary files to your web site into a subfolder, or the root -- your choice

if using the PHP version copy datasummary.php and readDayfile.php

for the JavaScript version copy datasummary.html and readDayfile.js

• Copy datasummary.css
• Open datasummary.html or datasummary.php from your website in a browser

Configuration Variables

by default, the script (the file 'readDayfile.js' or 'readDayfile.php' depending on your choice) will do the following:

• (both versions) Assume the dayfile.txt is read from a subfolder called 'data'.
• (JS version only) Insert the table it generates into a HTML element with attribute id='tableData'
• (both versions) Assume the date format in the dayfile is dd/mm/yy (the month is always in the middle for all Cumulus log files)
• (both versions) Assume the data in the dayfile is separated with a comma

The last two assumptions are fine for UK based systems, however others should check their dayfile.txt and adjust as necessary

• Look for the line 'dayfile='/data/dayfile.txt';' around line 15 and change this to point to your dayfile.txt on your webserver.

for PHP version the path should start from the / (root),

for JavaScript version the path should start from where the HTML will be stored.

• (JS Version only) tableDiv - the HTML element id attribute on your webpage to insert the table into
• (both versions) field_delimiter - the symbol separating each of your fields in the dayfile.txt. For most people this is a comma but (if you use comma to separate integer and decimal parts of real numbers) it could be a semi-colon (;) or other symbol.
• (both versions) date_delimiter - the symbol separating your date format. See setup.

Change as needed, save and test

Usage

Along the top will be a menu of the (in original version) six data sets available and on the top left of the table is the year currently being shown. Change either the year, or click one of the top buttons to change the data set. Depending on the speed of your internet connection, and your browser, the new web page may take a few seconds to be processed as it involves: re-reading the dayfile.txt file, redrawing the table, and inserting the values.

If you mouse over a particular value, it will be highlighted together with the corresponding day (row heading) and month (column heading). The highlighting functionality varies a bit between versions (see possible problems below).

What is shown, and how, in the cells at the intersection of the day and month headings, depends on the version you choose to install.

Opening a specific data set when the page is first loaded

By default (in the original version) the table created will show the available daily values of the maximum temperature for the current local calendar year (see possible problems below), however you can start with any data set and any year (assuming you have those values in the dayfile.txt) by adding a 'Query String' to the end of your URL in the browser.

• The parameter 'data' (in the original version) takes mintemp, maxtemp, avgtemp, minmaxt, rainfall, windgust. (You can add further data sets or change the language of these values - see Localization). Note the specified data will be displayed even if it is assigned 'false' and does not appear as a button.
• You can supply both data set and year parameters, one only, or none

examples....,

• JS version -- myserver.com/datasummary.html?year=2010
• PHP version -- myserver.com/datasummary.php?year=2010

This will open the default (maximum temperature) data set but initially showing year 2010

• JS version -- myserver.com/datasummary.html?data=rainfall&year=2009

This will open the rainfall data set for the year 2009.

Processing

If you select the pure Javascript original solution downloaded from this section, it means the page viewer's browser is doing all the work. The complete dayfile.txt is reloaded each time you select a dataset, and your browser then filters and processes the required subset of values from it. A table is then constructed by the script at the point indicated by the HTML DIV called 'tableData', and the values are then inserted.

If you select one of the various PHP versions available from this page or the forum links above, the source server does all the work of constructing the HTML page and sends the result to the viewer's browser.

Customisation

Understanding the Basics

The original 'tool' relies on three files for successful operation:

1. the jQuery library routines that allow it to work in any user agent (browser)
2. datasummary.css (the style sheet) and
3. either readDayfile.js (the JavaScript) or readDayfile.php (the PHP version of the script).

Please note that the table needs a good amount of space to show a full year of data (at least 900 pixels unless you start reducing the font size!)

In addition you need a carrier page to show the data. You can either use the page provided in the zip (datasummary.html or datasummary.php), or create your own page including:

• for both JS and PHP versions you need the script library and styling:

In the <head> section.....

<link rel="stylesheet" type="text/css" media="screen" href="datasummary.css"  /> 
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.1/jquery.js" type="text/javascript">

This loads the stylesheet; loads a jQuery library from Google servers rather than having the file on your server, (note many versions of jQuery are not supported by old versions of Internet Explorer, use the very old version '1.5' used by DAJ instead of the current version '3.1' if you need to);

Next you must load the script to build the table:

• for the JS version

In the <body> section, where you want the table to appear, declare the element

<section id="tableDiv">
<noscript>Your browser has not enabled the JavaScript necessary to display the table here<noscript>
&lt/section>

In the <body> section, near the end, call the script:

<script src="readDayfile.js" type="text/javascript"></script>

Once the page is loaded it runs readDayfile.js, that will look for your HTML element with an id attribute called 'tableData'; then will insert the data table within it.

Other code can be inserted inbetween such as anchor links to your other pages.

• for the PHP version

In the <body> section, use the code

<?php include('readDayfile.php');?>

to include the script that creates all the HTML elements required

Localization / Language

The script has been designed to be easily translated to your language of choice.

As in Instructions above, edit the readDayfile.js / .php

• variable mn is a list of the 12 months of the year, in an abbreviated format. You may change these as necessary, but try to keep it to an abbreviation as there is limited space.
• 'label_items' is a list of all possible data sets to be displayed. Again you can change these to suit if you are prepared to wade through all the script and make changes elsewhere too. However, the format is a little more involved and you should take some care. Each row represents one data set, with 4 columns of settings for that data set; so the default list is an array of four by six.

Example of a row,....

['maxtemp','Max Temp','Maximum Temperature',true]

• The first element, in this case 'maxtemp' -- is a system variable to identify the data set, used for the URL parameter option, used by the Switch coding (so any change here needs to be reflected there), and also tested elsewhere in the code (in the Rainfall and Windgust data sets a particular style is applied to their zero values).

However, if you add a new data set, then your new first element should be a unique identifier.

• Second, Max Temp is the text to be displayed in the button at the top of the table. You may change this to your own language

If you add a new data set, remember to consider how many buttons can be fitted across the top of the table, you may wish to split into multiple rows.

• Third, Maximum Temperature is the text shown at the top of the table to describe the current data set; again you may change this
• Finally, 'true' will display this button at the top; 'false' will hide it. Therefore, if you do not wish to allow users to jump to the 'Rainfall data set' change the 'true' to 'false' in the 'rainfall' element of the variable. (true/false MUST be lowercase)

NOTE: Sfws 12:22, 31 December 2012 (UTC)

Having made any change to the array as DAJ says above, you also need to change what is in a switch section below where DAJ says '// Nothing to edit below here'.

The switch ($whatdata) { ... } part of the coding identifies the columns in dayfile.txt for the values to be displayed. Any change you make in the array, needs a corresponding change within this part of the script. A typical case here reads

case 'mintemp'	: $tablelayout .= $label_items[1][2]; $dayfilecol=4; break;

so to add a new one, copy that line and paste it in again but in this new line replace 'mintemp' with whatever you have added as the first element in your new array row, replace '[1]' with square brackets round the number of your new array row (the first row is number zero) and finally replace '4' with the field number where the parameter you have added is found in dayfile.txt.

Styling

The table styling is completely configurable using the included datasummary.css Stylesheet. By default it is using similar colours to the standard Cumulus website. Below are a few of the key entries to consider when adjusting settings (typically colouring)... Also see support forum thread about colouring with php

In the 'datasummary.css' file:

CSS Element	Description
#table_container .highlight	Used to highlight the mouse position within the table, and also the row and column header of the data cell.
#table_container .smallfont	Adjusting the font size to something smaller when showing both Max & Min temp on one data cell
#table_container .zerovalue	In the Rainfall and Windgust data sets this style is applied to any values of 0. By default, the colour is set to a lighter grey but you could add 'display:none;' to hide zero values completely
#table_container table th	Colouring for the top header (Month names) and left header (day numbers)
#table_container table td,table th	The width of each data cell in the table. Be careful adjusting this as making it too small will stop the data being displayed completely
#table_menu li	The styling for the buttons at the top of the page (those for changing the data set)
#table_container	Set the overall font size and style used in the table, as well as the text colour; table positioning and maximum width

Possible problems

• Version 1.1 has been tested and runs on IE 7, IE 8, IE 9, FireFox 3 to 14, IceDragon, Chrome/Dragon/SRWare Iron, and Safari -- running on the non IE browsers for both Windows and the Mac.
• IE7 is notoriously slow for Javascript processing so there will be a longer delay as you change the data set (a few more seconds in some cases)
• Non-standard attributes 'datacol' and 'datarow' are generated by the original javascript and php routines that will not pass validation against standards (in HTML5 these can be made to validate by changing to 'data-col' and 'data-row').
• In version 1.1 of this tool, jQuery version 1.5 is called, this permitted use of '.attr' object to add/remove the highlight; from jQuery version 1.6 that was deprecated and the '.prop' object is now specified for the same purpose.
• Version 1.0 and 1.1 default to showing a table for viewer's local current calendar year. Remember the dayfile.txt (even if updated each day) only contains records up to the day ending at the last rollover time using the timezone local to the weather station. Timezone differences when combined with rollover time variations can lead to a period of 2 days discrepancy. At New Year a blank table will be displayed during this period by default. For example, 30 or 31 (depending on whether rollover has occured) in December of the last year could be the latest available for a site in USA whilst the original version of the code is showing a blank table of the next year during early morning on 2 January in Austrailia. Even when station and viewer are in same timezone, there will be a blank table until the first rollover on 2 January.
• The final field on each row is not read correctly, because the row break has been specified wrongly for a Microsoft Windows environment, it should quote fdata.split("\r\n"); i.e. defines that carriage return then line feed (newline) used to split daily observations in dayfile. Because the script presented here only processes a small number of fields from earlier in the row, this error does not affect the output for the published code.

Version Control

1.1 PHP version included with JavaScript version in new download package

1.0 Public launch (JavaScript only, no longer available for download)

Login and click 'Watch' at the top of this page to be automatically notified if there are updates