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

Lire cette page en français.

About

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

Dependencies

RapportHamster++ requires a version of Hamster using the new HTML report structure. 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, install the package php5-cli (tested in Ubuntu).

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.

• Download the archive of the latest version.

• Extract the archive.

• Open a terminal in the extracted folder.

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

  php index.cli.php "/path/to/the/report.html" 1 1 1 1 1 "h" "min" 0
  

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

The folder exemple contains two files:

• Gestion du temps, 2010-07-30 - 2010-08-05.html: a report created by Hamster;

• Gestion du temps, 2010-07-30 - 2010-08-05 - 2.html: the same report, but modified by RapportHamster++.

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.

Development

Last version: 1.0.1 (2012-05-22)

Git is used for revision control. Repository can be browsed online or cloned.

RapportHamster++ has an issue tracker, on which bug reports and feature requests can be submitted.

License

Author: Jean-Philippe Fleury contact@jpfleury.net
Copyright © 2010-2012 Jean-Philippe Fleury

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

Third-party code

• PHP Markdown: under the BSD-style license.