Revision as of 21:02, 13 April 2018

Name:	Annual Data Summary
Type:	HTML & Javascript
Author:	David Jamieson
Contact:	DAJ
Last update:	17 December 2012
Version:	1.2 BCJKiwi

'Annual Data Summary' is a small tool to read the dayfile.txt produced by Cumulus and summarise this in a table showing a full years worth of data. This tool uses standard HTML and Javascript so 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). However, a PHP version is included so you have the option to use either. Both provide identical data 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

Requirements

webserver space
Cumulus Dayfile.txt file uploaded to the webserver
Javascript enabled browser (all modern browsers use Javascript)
optionally, a tool to automate the uploading of dayfile.txt to your webserver once per day. Example, CumulusToolbox
optionally, PHP enabled web server if you wish to use the PHP version

The Basics

Here is a revised set of files (PHP only) ver 1.2 These are available here and update the Ver 1.1 fileset below to eliminate errors in validation due to deprecated code routines. They also include a couple of updates from DAJ advised by posts in the Forum. The files include additional notes and explanations on the changes where relevant. A working example is here

download the follwing file...AnnualDataSummary_12.zip
Follow the instructions below for the PHP version.

Original Fileset and instructions:-

download the following file...AnnualDataSummary.zip
Unzip the contents (five files will be extracted)
Edit the file 'readDayfile' file in a a good text editor (for example, notepad++). Edit the .js version or the .php depending on your choice
Look for the line 'dayfile='/data/dayfile.txt';' around line 15 and change this to point to your dayfile.txt on your webserver. This path should start from the / (root)
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 readDafyfile.js

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

Usage

Along the top will be a menu of the 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 dataset. Depending on the speed of your internet connection, and your browser, the data may take a few seconds to be processed.

If you select the pure Javascript solution available here, it means the page viewer's browser is doing all the work. The complete dayfile.txt is loaded each time you select a dataset, and your PC then filters and processes it. An alternative Javascript/jQuery solution that only reads the dayfile.txt once, however many times you choose a different data set or a different year is in the 3rd party tools forum. That alternative is thus considerably faster, especially with large dayfile.txt files.

This is in contrast to a PHP solution also available here, where the source server does all the work and only sends the results to the viewer's browser.

Possible problems

This has been tested and runs on IE 7, IE 8, IE9, FireFox 3 to 14, 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)

Customisation

Understanding the Basics

The 'tool' relies on two files for successful operation.... datasummary.css (the style sheet) and readDayfile.js (the Javascript) or readDayfile.php (the PHP version). The third file, datasummary.html/php, is simply a carrier page to show the data.

If you wish to use your own page to show the data on, do the following:

for the JS version

In the <HEAD> section.....

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

This loads the stylesheet; loads a jQuery library from Google servers (rather than having the file on your server); and loads the Javascript to build the table

Once the page is loaded it runs readDayfile.js and will look for a DIV called 'tableData'; inserting the data table within it. You can change the DIV it inserts into (see later in this article).

for the PHP version

use the code

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

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!)

Configuration Variables

by default, the script will do the following:

Insert it's contents into a DIV called 'tableData' (JS version only)
Assumes the date format in the dayfile is dd/mm/yy
Assumes the data in the dayfile is separated with a comma

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

If you need to adjust any of these settings, edit the readDayfile.js file and consider the variables in the top section of the script:

tableDiv - the name of the DIV on your webpage to insert the table into (JS Version only)
field_delimiter - the symbol separating each of your fields in the dayfile.txt. For most people this is a comma but may also be a period (.)
date_delimiter - the symbol separating your date format. In the UK this is / however in other countires it may be -

Change as needed, save and test

Localization / Language

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

As 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. However, the format is a little more involved and you should take some care. Example,....

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

The first element, in this case 'maxtemp' -- must remain unchanged, this is a system variable to identify the dataset and tested elsewhere in the code
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
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 dataset' change the 'true' to 'false' in the 'rainfall' element of the variable. (true/false MUST be lowercase)

Opening a specific data set

By default the table will summaries the maximum temperature for the current year, however you can start with any dataset or year (assuming you have the data in the dayfile.txt) but adding a string to the end of your URL in the browser. examples....,

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

This will open the data set initially showing year 2010

myserver.com/datasummary.html?data=rainfall&year=2009

This will open the rainfall dataset for the year 2009.

The parameter 'data' takes mintemp, maxtemp, avgtemp, minmaxt, rainfall, windgust. You can supply both parameters, one only, or none

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

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 datasets this style is applied to any values of 0. By default, the colour is set to a lighter grey but you could add 'dispaly: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

Version Control

1.1 PHP version included

1.0 Public launch

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

AnnualDataSummary: Difference between revisions

Revision as of 21:02, 13 April 2018

Contents

Requirements

The Basics

Usage

Possible problems

Customisation

Understanding the Basics

Configuration Variables

Localization / Language

Opening a specific data set

Styling

Version Control

Navigation menu

Page actions

Page actions

Personal tools

Wiki navigation

Search

Cumulus

Tools

@@ Line 1: / Line 1: @@
 {{AddOnBanner|name=Annual Data Summary|type=HTML & Javascript|author=David Jamieson|contact=[[User:Daj|DAJ]]|updated=7 March 2011|version=1.1|updated=17 December 2012|version=1.2 BCJKiwi}}
-'Annual Data Summary' is a small tool to read the [[dayfile.txt]] produced by Cumulus and summarise this in a table showing a full years worth of data.
+'Annual Data Summary' is a small tool to read the [[dayfile.txt]] produced by Cumulus and summarise this in a table showing a full years worth of data. This tool uses standard HTML and Javascript so 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).  However, a PHP version is included so you have the option to use either.  Both provide identical data and functionality, however if you have PHP services on your web server use the PHP version as it is slightly faster.
-*The tool uses HTML and jQuery (a language that produces Javascript) and includes 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 [http://www.grantownweather.co.uk/historic/dataSummary.php here]
@@ Line 11: / Line 7: @@
 = Requirements  =
-*webserver space (unless you are using this tool on your own local machine)
+*webserver space
-*Cumulus [[Dayfile.txt]] file uploaded to the webserver (for this tool, the default location is a subfolder called 'data')
+*Cumulus [[Dayfile.txt]] file uploaded to the webserver
 *Javascript enabled browser (all modern browsers use Javascript)
-*optionally, a tool to automate the uploading of dayfile.txt to your webserver once per day after rollover.  Example, [[CumulusToolbox]]
+*optionally, a tool to automate the uploading of dayfile.txt to your webserver once per day.  Example, [[CumulusToolbox]]
 *optionally, PHP enabled web server if you wish to use the PHP version
-= The Source Code  =
+= The Basics  =
+Here is a revised set of files (PHP only) ver 1.2
-== Revised PHP ==
+These are available here and update the Ver 1.1 fileset below to eliminate errors in validation due to deprecated code routines.
-Here is a revised set of files (PHP only) ver 1.2.
+They also include a couple of updates from DAJ advised by posts in the Forum.
+The files include additional notes and explanations on the changes where relevant.
-These are available here and update the Ver 1.1 fileset below to eliminate errors in validation due to non-standard or deprecated code routines.
+A working example is [http://silveracorn.co.nz/weather/datasummary.php here]
-They also include a couple of updates from DAJ version as advised by posts in the Forum.
+*download the follwing file...[http://wiki.sandaysoft.com/files/AnnualDataSummary_12.zip AnnualDataSummary_12.zip]
-The files include additional notes, and explanations on the changes, where relevant.
-*A working example is [http://silveracorn.co.nz/weather/datasummary.php here]
-*Download the following file...[http://wiki.sandaysoft.com/files/AnnualDataSummary_12.zip AnnualDataSummary_12.zip]
 *Follow the instructions below for the PHP version.
+Original Fileset and instructions:-
-== Alternative JavaScript ==
-[[User:Sfws|Sfws]] 12:15, 31 December 2012 (UTC)
-*An [http://sandaysoft.com/forum/viewtopic.php?f=18&t=8690 alternative Javascript/jQuery solution] is in the 3rd party tools forum.
-*Like the revised PHP version above, the alternative JavaScript version works correctly at the start of a new year (for the forum version the ''default year reflects the latest year on the dayfile.txt'', not (as the original version uses) the current calendar year in the viewer's time zone).
-*Also like the revised PHP version, the alternative JavaScript version will pass validation, as all the coding is to the latest standards (ECMA-292, CSS3, HTML5).  The original PHP and JS versions below, use non-standard attributes to handle for example the highlighting facility.
-*Unlike the original version below, the alternative JavaScript version only reads the '''dayfile.txt''' ''once'', however many times you choose a different data set (called category in the forum) or a different year.  It also ''avoids redrawing the table if the year is changed''. So the alternative is thus considerably faster, especially with large dayfile.txt files (and changes of data set or year).
-*For ease of customisation, the forum version uses a different sequence in ''''label_items'''', and includes the ability to apply your own formatting according to value for any selected dataset.  The forum example includes colour rainfall rate according to intensity groups used by UK Meteorological Office.
-*If you select the new version, it includes a CSS, but you may want to combine that with your existing CSS to make the new page match your existing pages.  It includes HTML, but again that will need tailoring to match your other pages, but the HTML in the forum does offer the ability to display the raw dayfile.txt if JavaScript is not enabled in the viewer's browser.
+*download the following file...[http://wiki.sandaysoft.com/files/AnnualDataSummary.zip AnnualDataSummary.zip]
-== Original Fileset ==
-*Download the following file...[http://wiki.sandaysoft.com/files/AnnualDataSummary.zip AnnualDataSummary.zip]
 *Unzip the contents (five files will be extracted)
+*Edit the file 'readDayfile' file in a a good text editor (for example, [http://notepad-plus-plus.org/ notepad++]). Edit the .js version or the .php depending on your choice
+*Look for the line 'dayfile='/data/dayfile.txt';' around line 15 and change this to point to your dayfile.txt on your webserver. This path should start from the / (root)
-== Instructions ==
-*Edit the file 'readDayfile.js' or 'readDayfile.php' depending on your choice in a good text editor (for example, [http://notepad-plus-plus.org/ 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.
-<br>
 *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''
+: if using the PHP version copy datasummary.php and readDayfile.php
-: for the JavaScript version copy '''datasummary.html''' and '''readDayfile.js'''
+: for the Javascript version copy datasummary.html and readDafyfile.js
-*Copy ''datasummary.css''
+*Copy datasummary.css
-* Open '''datasummary.html''' or ''datasummary.php'' from your website in a browser
+* 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''
-*   (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 may also be a period ('''.''').
-* (both versions) '''date_delimiter''' - the symbol separating your date format. In the UK this is '''/''' however in other countires it may be '''-'''
-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.
+Along the top will be a menu of the 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 dataset. Depending on the speed of your internet connection, and your browser, the data may take a few seconds to be processed.
-If you mouse over a particular value, it will be highlighted together with the corresponding day (row heading) and month (column heading).
+If you select the pure Javascript solution available here, it means the page viewer's browser is doing all the work. The complete dayfile.txt is loaded each time you select a dataset, and your PC then filters and processes it.  An [http://sandaysoft.com/forum/viewtopic.php?f=18&t=8690 alternative Javascript/jQuery solution] that only reads the dayfile.txt once, however many times you choose a different data set or a different year is in the 3rd party tools forum. That alternative is thus considerably faster, especially with large dayfile.txt files.
-Some data sets show minimum and maximum values in the cells at the intersection of the day and month headings, most just show a single value at the intersection.
+This is in contrast to a PHP solution also available here, where the source server does all the work and only sends the results to the viewer's browser.
+= Possible problems  =
+*This has been tested and runs on IE 7, IE 8, IE9, FireFox 3 to 14, Chrome/Dragon/SRWare Iron, and Safari -- running on the non IE browsers for both Windows and the Mac.
-== Opening a specific data set when the page is first loaded ==
+*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)
-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 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)
-*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&amp;year=2009
-:This will open the rainfall data set for the year 2009.
-== Processing ==
-If you select the pure Javascript solution available here, 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 PC 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 the PHP solution available here, 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 'tool' relies on two files for successful operation.... datasummary.css (the style sheet) and either readDayfile.js (the JavaScript) or readDayfile.php (the PHP version). The third file, datasummary.html/php, is simply a carrier page to show the data.
+The 'tool' relies on two files for successful operation.... datasummary.css (the style sheet) and readDayfile.js (the Javascript) or readDayfile.php (the PHP version). The third file, datasummary.html/php, is simply a carrier page to show the data.
 If you wish to use your own page to show the data on, do the following:
@@ Line 117: / Line 63: @@
 *for the PHP version
-:you still need the jQuery library as above
 :use the code <pre><?php include('readDayfile.php');?></pre>
 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!)
+<br>
+== Configuration Variables  ==
+by default, the script will do the following:
+*Insert it's contents into a DIV called 'tableData'  (JS version only)
+*Assumes the date format in the dayfile is dd/mm/yy
+*Assumes the data in the dayfile is separated with a comma
+The last two assumptions are fine for UK based systems, however others should check the dayfile.txt and adjust as necessary
+If you need to adjust any of these settings, edit the readDayfile.js file and consider the variables in the top section of the script:
+*'''tableDiv''' - the name of the DIV on your webpage to insert the table into  (JS Version only)
+*'''field_delimiter''' - the symbol separating each of your fields in the dayfile.txt. For most people this is a comma but may also be a period (.)
+*'''date_delimiter''' - the symbol separating your date format. In the UK this is / however in other countires it may be -
+Change as needed, save and test
 == Localization / Language  ==
@@ Line 127: / Line 91: @@
 The script has been designed to be easily translated to your language of choice.
-As in '''Instructions''' above, edit the readDayfile.js / .php
+As 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. 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.
+*''''label_items'''' is a list of all possible data sets to be displayed. Again you can change these to suit. However, the format is a little more involved and you should take some care. Example,....
-Example of a row,....
 <pre>['maxtemp','Max Temp','Maximum Temperature',true]</pre>
-*The first element, in this case 'maxtemp' -- is a system variable to identify the data set, used for the URL parameter option, and tested elsewhere in the code (in the Rainfall and Windgust data sets a particular style is applied to any zero values, so their system variables should not be changed just in this list).
+*The first element, in this case 'maxtemp' -- must remain '''unchanged''', this is a system variable to identify the dataset and tested elsewhere in the code
-However, if you add a new dataset, 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 dataset, 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)
+*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 dataset' change the 'true' to 'false' in the 'rainfall' element of the variable. (true/false MUST be lowercase)
 <br>
+== Opening a specific data set  ==
+By default the table will summaries the maximum temperature for the current year, however you can start with any dataset or year (assuming you have the data in the dayfile.txt) but adding a string to the end of your URL in the browser. examples....,
+*JS version --myserver.com/datasummary.html?year=2010
+*PHP version -- myserver.com/datasummary.php?year=2010
+:This will open the data set initially showing year 2010
+*myserver.com/datasummary.html?data=rainfall&amp;year=2009
+:This will open the rainfall dataset for the year 2009.
+The parameter 'data' takes mintemp, maxtemp, avgtemp, minmaxt, rainfall, windgust. You can supply both parameters, one only, or none
 == Styling  ==
@@ Line 163: / Line 135: @@
 |-
 | #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
+| In the Rainfall and Windgust datasets this style is applied to any values of 0.  By default, the colour is set to a lighter grey but you could add 'dispaly:none;' to hide zero values completely
 |-
 | #table_container table th
@@ Line 177: / Line 149: @@
 | Set the overall font size and style used in the table, as well as the text colour; table positioning and maximum width
 |}
-<br>
-= Possible problems  =
-*Version 1.1 has been tested and runs on IE 7, IE 8, IE 9, FireFox 3 to 14, 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)
-*The original version defaults to current local calendar year, but the dayfile.txt only contains records up to the last rollover time (using the timezone local to the weather station).  So at new year there can be a period of up to 2 days when the default year is ''not'' available to be displayed (depending on timezone differences and rollover time).
-*Non-standard attributes are generated by this routine that will not pass validation against standards.