README

Grails PDF Plugin
author: Aaron Eischeid

Pdf plugin allows a Grails application to generate PDFs and send them
to the browser by converting existing pages in your application to PDF
on the fly. The underlying system uses the xhtmlrenderer component from java.net
along with iText to do the rendering.

Install the plugin from the grails repositories using the grails command:
    "grails install-plugin pdf"
Or you can use the zip file on Github.
    "grails install-plugin [path/to/zip/file]"
    
<------------>
    Notes:
<------------>
pending 0.6 version. Fix for major brokenness. POST type requests weren't
working. Other significant piece is packaging and get a new version into the 
official grails repos thanks to the new zipOnly option this should be easier. 
Next will be ... I don't know?

<------------>
    Usage:
<------------>

The plugin is really easy to use. Basically just use the tag libraries as described
in the demo.gsp and the gsp that you reference in the tag will be rendered as a 
PDF file. You should probably make some effort to style the PDF for print media
and the XHTMLrenderer under the hood provides some help in this area by enabling 
the use of certain CSS3 properties.

That is really all there is to it...

That said the plugin is pretty simple. and you could use the pdfService methods 
directly from any controller, avoiding my weird tagLibs and controller altogether.
Just add an "import pdf" and "def pdfService" to your controller then look at 
the included pdfController to get an idea of what you need to do.

There are a couple things to watch out for when actaually rendering pdfs.

The first thing is that form elements pretty much just get ignored in the PDF 
rendering process, and that can leave unpredictable spaces (or lack of spaces) in 
the page.

The second thing is that the underlying renderer ignores javascript. So pages that
have javascript effects, or content added via AJAX will not render as they would
in a web browser. This is not a bug! PDF's are meant to be static documents, and
web pages usually aren't. However, a number of people have expressed interest in
the ability of the plugin to render a snapshot of the page as it appears in the 
browser at any given moment, and that is very doable, it just hasn't been added 
into this plugin yet. If you want to do it dig into the plugin a bit, see how it
works and go for it. not to tough. you just need to get the webpage ,and base url
as a string.

A common question is what happens to images. 
Images and externally linked CSS files should be automatically resolved. 
I have experienced weirdness with CSS background images though... just play around


<------------------->
  Tag Documentation
<------------------->

g:pdfLink
attributes:

    * url (optional) - the url of the gsp you want to convert to PDF
    * filename (optional) - what you want the filename of the resultant PDF to be
                            - defualt = 'document.pdf'
    * icon (optional) - will add an <img … /> tag
    * class (optional) - set the class of element - default = 'pdf'
    * pdfController (optional) - like you would expect... (since 0.5)
    * pdfAction (optional) - like you would expect... (since 0.5)
    * pdfId (optional) - like you would expect... (since 0.5)

g:pdfForm
attributes:

    * url (optional) - the url of the gsp to want to convert to PDF
    * filename (optional) - what you want the filename of the resultant PDF to be
    * name (optional) - becomes the name and id of HTML form - default = 'simplePdfForm'
    * method (optional) - the method of the form - default = 'get'
    * template (optional) - template you want to render as a pdf, method must = post (since 0.4)
    * controller (optional) - requires action method='post' (since 0.4)
    * action (optional) - controller action for rendering PDF (since 0.4)