Massive reorganization of the docs. See the new docs online at http://docs.djangoproject.com/.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@8506 bcc190cf-cafb-0310-a4f2-bffc1f526a37

docs/howto/outputting-pdf.txt

@@ -0,0 +1,160 @@
+.. _howto-outputting-pdf:
+
+===========================
+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 :class:`~django.http.HttpResponse`
+objects are file-like objects.
+
+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 MIME type, ``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 :class:`~django.http.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.
+    * `Pisa HTML2PDF`_ is yet another PDF-generation library. Pisa ships with
+      an example of how to integrate Pisa with Django.      
+    * 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/
+.. _`Pisa HTML2PDF`: http://www.htmltopdf.org/
+.. _HTMLdoc: http://www.htmldoc.org/
+.. _forge_fdf in Python: http://www.accesspdf.com/article.php/20050421092951834
+
+Other formats
+=============
+
+Notice that there isn't a lot in these examples that's PDF-specific -- just the
+bits using ``reportlab``. You can use a similar technique to generate any
+arbitrary format that you can find a Python library for. Also see
+:ref:`howto-outputting-csv` for another example and some techniques you can use
+when generated text-based formats.