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.

Page Header and Page Footer bands
---------------------------------

Page header and Page footer bands are designed to appear on the header and
footer, respectively, on every page in the report.

In most reports, a page header is used to show the report title and its page number,
page count and maybe the columns header if you are creating a list or grid report.

In the same way, a page footer band is used to show footer information, like the print
date/time, software name, company's mark, etc.

Add this code block to the end of the report class to have both bands:

::

        class band_page_header(ReportBand):
            height = 1.3*cm
            elements = [
                    SystemField(expression='%(report_title)s', top=0.1*cm, left=0, width=BAND_WIDTH,
                        style={'fontName': 'Helvetica-Bold', 'fontSize': 14, 'alignment': TA_CENTER}),
                    Label(text="ID", top=0.8*cm, left=0.5*cm),
                    Label(text=u"Creation Date", top=0.8*cm, left=3*cm),
                    SystemField(expression=u'Page %(page_number)d of %(page_count)d', top=0.1*cm,
                        width=BAND_WIDTH, style={'alignment': TA_RIGHT}),
                    ]
            borders = {'bottom': True}
    
        class band_page_footer(ReportBand):
            height = 0.5*cm
            elements = [
                    Label(text='Geraldo Reports', top=0.1*cm),
                    SystemField(expression=u'Printed in %(now:%Y, %b %d)s at %(now:%H:%M)s', top=0.1*cm,
                        width=BAND_WIDTH, style={'alignment': TA_RIGHT}),
                    ]
            borders = {'top': True}

Now you have to change the top lines of the file with imports to import some new elements:

::

    from geraldo import Report, landscape, ReportBand, ObjectValue, SystemField,\
            BAND_WIDTH, Label
    
    from reportlab.lib.pagesizes import A5
    from reportlab.lib.units import cm
    from reportlab.lib.enums import TA_RIGHT, TA_CENTER

The new elements for you now are:

- **SystemField** - shows a system field, like current date/time, page number,
  page count, report title, report author, etc.
- **Label** - show a free text
- **BAND_WIDTH** - sets the width automatically to its parent band width;
- **TA_RIGHT** and **TA_CENTER** - they set the alignment of a widget

Other good use of Page Header and Page Footer bands is to compose or inherit
reports layout. Use your imagination!

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!
