Tutorial using Django

Once you have Geraldo installed and its dependencies resolved (read the Installation document to know about the dependencies on ReportLab and Python Imaging Library), you can start opening the settings.py from your project to edit.

Attention: this tutorial assumes you are going to use Geraldo with a Django project, but in fact you can just ignore the Django parts and all the rest is exactly the same for Django and non-Django cases.

Step 1. Preparing your project

To install Geraldo in your Django project, you must change the setting INSTALLED_APPS in your settings.py file and this should be enough.

But let’s create a new URL to load a PDF report online.

Attention: Geraldo can work with online or file ways to get a PDF. You are not dependent on a URL or view to generate reports from Geraldo. This is just one of many ways you can do it.

We are going to work with a common example for this kind of solution: a purchasing application.

Let’s say you have the following model classes:

class Product(models.Model):
    name = models.CharField(max_length=100)

class Customer(models.Model):
    name = models.CharField(max_length=100)

class Purchase(models.Model):
    customer = models.ForeignKey('Customer')
    delivery_address = models.CharField(max_length=70, blank=True)
    date_creation = models.DateField(blank=True, default=date.today())
    date_bill = models.DateField(blank=True, null=True)
    date_delivery = models.DateField(blank=True, null=True)
    taxes = models.DecimalField(max_digits=12, decimal_places=2, blank=True, default=0)
    sub_total_price = models.DecimalField(max_digits=12, decimal_places=2, blank=True, default=0)
    total_price = models.DecimalField(max_digits=12, decimal_places=2, blank=True, default=0)

class PurchaseItem(models.Model):
    purchase = models.ForeignKey('Purchase')
    product = models.ForeignKey('Product')
    unit_price = models.DecimalField(max_digits=12, decimal_places=2)
    quantity = models.DecimalField(max_digits=12, decimal_places=2)
    total_price = models.DecimalField(max_digits=12, decimal_places=2, blank=True, default=0)

First you declare a new URL, for example:

urlpatterns = patterns('purchases.views',
    url('^purchase-report/$', 'purchase_report'),
)

The next step is you have a view for the created URL, like this:

from django.http import HttpResponse

from reports import ReportPurchase
from geraldo.generators import PDFGenerator
from models import Purchase

def purchase_report(request):
    resp = HttpResponse(mimetype='application/pdf')

    purchases = Purchase.objects.order_by('customer', 'id')
    report = ReportPurchase(queryset=purchases)
    report.generate_by(PDFGenerator, filename=resp)

    return resp

You can see you first imported two important things:

from reports import ReportPurchase
from geraldo.generators import PDFGenerator

Your report class (we will create it in the next step) and the generator class PDFGenerator you will need to generate a PDF file. In the future we will have other generators, for other formats of file.

The next thing to note is that you are going to return a PDF format HttpResponse:

resp = HttpResponse(mimetype='application/pdf')

Now you are going to work your report instance:

purchases = Purchase.objects.order_by('customer', 'id')
report = ReportPurchase(queryset=purchases)
report.generate_by(PDFGenerator, filename=resp)
  • The first thing you did is to get all purchases, ordered by ‘customer’ and ‘id’ fields;
  • Afterwards, you got a report instance from your report class ReportPurchase, using purchases queryset as report driver queryset;
  • And last, you called the ‘generate_by’ method of the generator class.

Now you have a prepared Django application to use a report you are going to create at the next step!

Declaring the report class

The report class must be an inheritance from geraldo.Report class. You can create a new file ‘reports.py’ to declare your report classes inside.

from geraldo import Report

class ReportPurchase(Report):
    title = 'Purchases list'
    author = 'John Smith Corporation'

To see something more complex, you can set the page size, margins and other report attributes, like below:

from geraldo import Report, landscape
from reportlab.lib.pagesizes import A5
from reportlab.lib.units import cm

class ReportPurchase(Report):
    title = 'Purchases list'
    author = 'John Smith Corporation'

    page_size = landscape(A5)
    margin_left = 2*cm
    margin_top = 0.5*cm
    margin_right = 0.5*cm
    margin_bottom = 0.5*cm

As you can see, we use what we can from the ReportLab libraries, their units, page sizes, stylizing, etc.

A report is driven by bands. If you are used to working with other report engines you know what a band is.

A band is a row with elements in the report canvas. Bands in essence are the same but their use varies depending whether you are using a band as the Page Header or Report Summary, for example.

A report can have a band for each one of following attributes:

Detail band

The detail band is the most important band in a report. This is because the detail band is the reason of the existence of every report.

The detail band is used most of the time to show object field values. This is the same for a detailed info page or just a simple list or grid.

The detail band is rendered one time for each object in the queryset attribute. So, if you have 10 objects in the queryset, you will have the detail band rendered 10 times.

Let’s change our report to have a detail band, see below:

from geraldo import Report, landscape, ReportBand, ObjectValue
from reportlab.lib.pagesizes import A5
from reportlab.lib.units import cm

class ReportPurchase(Report):
    title = 'Purchases list'
    author = 'John Smith Corporation'

    page_size = landscape(A5)
    margin_left = 2*cm
    margin_top = 0.5*cm
    margin_right = 0.5*cm
    margin_bottom = 0.5*cm

    class band_detail(ReportBand):
        height = 0.5*cm
        elements=(
            ObjectValue(attribute_name='id', left=0.5*cm),
            ObjectValue(attribute_name='date_creation', left=3*cm,
                get_value=lambda instance: instance.date_creation.strftime('%m/%d/%Y')),
            )

The attribute band_detail is locally declared as a class, but it could alternatively be set with an external class.

The important thing here is that the band has the attribute height, fixed with a defined height in centimeters.

The second thing to observe is the elements list, with 2 widgets representing 2 model class fields: id and date_creation. The last one is customized with the get_value attribute, for date field formatting.

Grouping

The next thing now is to group our purchases by a field. Let’s choose the field customer, ok?

Geraldo allows you to group a report at many levels. This means you can group the report objects by 1, 2 or however many fields you want and have a header and footer to show their aggregation information and other features.

But for now, just add the following code to the end of reports.py:

groups = [
        ReportGroup(attribute_name = 'customer',
            band_header = ReportBand(
                height = 0.7*cm,
                elements = [
                    ObjectValue(attribute_name='customer', left=0, top=0.1*cm, width=20*cm,
                        get_value=lambda instance: 'Customer: ' + (instance.customer.name),
                        style={'fontName': 'Helvetica-Bold', 'fontSize': 12})
                    ],
                borders = {'bottom': True},
                )
            ),
        ]

In the same way as you did before, you have to change the top imports to have the new elements:

from geraldo import Report, landscape, ReportBand, ObjectValue, SystemField,\
        BAND_WIDTH, Label, ReportGroup

The two important things now are:

  • attribute_name - this attribute in ReportGroup defines which field we are going to use to group the objects. You must order the queryset beforehand by this attribute to have it working properly. Here you can use a field name, free attribute, property or method that you have in queryset objects;
  • band_header - this band is for you to show things above the group. You can also use band_footer if you wish.

SubReports

SubReport is the way you have to show object children data in a report. As you know, a purchase has many items, and they are available in attribute purchase.purchaseitem_set.all() os something like that.

Geraldo allows you to have however many subreports you want, and they will appear in the same sequence that you place them in the class declaration.

Just add the following block of code to the end of reports.py:

subreports = [
        SubReport(
            queryset_string = '%(object)s.purchaseitem_set.all()',
            detail_band = ReportBand(
                height=0.5*cm,
                elements=[
                    ObjectValue(attribute_name='product', top=0, left=1*cm),
                    ObjectValue(attribute_name='unit_price', top=0, left=5*cm),
                    ]
                ),
            ),
        ]

And now you have to change the top imports line:

from geraldo import Report, landscape, ReportBand, ObjectValue, SystemField,\
        BAND_WIDTH, Label, ReportGroup, SubReport

The new and most interesting thing here is this:

queryset_string = '%(object)s.purchaseitem_set.all()',

This is the attribute that you use to join the detail object to the subreport. It is a string because you can do a relationship to get objects using different ways.

So, you just use the macro ‘%(object)s’ to set the current object!