diff options
Diffstat (limited to 'google_appengine/lib/django/docs/outputting_pdf.txt')
| -rw-r--r-- | google_appengine/lib/django/docs/outputting_pdf.txt | 153 |
1 files changed, 153 insertions, 0 deletions
diff --git a/google_appengine/lib/django/docs/outputting_pdf.txt b/google_appengine/lib/django/docs/outputting_pdf.txt new file mode 100644 index 0000000..bd6ae7a --- /dev/null +++ b/google_appengine/lib/django/docs/outputting_pdf.txt @@ -0,0 +1,153 @@ +=========================== +Outputting PDFs with Django +=========================== + +This document explains how to output PDF files dynamically using Django views. +This is made possible by the excellent, open-source ReportLab_ Python PDF +library. + +The advantage of generating PDF files dynamically is that you can create +customized PDFs for different purposes -- say, for different users or different +pieces of content. + +For example, Django was used at kusports.com_ to generate customized, +printer-friendly NCAA tournament brackets, as PDF files, for people +participating in a March Madness contest. + +.. _ReportLab: http://www.reportlab.org/rl_toolkit.html +.. _kusports.com: http://www.kusports.com/ + +Install ReportLab +================= + +Download and install the ReportLab library from http://www.reportlab.org/downloads.html. +The `user guide`_ (not coincidentally, a PDF file) explains how to install it. + +Test your installation by importing it in the Python interactive interpreter:: + + >>> import reportlab + +If that command doesn't raise any errors, the installation worked. + +.. _user guide: http://www.reportlab.com/docs/userguide.pdf + +Write your view +=============== + +The key to generating PDFs dynamically with Django is that the ReportLab API +acts on file-like objects, and Django's ``HttpResponse`` objects are file-like +objects. + +.. admonition:: Note + + For more information on ``HttpResponse`` objects, see + `Request and response objects`_. + + .. _Request and response objects: ../request_response/ + +Here's a "Hello World" example:: + + from reportlab.pdfgen import canvas + from django.http import HttpResponse + + def some_view(request): + # Create the HttpResponse object with the appropriate PDF headers. + response = HttpResponse(mimetype='application/pdf') + response['Content-Disposition'] = 'attachment; filename=somefilename.pdf' + + # Create the PDF object, using the response object as its "file." + p = canvas.Canvas(response) + + # Draw things on the PDF. Here's where the PDF generation happens. + # See the ReportLab documentation for the full list of functionality. + p.drawString(100, 100, "Hello world.") + + # Close the PDF object cleanly, and we're done. + p.showPage() + p.save() + return response + +The code and comments should be self-explanatory, but a few things deserve a +mention: + + * The response gets a special mimetype, ``application/pdf``. This tells + browsers that the document is a PDF file, rather than an HTML file. If + you leave this off, browsers will probably interpret the output as HTML, + which would result in ugly, scary gobbledygook in the browser window. + + * The response gets an additional ``Content-Disposition`` header, which + contains the name of the PDF file. This filename is arbitrary: Call it + whatever you want. It'll be used by browsers in the "Save as..." + dialogue, etc. + + * The ``Content-Disposition`` header starts with ``'attachment; '`` in this + example. This forces Web browsers to pop-up a dialog box + prompting/confirming how to handle the document even if a default is set + on the machine. If you leave off ``'attachment;'``, browsers will handle + the PDF using whatever program/plugin they've been configured to use for + PDFs. Here's what that code would look like:: + + response['Content-Disposition'] = 'filename=somefilename.pdf' + + * Hooking into the ReportLab API is easy: Just pass ``response`` as the + first argument to ``canvas.Canvas``. The ``Canvas`` class expects a + file-like object, and ``HttpResponse`` objects fit the bill. + + * Note that all subsequent PDF-generation methods are called on the PDF + object (in this case, ``p``) -- not on ``response``. + + * Finally, it's important to call ``showPage()`` and ``save()`` on the PDF + file. + +Complex PDFs +============ + +If you're creating a complex PDF document with ReportLab, consider using the +cStringIO_ library as a temporary holding place for your PDF file. The +cStringIO library provides a file-like object interface that is particularly +efficient. Here's the above "Hello World" example rewritten to use +``cStringIO``:: + + from cStringIO import StringIO + from reportlab.pdfgen import canvas + from django.http import HttpResponse + + def some_view(request): + # Create the HttpResponse object with the appropriate PDF headers. + response = HttpResponse(mimetype='application/pdf') + response['Content-Disposition'] = 'attachment; filename=somefilename.pdf' + + buffer = StringIO() + + # Create the PDF object, using the StringIO object as its "file." + p = canvas.Canvas(buffer) + + # Draw things on the PDF. Here's where the PDF generation happens. + # See the ReportLab documentation for the full list of functionality. + p.drawString(100, 100, "Hello world.") + + # Close the PDF object cleanly. + p.showPage() + p.save() + + # Get the value of the StringIO buffer and write it to the response. + pdf = buffer.getvalue() + buffer.close() + response.write(pdf) + return response + +.. _cStringIO: http://www.python.org/doc/current/lib/module-cStringIO.html + +Further resources +================= + + * PDFlib_ is another PDF-generation library that has Python bindings. To + use it with Django, just use the same concepts explained in this article. + * HTMLdoc_ is a command-line script that can convert HTML to PDF. It + doesn't have a Python interface, but you can escape out to the shell + using ``system`` or ``popen`` and retrieve the output in Python. + * `forge_fdf in Python`_ is a library that fills in PDF forms. + +.. _PDFlib: http://www.pdflib.org/ +.. _HTMLdoc: http://www.htmldoc.org/ +.. _forge_fdf in Python: http://www.accesspdf.com/article.php/20050421092951834 |