(Read more interesting articles on Django 1.2 e-commerce here.)
ReportLab is an open source project available at http://www.reportlab.org. It is a very mature tool and includes binaries for several platforms as well as source code. It also contains extension code written in C, so it’s relatively fast. It is possible for ReportLab to insert PNG and GIF image files into PDF output, but in order to do so we must have the Python Imaging Library (PIL) installed. We will not require this functionality in this article, but if you need it for a future project, see the PIL documentation for setup instructions.
The starting point in the ReportLab API is drawing to canvas objects. Canvas objects are exactly what they sound like: blank slates that are accessible using various drawing commands that paint graphics, images, and words. This is sometimes referred to as a low-level drawing interface because generating output is often tedious. If we were creating anything beyond basic reporting output, we would likely want to build our own framework or set of routines on top of these low-level drawing functions.
Drawing to a canvas object is a lot like working with the old LOGO programming language. It has a cursor that we can move around and draw points from one position to another. Mostly, these drawing functions work with two-dimensional (x, y) coordinates to specify starting and ending positions.
This two-dimensional coordinate system in ReportLab is different from the typical system used in many graphics applications. It is the standard Cartesian plane, whose origin (x and y coordinates both equal to 0) begins in the lower-left hand corner instead of the typical upper-right hand corner. This coordinate system is used in most mathematics courses, but computer graphics tools, including HTML and CSS layouts, typically use a different coordinate system, where the origin is in the upper-left.
ReportLab’s low-level interface also includes functions to render text to a canvas. This includes support for different fonts and colors. The text routines we will see, however, may surprise you with their relative crudeness. For example, word-wrapping and other typesetting operations are not automatically implemented. ReportLab includes a more advanced set of routines called PLATYPUS, which can handle page layout and typography. Most low-level drawing tools do not include this functionality by default (hence the name “low-level”).
This low-level drawing interface is called pdfgen and is located in the reportlab.pdfgen module. The ReportLab User’s Guide includes extensive information about its use and a separate API reference is also available.
The ReportLab canvas object is designed to work directly on files. We can create a new canvas from an existing open file object or by simply passing in a file name. The canvas constructor takes as its first argument the filename or an open file object. For example:
from reportlab.pdfgen import canvas
c = canvas.Canvas("myreport.pdf")
Once we obtained a canvas object, we can access the drawing routines as methods on the instance. To draw some text, we can call the drawString method:
c.drawString(250, 250, "Ecommerce in Django")
This command moves the cursor to coordinates (250, 250) and draws the string “Ecommerce in Django“. In addition to drawing strings, the canvas object includes methods to create rectangles, lines, circles, and other shapes.
Because PDF was originally designed for printed output, consideration needs to be made for page size. Page size refers to the size of the PDF document if it were to be output to paper. By default, ReportLab uses the A4 standard, but it supports most popular page sizes, including letter, the typical size used in the US. Various page sizes are defined in reportlab.lib.pagesizes. To change this setting for our canvas object, we pass in the pagesize keyword argument to the canvas constructor.
from reportlab.lib.pagesizes import letter
c = canvas.Canvas('myreport.pdf', pagesize=letter)
Because the units passed to our drawing functions, like rect, will vary according to what page size we’re using, we can use ReportLab’s units module to precisely control the output of our drawing methods. Units are stored in reportlab.lib.units. We can use the inch unit to draw shapes of a specific size:
from reportlab.lib.units import inch
c.rect(1*inch, 1*inch, 0.5*inch, 1*inch)
The above code fragment draws a rectangle, starting one inch from the bottom and one inch from the left of the page, with sides that are length 0.5 inches and one inch, as shown in the following screenshot:
Not particularly impressive is it? As you can see, using the low-level library routines require a lot of work to generate very little results. Using these routines directly is tedious. They are certainly useful and required for some tasks. They can also act as building blocks for your own, more sophisticated routines.
Building our own library of routines would still be a lot of work. Fortunately ReportLab includes a built-in high-level interface for creating sophisticated report documents quickly. These routines are called PLATYPUS; we mentioned them earlier when talking about typesetting text, but they can do much more.
PLATYPUS is an acronym for “Page Layout and Typography Using Scripts”. The PLATYPUS code is located in the reportlab.platypus module. It allows us to create some very sophisticated documents suitable for reporting systems in an e-commerce application.
Using PLATYPUS means we don’t have to worry about things such as page margins, font sizes, and word-wrapping. The bulk of this heavy lifting is taken care of by the high-level routines. We can, if we wish, access the low-level canvas routines. Instead we can build a document from a template object, defining and adding the elements (such as paragraphs, tables, spacers, and images) to the document container.
The following example generates a PDF report listing all the products in our Product inventory:
from reportlab.platypus.doctemplate import SimpleDocTemplate
from reportlab.platypus import Paragraph, Spacer
from reportlab.lib import sytles
doc = SimpleDocTemplate("products.pdf")
Catalog = []
header = Paragraph("Product Inventory",
styles['Heading1']) Catalog.append(header)
style = styles['Normal']
for product in Product.objects.all():
for product in Product.objects.all():
p = Paragraph("%s" % product.name, style)
Catalog.append(p)
s = Spacer(1, 0.25*inch)
Catalog.append(s)
doc.build(Catalog)
The previous code generates a PDF file called products.pdf that contains a header and a list of our product inventory. The output is displayed in the accompanying screenshot.
