Description
-----------

The high level goal of the three modules in this package is to enhance 
existing time tracking/reporting capabilities in Mantis.

The package contains 3 modules:
- bug_report_timed
- time_tracking
- time_tracking_weekly

'bug_report_timed' module
=========================

Simple issue submission module, capabale of setting initial time tracking
value and issue status.

Properties:
- Based on simple view of standard Mantis issue report site
- Allows for initial setting of 'severity', 'priority' and 'status' fields 
- Capable of defining issue submission date (e.g. earlier date). This date will
  also be assigned to the initial time tracking note
- Access priviledges required: time tracking priviledges


'time_tracking' module
======================

Time tracking report module. Time tracking reports are show summary time
tracking times added in notes and status changes. The summaries are 
limited using dates and shown with respect to categoty, status, project, etc.

Properties:
- Built upon Mantis billing module
- A report is presented as a general table that can be filtered and sorted
  in order to obtain detailed report types
- Filtering is performed using edit-boxes in the table header. 'Enter' submits.
- Double-click on column's header activates sorting.
- Standard Mantis filter load/choose/save component is present. This way a set of
  standard reports can be obtained.
- The table can be exported to Excel CSV file. The time tracking column is exported
  in minutes.
- Global project-switch drop-down box affects the report 
- Access priviledges required: developer+. Administrator has a global view on all
  projects and issues. Manager sees all the issues in his projects. Developers
  can view only the issues they contributed to.


'time_tracking_weekly' module
=============================

Per week time tracking and time submitting report module. 

Properties:
- Built upon Mantis billing module
- The report includes only the issues submitted in the defined time span, that are 
  not closed
- Report table can be sorted and filtered
- Global project-switch drop-down box affects the report 
- Data is shown for a given week
- The report shows the summary work times of a given user on a given issue in a 
  given day
- A user can add additional time tracking values using provided edit-boxes. 
  'Enter' submits. Corresponding notes with time tracking information are added.
  The note text is left empty to prevent Mantis from sending e-mails.
- No time tracking additions are allowed for days before issue submission date
  and after the current date
- A user is allowed to increase on his time tracking values.
- Administrator sees everything. Manager sees everything in his projects. 
  Developer can view only his work.


Installation
------------

Installation of this package generally boils down to copying the included files
into Mantis root dir, and plugging the modules into Mantis main menu.

Installation procedure:

1. Ensure that main Mantis config file 'config_inc.php' enables time 
   tracking: '$g_time_tracking_enabled = ON;'.

2. Copy all the files in the package to Mantis installation directory (e.g. C:\Mantis).
  No overwrite prompts should occur.

3. Insert the following code into 'html_api.php' (<mantis>\core\html_api.php) file. 
  The code should be added to 'print_menu' function (e.g. just after line 
  containing '# Add custom options').

	# Add bug_report_timed
	$t_custom_options = prepare_custom_menu_options( 'main_menu_custom_options' );
	$t_menu_options = array_merge( $t_menu_options, $t_custom_options );
	if ( config_get('time_tracking_enabled') && access_has_project_level( config_get( 'time_tracking_edit_threshold' ) ) )
	$t_menu_options[] = '<a href="bug_report_timed_page.php">' . lang_get( 'bug_report_timed_link' ) . '</a>';
	
	# Add time_tracking report
	$t_custom_options = prepare_custom_menu_options( 'main_menu_custom_options' );
	$t_menu_options = array_merge( $t_menu_options, $t_custom_options );
	if ( config_get('time_tracking_enabled') )
	$t_menu_options[] = '<a href="time_tracking_page.php">' . lang_get( 'time_tracking_link' ) . '</a>';
					
	# Add billing_weekly
	$t_custom_options = prepare_custom_menu_options( 'main_menu_custom_options' );
	$t_menu_options = array_merge( $t_menu_options, $t_custom_options );
	if ( config_get('time_tracking_enabled') && access_has_project_level( config_get( 'time_tracking_edit_threshold' ) ) )
	$t_menu_options[] = '<a href="time_tracking_weekly_page.php">' . lang_get( 'bug_report_weekly_link' ) . '</a>';

4. Append the following definitions to chosen localisation language files in the 'lang' directory.
  For example, add the following php code to '<mantis>\lang\strings_english.txt':

	$s_time_tracking_link = 'Time Tracking';
	$s_bug_report_timed_link = 'Report Timed Issue';
	$s_bug_report_weekly_link = 'Week Report';
	$s_issue_created = 'Issue created';
	$s_mon = 'Mon';
	$s_tue = 'Tue';
	$s_wed = 'Wed';
	$s_thu = 'Thu';
	$s_fri = 'Fri';
	$s_sat = 'Sat';
	$s_sun = 'Sun';
	$s_time_added = 'Work added.';

5. The installation should be completed by now. Three new links should be visible in the
  main menu.


Final remarks
-------------

Some of the most important principles, decisions and summaries of this first version,
that will probably be important to future developers of these modules are:

- The files included are free/open source. The Mantis license applies. All modifications
  are highly encouraged.
- Tested on: Mantis 1.1.2, MySql. Seems to be compatible with Firefox as well as with IE.
- One of the goals was not to modify the Mantis codebase itself. This resulted
  in some duplicated code.
- Mantis API was not modified. Database schema was not modified.
- Sorting, filtering, and paging of reports is done on client side using java script.
  This obviously prevents the reports from scaling up well.
- Standard Mantis API was used where possible. 'time_tracking_weekly' module contains
  one bare sql query that wasn't tested with databased other than mySql (it does seem to
  be pretty standard though).
- Advised coding conventions were probably violated mulitple times
- If this code is to be included someday in the Mantis codebase, it will probably need a close
  review, refactoring and testing.