/***
|Name|SnapshotPluginInfo|
|Source|http://www.TiddlyTools.com/#SnapshotPlugin|
|Documentation|http://www.TiddlyTools.com/#SnapshotPluginInfo|
|Version|1.3.0|
|Author|Eric Shulman|
|License|http://www.TiddlyTools.com/#LegalStatements|
|~CoreVersion|2.1|
|Type|documentation|
|Description|Documentation for SnapshotPlugin|
This plugin provides a macro as well as tiddler toolbar commands that creates a file or opens a new browser window containing the //rendered// HTML and CSS style definitions that are being displayed for selected elements of the current document.
!!!!!Usage:
<<<
As a macro embedded in tiddler content:
{{{
<<snapshot print label:text prompt:text id:elementID|here|viewer|story|all|ask>
}}}
where:
*''print'' //(optional)//<br>when present, causes the snapshot output to be directed to a new browser tab/window instead of saving it to a file.  In addition, the print dialog for that tab/window is automatically invoked.
*''label'' //(optional)//<br>is the text to be displayed for the command link generated by the macro
*''prompt'' //(optional)//<br>is the 'tool tip' message displayed when you mouseover the command link
*''id:...'' //(optional)//<br>specifies the document element to be captured, and can be one of:
**''elementID''<br>is a specific DOM element ID, such as "displayArea", "mainMenu", "contentWrapper", etc.
**''here''<br>the containing tiddler in which the macro (or toolbar command) occurs, including the tiddler title and subtitle (date/time/author) information.
**''viewer''<br>same as ''here'', but omits the tiddler title, subtitle and toolbar elements (i.e., it includes //only// the content of the tiddler)
**''story''<br>selects all currently displayed tiddlers (i.e., the 'story column')
**''all''<br>selects the entire document contents, including page header, main menu and sidebar displays
**''ask''<br>when the snapshot command link is clicked, a droplist is displayed so you can choose from several pre-defined elements: "current tiddler", "story column", or "entire document", or "DOM element ID..."  When DOM element ID is chosen, the droplist is refreshed to show the individual ID's for all currently rendered DOM elements (at least, the ones that have ID's).  For any given DOM element ID, only the portions of the document that are contained //within// the specified DOM element will be transcribed to the resulting snapshot or print output.  
//''NOTE: when no parameters are specified, the macro creates a snapshot file using the containing tiddler as the default element.'' (e.g., equivalent to {{{<<snapshot id:here>>}}}//

The snapshot/print functions can also be embedded as tiddler toolbar commands in [[ViewTemplate]]:
{{{
<span class='toolbar' macro='toolbar snapshotSave'></span>
<span class='toolbar' macro='toolbar snapshotPrint'></span>
}}}
* when invoked via toolbar commands, the "id:ask" option is automatically applied, and a droplist of elements to choose from is displayed.

Please note that, although the snapshot/print that is created using the HTML+CSS of the displayed content, ''there is NO javascript code'' written into the snapshot.  As a result, the snapshot only ''reproduces the //appearance// of the displayed content, allowing you to //view// or //print// the result'', but does not permit you to interact with it in other ways.

For example, even simple processing (such as mouseover highlighting) will not function from the snapshot.  You can't click a TiddlyLink to open other tiddlers, because A) there is no code that handles the click and B) there is no underlying 'storeArea' (and core code) to retrieve and render anything!  You also can't use ANY command links, since these also require javascript code (and the core) to operate. 
<<<
!!!!!Examples:
<<<
{{{<<snapshot>>}}}: <<snapshot>>
{{{<<snapshot id:mainMenu>>}}}: <<snapshot id:mainMenu>>
{{{<<snapshot print id:story>>}}}: <<snapshot print id:story>>
{{{<<snapshot print id:ask>>}}}: <<snapshot print id:ask>>
{{{<<snapshot print noCSS id:viewer>>}}}: <<snapshot print noCSS id:viewer>>
<<<
!!!!!Configuration
<<<
<<option chkSnapshotHTMLOnly>> output HTML only (omit CSS)
<<<
!!!!!Revisions
<<<
2009.10.12 1.3.0 added multi-file story snapshot
2009.09.25 1.2.1 in getSnap(), added META tag to set UTF-8 encoding for I18N support
2009.06.04 1.2.0 added handling in getSnap() so current form input values are shown in snapshots
2008.05.16 1.1.1 added try..catch around addEvent/removeEvent calls to avoid error in Opera
2008.04.28 1.1.0 removed 'viewerHTML' from 'ask' droplist and replaced with toggle for "output HTML only".  Removed 'noCSS' parameter and replaced with config.options.chkSnapshotHTMLOnly global option.  Added "select a tiddler..." to 'ask' droplist
2008.04.24 1.0.1 in saveSnap(), convert output from Unicode to UTF before passing to saveFile().  Fixes "unknown name" error in IE's file.Write() function.
2008.04.21 1.0.0 initial release - derived from [[NewDocumentPlugin]] with many improvements, including: "ask for ID" using droplist of available DOM elements, use "<base href=...>" for correctly resolving image references, wrap 'viewer only' output in class="tiddler viewer" for proper application of inherited CSS styles, snapshotSave and snapshotPrint tiddler toolbar command definitions, and more...

__Excerpted revisions from [[NewDocumentPlugin]] (obsolete)__
2008.04.20 1.8.0 added support for 'noCSS' and 'viewer' params for alternative snapshot output
2007.03.30 1.7.0 added support for "print" param as alternative for "snap".  When "print" is used, the filename is ignored and ouput is directed to another browser tab/window, where the print dialog is then automatically triggered.
2007.03.30 1.6.1 added support for "here" keyword for current tiddler elementID and "prompt:text" param for specifying tooltip text
2006.10.18 1.5.0 new optional param for 'snap'... specify alternative DOM element ID (default is still "contentWrapper").  Based on a suggestion from Xavier Verges.
2006.03.09 1.2.0 added special "snap" filter parameter to generate and write "snapshot" files containing static HTML+CSS for currently rendered document.
2006.02.03 1.0.0 Created.
<<<