/***
|Name|TaskTimerPlugin|
|Source|http://www.TiddlyTools.com/#TaskTimerPlugin|
|Documentation|http://www.TiddlyTools.com/#TaskTimerPluginInfo|
|Version|1.4.1|
|Author|Eric Shulman|
|License|http://www.TiddlyTools.com/#LegalStatements|
|~CoreVersion|2.1|
|Type|documentation|
|Description|documentation for TaskTimerPlugin|
Quickly generate 'timed task' logs that can be used for status reports, billing purposes, etc.  
!!!!!Usage
<<<
{{{
<<taskTimer TiddlerName "output format" "prompt text" "default description">>
}}}
creates a 'stopwatch' button that, when pressed, displays the elapsed time (in seconds).  Pressing the button again stops the timer, and prompts for a 'target tiddler' (default: [[ActivityReport]] and a 'task description' and writes the description, starttime, endtime, and elapsed time into the indicated tiddler's content.

''~TiddlerName'' //or// ''ask'' //or// ''here'' //or// ''today'' //or// ''"""today:YYYY0MM0DD"""''
>If you omit the ''~TiddlerName'' parameter or use the keyword, ''here'', the output is inserted into the current tiddler.  If you use the keyword, ''ask'', then you will be prompted for a ~TiddlerName each time you press the button to stop the timer.  If you use the keyword, ''today'', then the current date is used as the ~TiddlerName.  You can specify any date format you like by appending it to the "today:" keyword.  If the format is omitted, the format will match that used by {{{<<newJournal>>}}} macro or the {{{<<date>>}}} and {{{<<calendar>>}}} macros (if [[DatePlugin]] and/or [[CalendarPlugin]] are installed).
>
>If the target tiddler does not yet exist, it will be automatically created when a timer activity is recorded for the first time.  Note: When used in a non-tiddler area (such as MainMenu), you should either provide a specific ~TiddlerName value (e.g., {{{<<taskTimer MainMenu>>}}} or use the ''ask'' or '''today'' keywords.
''output format''
>The default output format is: {{{|%4|%0|%1|%2|%3|}}} where %0, %1, %2, %3 and %4 are automatically replaced with the description, starttime, stoptime, elapsed time and current date values, respectively.  This format generates a single row using TiddlyWiki table format, allowing each subsequent timed task to add another row to an existing table of recorded activities.  If this table format is not appropriate for your needs, you can provide an alternative formatting string, using the %n substitution markers to place those values where you want.
>
>//Please note: ''Do not use either single-quotes or double-quotes within the format string, as this interferes with the plugin's button generating code.  Also, for backward-compatibility with previous versions of this plugin, the date value is indicated using the %4 'substitution marker', even though it is displayed as the first item in the table row.''//
''insertion point marker''
>The task timer output is usually appended to the end of the target tiddler content.  However, you may choose to insert the output //anywhere// within the tiddler content simply by embedding an 'insertion point marker', consisting of the keyword "tasktimer", enclosed in TW style comments, like this: ''{{{/%}}}{{{tasktimer}}}{{{%/}}}''.  When the marker is present in the tiddler source, the timed task report output is placed immediately //before// that marker, instead of at the end of the tiddler.
<<<
!!!!!Configuration
<<<
You can further customize the formats used by creating a separate tiddler, e.g. [[TaskTimerPluginConfig]], tagged with<<tag systemConfig>>, that contains any combination of the following javascript statements:
{{{
// default target tiddler title (when 'ask' option is used)
config.macros.taskTimer.defTarget="ActivityReport";

// table heading (when creating **new** target tiddlers only)
config.macros.taskTimer.defHeader="|//Date//|//Description//|//Started//|//Stopped//|//Elapsed//|\n";

// note: double-backslash-en, also datestamp is %4 (for backward compatibility)
config.macros.taskTimer.format="|%4|%0|%1|%2|%3|\\n";

// date stamp format (used with %4, above)
config.macros.taskTimer.datestampFormat="YYYY-0MM-0DD";

// default description text - note: do not use empty string (e.g., "")
config.macros.taskTimer.defText=" ";

// format for target tiddler title (when "today" option is used)
// otherwise, use format from CalendarPlugin, DatePlugin, DatePluginConfig,
// or <<newJournal>> macro embedded in SideBarOptions
config.macros.taskTimer.todayFormat="0MM/0DD/YYYY";

// marker for locating 'insertion point' in target tiddler
config.macros.taskTimer.marker="/%tasktimer%/";

// default tag (when creating **new** target tiddlers only)
config.macros.taskTimer.tag="task";
}}}
<<<
!!!!!Examples
<<<
{{{<<taskTimer>>}}}
<<taskTimer>>
|//Date//|//Description//|//Started//|//Stopped//|//Elapsed//|
/%tasktimer%/
{{{<<taskTimer ask>>}}}
<<taskTimer ask>>
<<<
!!!!!Revisions
<<<
2008.11.10 1.4.1 in elapsed time calculation, truncate start/stop times to nearest second (avoids 1-second 'round-down' error)
2008.10.31 1.4.0 added 'buttonFormat' for custom timer button display using %0=current, %1=start, %2=elapsed
2008.03.12 1.3.0 added 'datestampFormat' for including date in standard output.  Also, for clarity, renamed 'getDateFormat()' to 'getJournalFormat()'.
2008.03.10 [*.*.*] plugin size reduction - documentation moved to [[TaskTimerPluginInfo]]
2007.12.13 1.2.2 in getDateFormat(), cleanup fallback logic 
2007.06.28 1.2.1 pass current tiddler.fields to saveTiddler(), so updates to existing tiddler won't lose custom fields
2007.06.25 1.2.0 added optional "default text" param for specifying the default description for new activity log entries
2007.06.22 1.1.0 added "today" and "today:MMDDYYYY" as special keywords.  Generates tiddlername from current date, and uses date format defined in CalendarPlugin, DatePlugin, or DatePluginConfig if any of those tiddlers is installed.  Also, don't stop timer until user completes entering of prompted inputs (e.g., after asking for a target tiddler and activity description)
2007.05.22 1.0.0 target tiddler created when stopping timer button (i.e., second button press) instead of when starting timer.  Default header content includes comment marker.  Target tiddler is tagged with "task".
2007.04.04 0.8.2 moved handling for 'here' param into toggle().  In toggle(), only render target tiddler if button is not in that tiddler... fixes problem where starting timer with target=here was re-rendering (and thus re-initializing) the timer button (immediately stopping the timer)
2007.03.21 0.8.1 handle case where target tiddler is deleted while timer is running.
2007.03.21 0.8.0 use UTC time functions to calculate elapsed time in hours, minutes, and seconds
2007.03.20 0.7.0 added lots of cool features, like automatically creating tiddlers, with prompting, etc.
2007.03.14 0.5.0 converted from inline script
<<<