Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
v1.0 - tested on Chrome with demos included
  • Loading branch information
GerHobbelt committed May 28, 2014
1 parent bcb057a commit 3db474b
Show file tree
Hide file tree
Showing 12 changed files with 1,502 additions and 60 deletions.
110 changes: 110 additions & 0 deletions README.md
Expand Up @@ -2,3 +2,113 @@ jquery.print-in-page
====================

jquery plugin which enables you to print parts (elements) in the page without using popups or iframes: useful for complex parts which you don't want to copy / clone.




API
---

`$.fn.print(options)` -- can be used to set the options shared among all 'print-in-page' instances, i.e. use this if you want to tweak the defaults.

`$els.print(options)` -- initializes a print-in-page instance for the given DOM node collection. Returns a reference to the print-in-page instance, so that you can chain print-in-page methods.


### Events

print-in-page fires these custom events on the **print-in-page instance**:

- initPrinting -- triggered when you invoke the `.continue()` API method for the first time, starting a print process/session in your browser

- startPrintPreview -- ...

- renderPrintPreview -- override the default here when you have specific render (DOM manipulation) needs which do not complement the default behaviour. See the demo/main.js file for an example where a **supplementary filtering process** is applied in the `finishPrintPreview` event.

- finishPrintPreview -- Concludes the preview render/show process. By now we expect you to have your preview display in order and awaiting user ack/nack action.

- startPrint -- The actual printing process starts; if you need to perform some last-minute tweak, here's the place for that.

- renderPrint -- this phase is executing the actual `window.print()` call. Do not `e.preventDefault()` unless you wish to replace the actual printing process itself.

- finishPrint -- ...

- startRollbackAfterPrint -- you receive this event when the printing process has completed (`onafterprint`) or has been aborted via the `.abort()` API method

- renderRollbackAfterPrint -- the default action following this event is to restore the DOM to its original glory from before the start of preview/print session

- finishRollbackAfterPrint -- ...

- donePrinting -- this is the last event you will receive at the end of any and each print/preview session

- abortPrinting -- this event is fired when the .abort()` API method has been invoked and the current print/preview process can be aborted.






### Methods

where `*p*` is the print-in-page instance obtained via the `$elements.print()` API:

`*p*.on(event, f)` -- register function `f` for the given event.

> The handlers are executed in the order they are registered.
> `f` may be an *array* of handlers: each of these is then registered with the given event

`*p*.off(event, f)` -- unregister function `f` for the given event.

> `f` may be an *array* of handlers: each of these is then unregistered from the given event
> When you do not specify any handler (or `null`), then all registered handlers for this event are unregistered.
> When you do not specify an event, then the handler is unregistered for *all* events.

`*p*.continue()` -- start / continue the print operation

> Note: when invoked while the process is already commencing on its own, i.e. when called from an event handler during a *synchronous* action state,
> the call is simply ignored (the return value of the event handler is observed instead)

`*p*.prime(N)` -- prime the print operation for N `.continue()` invocations: use this method when you have multiple async processes running your event handler(s) and need *each and every one of them* to invoke `.continue()` before the print process may commence.


*p*.abort()` -- You can ABORT the print process at any time by invoking this method.

> The DOM will be restored to its original pre-print-preview glory and the print process is reset.

`*p*.isAborted()` -- truthy when the current printing session is being aborted. This flag holds until the session ends (i.e. until after the `donePrinting` event).


`*p*.isWorking()` -- truthy when the print-in-page component is considered to be 'working' i.e. when it won't liten to `.continue()` calls as it's already moving along on its own volition


`*p*.elements([$els])` -- getter/setter for the set of DOM elements which will be print/previewed. You can change the DOM element collection until the preview starts (i.e. right before the `renderPrintPreview` event) and after the original situation has been restored (i.e. just before the `finishRollbackAfterPrint` event)


`*p*.destroy()` -- alias or `.teardown()`

`*p*.teardown()` -- ... jquery teardown ...




Examples / Demos
----------------

See the `./demo` directory for several examples (demo/index.html).

**Notes**:

- All demos use [RequireJS](http://requirejs.org/) to load the JavaScript assets.

- All demos share a single JS driver file (demo/main.js)

- Check the differences in the HTML for the different examples in the `demo/` directory: these build upon one another from simple to complex, while the `main.js` driver code serves them all

- note that the (demo/restyling-and-printing.html) demo has been specifically tailored to make the actual printout **different from the preview**: by using extra print-media CSS rules and a few bits of DOM (HTML) the printout consists of multiple pages, while the preview is a single page, which does not include all the content in the lead-in page either. Check the example's HTML and CSS to observe what goes on in there.

Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
54 changes: 51 additions & 3 deletions demo/index.html
@@ -1,10 +1,58 @@
<!DOCTYPE html>
<html>
<head>
<title>jQuery Print-in-Page demo</title>
<script data-main="../scripts/main" src="../libs/require.js"></script>
<title>jQuery Print-in-Page demos</title>
<style>
html, body, h1, p, div
{
font-size: 16px;
line-height: 22px;
margin: 0;
padding: 0;
}

ul
{
font-size: 16px;
line-height: 22px;
}

h1
{
font-size: 18px;
line-height: 22px;
margin: 0;
padding: 0;
}

p
{
font-size: 12px;
line-height: 16px;
margin: 0;
padding: 0;
}

div
{
padding: 0 6px;
margin: 3px;
border: 1px solid #888;
}

body
{
padding: 6px;
}

</style>
</head>
<body>
<!-- Check the console -->
<h1>Examples</h1>
<ul>
<li><a href="simple-printing.html">simple print example</a> -- just prints a section of the demo page</li>
<li><a href="preview-plus-printing.html">print with preview example</a> -- shows a preview, user then hits button the print or abort/revert</li>
<li><a href="restyling-and-printing.html">restyling print example</a> -- restyles the content for preview &amp; printing</li>
</ul>
</body>
</html>
195 changes: 195 additions & 0 deletions demo/preview-plus-printing.html
@@ -0,0 +1,195 @@
<!DOCTYPE html>
<html>
<head>
<title>jQuery Print-in-Page demo: Preview &amp; Printing</title>
<style>
html, body, h1, p, div
{
font-size: 16px;
line-height: 22px;
margin: 0;
padding: 0;
}

ul
{
font-size: 16px;
line-height: 22px;
}

h1
{
font-size: 18px;
line-height: 22px;
margin: 0;
padding: 0;
}

p
{
font-size: 12px;
line-height: 16px;
margin: 0;
padding: 0;
}

div
{
padding: 0 6px;
margin: 3px;
border: 1px solid #888;
}

body
{
padding: 6px;
}

div.content-A
{
background-color: #fee;
}

div.content-B
{
background-color: #eee;
}

div.content-C
{
background-color: #eef;
}

div.content-D
{
background-color: #efe;
}

.print-buttons, .previewPanel
{
background-color: #ffe;
border: 2px solid grey;
padding: 1em 2em;
text-align: center;
margin-top: 2em;
}

.print-buttons button, .previewPanel button
{
min-width: 20em;
margin: 0 2em;
}

.previewPanel p
{
font-size: 14px;
font-style: italic;
margin-bottom: 1em;
}


/* using styles to hide/show printing content */

.pip-do-not-print
{
display: none !important;
}
.pip-print
{
}
.pip-print-parent
{
}
.pip-print-root
{
padding: 1em;
border: 6px solid red;
margin: 1em;
}



/* this bit of the DOM stays hidden until the preview need it: */
.previewPanel
{
display: none;
}

</style>
</head>
<body>
<div class="content-A">
<h1>content A</h1>
<p>Bla bla bla</p>
</div>

<div class="content-B">
<h1>content B</h1>
<p>Bla bla bla</p>

<div class="content-C">
<h1>content C inside B</h1>
<p>Bla bla bla</p>
</div>

<div class="content-D">
<h1>content D inside B</h1>
<p>Bla bla bla</p>
</div>
</div>

<div class="content-A">
<h1>more content A</h1>
<p>Bla bla bla</p>
</div>

<div class="content-A">
<h1>even more content A</h1>
<p>Bla bla bla</p>
</div>

<div class="content-B">
<h1>more content B</h1>
<p>Bla bla bla</p>

<div class="content-C">
<h1>more content C inside B</h1>
<p>Bla bla bla</p>
</div>

<div class="content-D">
<h1>more content D inside B</h1>
<p>Bla bla bla</p>
</div>
</div>

<div class="print-buttons">
<div style="margin-bottom: 1em; text-align: left; border: 0; background-color: #eed;">
<input name="only-div-nodes" id="only-div-nodes" type="checkbox" />
<label for="only-div-nodes">Only edit <code>DIV</code> nodes in the DOM <em>(watch the effect on the 'B' content being included in the printed result or not... this being due to the <code>P</code> and <code>H1</code> DOM nodes being hidden as siblings of the 'C' &amp; 'D' <code>DIV</code>s.)</em></label>
</div>

<button class="click-to-print print-area-A">Click to Print 'A' sections only</button>

<button class="click-to-print print-area-C">Click to Print 'C' sections only (nested inside 'B' sections...)</button>

<button class="click-to-print print-area-C print-area-B" title="HINT: this will result in each entire 'B' chunk being printed; the print-in-page plugin does not mind you effectively specified the C sections _twice_">Click to Print 'C' plus 'B' sections == all 'B' sections</button>

<button class="click-to-print print-area-A print-area-D">Click to Print 'A' + 'D' sections</button>
</div>

<div class="previewPanel">
<hr />
<p>Now that you see this preview above, are you sure you want to print this stuff? Hit the <code>YES</code> button if you want to, otherwise click on the <code>NO/ABORT</code> button when you wish to abort the print action now.</p>

<button id="preview-okay">YES</button>

<button id="preview-abort">NO / ABORT</button>
</div>


<!-- Check the console -->

<script data-main="../scripts/main" src="../libs/require.js"></script>
</body>
</html>

0 comments on commit 3db474b

Please sign in to comment.