RapportHamster++, a tool to customize Hamster's HTML report

[Jean-Philippe Fleury <contact jpfleury net>]

Hi,

I want to present you RapportHamster++, a script that I wrote to
customize Hamster's HTML reports. Here's a little description:

----

RapportHamster++ (literally "HamsterReport++" in French) is a set of PHP
functions to customize HTML reports created by the [Gnome Time Tracker
Hamster](http://projecthamster.wordpress.com/). The parsing and the
modification of HTML reports are mainly performed with DOM PHP extension.

## Prerequisites

- RapportHamster++ requires a version of Hamster using [the new HTML
report
structure](http://projecthamster.wordpress.com/2010/06/06/custom-html-reports/).
Version 2.31.6 uses this new structure. It is possible that this is also
the case of an earlier version.

- It also requires of course a PHP interpreter, on a web server or in
command line (PHP CLI). To use PHP in command line in Ubuntu, install
the package `php5-cli`.

- To get a copy of the code of RapportHamster++ using Bazaar in Ubuntu,
install the package `bzr`.

## Installation

There is no installation needed. An index file is available by default
to show the possible uses with PHP CLI of the different functions.

Example in a console in GNU/Linux:

1. Get a copy of the code of RapportHamster++ using Bazaar:

		bzr branch lp:rapporthamster++

2. Go to the newly created directory:

		cd rapporthamster++

3. Run the index script (the parameters are there for example):

		php ./index.cli.php "/path/to/the/report.html" o o o o o 0

	The modified report will be saved in the same directory as the original
report, for example `/path/to/the/report - 2.html`.

For more details about the parameters and the functions, analyze the
file `index.cli.php` with a text editor and read the comments of each
function in the file `inc/fonctions.inc.php`. See also the feature
overview below.

## Feature Overview

The file `index.cli.php` is delivered by default to show a possible use
of the functions of RapportHamster++. These functions are:

- `ajouteClassesLignesTable()`: adds CSS classes to the rows of a given
table. The visible result is a background color for even rows;

- `ajouteDureeTotale()`: adds the total duration of all activities in
the report;

- `colonneMarkdownVersHtml()`: converts the text of a column from
Markdown syntax to HTML. Useful to write descriptions in Markdown. For
example:

		Lorem *ipsum* dolor **sit** amet, `consectetuer` adipiscing
[elit](dictum).

	becomes:

		<p>Lorem <em>ipsum</em> dolor <strong>sit</strong> amet,
<code>consectetuer</code> adipiscing <a href="dictum">elit</a>.</p>

- `dateSansZeroInitial()`: removes all the leading zeros (0) in the
dates appearing in the report. For example:

		May 08, 2010

	becomes:

		May 8, 2010

	Another example:

		Activity log for May 01 – 07, 2010

	becomes:

		Activity log for May 1 – 7, 2010

- `dureeFormatHamsterVersMinutes()`: converts duration in minutes. For
example, for the duration `8h 15min`, the return is `495`;

- `fusionneActivites()`: merges the activities of the table "Activity
Log" (second tab) of the report. The columns "Start" and "End" are removed.

	The merge looks for similar activities (same day, activity, category
and tags) whose description uses a special syntax to link activities
between them. Say the following five activities:

	- description of the activity 1 (1h 35min): [1] Start of the activity.
Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
	
	- description of the activity 2 (20min): [1]
	
	- description of the activity 3 (2h 15min): [1] Class aptent tacit
sociosqu ad torquent per conubia nostra Litor, per inceptos himenaeos.
	
	- description of the activity 4 (1h 10min): [1]
	
	- description of the activity 5 (2h 50min): [1] End of the activity.
Praesenta tempus, odio ac sagittae vehicle; pede tincidunt mauris lacus,
euismod orci in mauris quam has.

	These five activities, if they have the same date, activity, category
and tags, are linked by the number in brackets located at the beginning
of each description, and will be merged. The total duration of the
activity is the sum of all activities (8h 10min in this example) and the
resulting description will contain if necessary the description of each
activity:

		[1] Start of the activity. Lorem ipsum dolor sit amet, consectetuer
adipiscing elit.
		
		Class aptent tacit sociosqu ad torquent per conubia nostra Litor, per
inceptos himenaeos.
		
		End of the activity. Praesenta tempus, odio ac sagittae vehicle; pede
tincidunt mauris lacus, euismod orci in mauris quam has.

- `minutesVersDureeFormatHamster()`: converts the number of minutes in
duration displayed by Hamster. For example, for `495`, the duration
returned is `8h 15min`;

- `supprimeColonnes()`: removes the given columns in the given table;

- `supprimeJquery()`: removes jQuery from the report. Useful when some
tables are removed and only one is left;

- `supprimeTables()`: removes the given tables. A table corresponds to a
tab at the top of the report.

- `unitesDureeFormatHamster()`: finds units used in the default report
for hours and minutes. For example, returns `array ('h', 'min')` for a
report in English.

## Website

See <https://launchpad.net/rapporthamster++>.

## License

### RapportHamster++

Author: [Jean-Philippe Fleury](http://www.jpfleury.net/contact)
Copyright © Jean-Philippe Fleury, 2010.

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.

### Included scripts

- [PHP Markdown](http://michelf.com/projets/php-markdown/): under the
BSD-style license.

----

Regards,

Jean-Philippe