frePPLev2.0
open source Production PLanning
  • Home
  • Documentation
    • Getting started
    • Modeling guide
    • User guide
    • Installation guide
    • Developer guide
    • FAQ
  • C++ API

Adding or customizing a report

This section describes the different steps to add a new report (or update an existing one) in the user interface. We’ll describe both the general case as well as the generic view provided by frePPLe.

The steps outline here are a short and very brief summary of how screens are designed in the Django web application framework. More detailed instructions are available on the Django websitehttps://www.djangoproject.com, which has an excellent tutorial.

General case

As an example we’ll create a report to display some statistics on the size of your model. It will simply display the total number of buffers and operations in your model.

  1. Create a view to generate the data.
    A view function retrieves the report data from the database (or computes it from another source) and passes a data dictionary with the data to the report template.
    A view is a Python function. Here’s the view required for our example, which you can put in a file statistics.py:

      from freppledb.input.models import *
      from django.shortcuts import render_to_response
      from django.template import RequestContext
      from django.contrib.admin.views.decorators import staff_member_required
    
      @staff_member_required
      def MyStatisticsReport(request):
        countOperations = Operation.objects.using(request.database).count()
        countBuffers = Buffer.objects.using(request.database).count()
        return render_to_response('statistics.html', 
           RequestContext(request, {
             'numOperations': countOperations, 
             'numBuffers': countBuffers, 
             'title': 'Model statistics',
           }))

    The function decorator staff_member_required is used to assure users are authenticated properly.
    Notice how the first 2 statements in the function use the Django relational mapping to pick the data from the database. This code is translated by the framework in SQL queries on the database.
    The last line in the function passes the data in a dictionary to the Django template engine. The template engine will generate the HTML code returned to the user’s browser.

  2. Create a template to visualize the data.
    The template file statistics.html will define all aspects of the visualizing the results.
    The file templates/statistics.html for our example looks like this:

      {% extends "admin/base_site_nav.html" %}
      {% load i18n %}
      {% block content %}
      <div id="content-main">
      {% trans 'Number of operations:' %} {{numOperations}}<br/>
      {% trans 'Number of buffers:' %} {{numBuffers}}<br/>
      </div>
      {% endblock %}

    Templates are inheriting from each other. In this example we inherit from the base template which already contains the navigation toolbar and the breadcrumbs trail. We only override the block which contains the div-element with the main content.
    Templates use special tags to pick up data elements or to call special functions. The {{ }} tag is used to refer to the data elements provided by the view function. The {% trans %} tag is used to mark text that should be translated into the different targetted languages for the user interface.

  3. Map the view as a URL.
    To expose the view as a URL to the users you’ll need to map it to a URL pattern. This mapping is defined in the files urls.py, input/urls.py, output/urls.py, common/urls.py and execute/urls.py.
    Edit the definition of the urlpatterns variable in the file urls.py to set up a URL for this example:

      urlpatterns = patterns('',
        ...    
        (r'^statistics.html$', 'statistics.MyStatisticsReport'),
        )

  4. Update the menu structure.
    To insert the view you’ll probably want to insert it in the menu bar and/or the context menus of the different objects.
    This requires editing the files:

    • templates/admin/base_site_nav.html: Menu bar
    • templates/*context.html: Context menu for different entities

Using the frePPLe generic report

FrePPLe uses a standard view for displaying data in a list or grid layout, respectively called ListReport and TableReport. With these views you can add new reports with with less code and more functionality (such as sorting, filtering, pagination, CSV export).
The steps for adding the view are slightly different from the generic case.

  1. Define a report class
    Instead of defining a view function we define a class with the report metadata. See the definition of the report base classes in the file common/report.py to see all available options for the metadata classes.
    For a list report this class has the following structure:

      from freppledb.common.report import *
    
      class myReportClass(ListReport):
        template = 'myreporttemplate.html'
        title = 'title of my report'
        basequeryset = ... # A query returning the data to display
        frozenColumns = 1
        rows = (
          ('field1', {
            'filter': FilterNumber(operator='exact', ),
            'title': _('field1'),
            }),
          ('field2', {
            'filter': FilterText(size=15),
            'title': _('field2')}),
          ('field3', {
            'title': _('field3'),
            'filter': FilterDate(),
            }),
          )

    For a table report this class has the following structure:

      from freppledb.common.report import *
    
      class myReportClass(TableReport):
        template = 'myreporttemplate.html'
        title = 'title of my report'
        basequeryset = ... # A query returning the data to display
        model = Operation
        rows = (
          ('field1',{
            'filter': FilterNumber(operator='exact', ),
            'title': _('field1'),
            }),
          )
        crosses = (
          ('field2', {'title': 'field2',}),
          ('field3', {'title': 'field3',}),
          )
        columns = (
          ('bucket',{'title': _('bucket')}),
          )
    
        @staticmethod
        def resultlist1(request, basequery, bucket, startdate, enddate, sortsql='1 asc'):
          ... # A query returning the data to display as fixed columns on the left hand side.
    
        @staticmethod
        def resultlist2(request, basequery, bucket, startdate, enddate, sortsql='1 asc'):
          ... # A query returning the data to display for all cells in the grid.

  2. Create a template to visualize the data.
    For a list report the template has the following structure:

      {% extends "admin/base_site_list.html" %}
      {% load i18n %}
    
      {% block frozendata %}
      {% for i in objectlist1 %}
      <tr>
      <td>{{i.field1}}</td>
      </tr>{% endfor %}
      {% endblock %}
    
      {% block data %}
      {% for i in objectlist1 %}
      <tr>
      <td>{{i.field2}}</td>
      <td>{{i.field3}}</td>
      </tr>{% endfor %}
      {% endblock %}

    For a grid report the template is identical, but inherits from the admin/base_site_table.html template instead.

  3. Map the view as a URL.
    The syntax for adding a report now refers to the generic view, and we pass the report class as an argument:

      urlpatterns = patterns('',
        ... 
        (r'^myreport/([^/]+)/$', 'freppledb.common.report.view_report',
          {'report': myReportClass,}),
        ...
        )

  4. Update the menu structure.
    This step is identical to the general case.

Some further hints

  • For extensive customizations it is best to store the extensions in a seperate directory. This keeps the extensions modular and makes upgrading to new frePPLe releases easier.
    Django supports this very well: you can add a new application which defines the new views and models, and you can override existing templates in an override directory.

  • Developing reports is best done in the source code install. Adding reports to the packaged installation created from the Windows installer is a bit more complex and not recommended.
    • Getting started
    • Modeling guide
      • Simplified domain model
      • Detailed domain model
      • Environment variables
      • Python interpreter
      • Global parameters
      • Buffer
      • Calendar
      • Customer
      • Demand
      • Flow
      • Item
      • Load
      • Location
      • Operation
      • Suboperation
      • Operationplan
      • Problem
      • Resource
      • SetupMatrix
      • Skill
      • Resource skill
      • Solver
      • Extension modules
        • Forecast module
        • REST web service module
        • Linear programming solver module
        • OpenERP connector module
    • User guide
      • Main features
      • Supported browsers
      • Getting around
        • Logging in
        • Logging out
        • Changing password
        • Navigation
          • Menu bar
          • Jump search
          • Context menus
          • Browser bookmarks
        • Filtering data
        • Sorting data
        • Selecting time buckets
        • Exporting data
        • Importing data
        • User preferences
        • User permissions and roles
      • Screens
        • Data input
        • Supply Path / Where Used
        • Comments
        • History – Audit trail
        • Plan analysis
          • Problem report
          • Constraint report
          • Inventory report
          • Inventory detail report
          • Resource report
          • Resource Gantt report
          • Resource detail report
          • Operation report
          • Operation detail report
          • Demand report
          • Demand detail report
          • Demand Gantt report
          • Forecast report
          • Performance indicator report
        • Execute
      • Batch commands
        • manage.py (manage.exe on Windows)
        • frepple (frepple.exe on Windows)
        • freppleservice.exe (Windows only)
    • Installation guide
      • Windows installer
      • Compiling on Windows
      • Linux binary packages
      • Compiling on Linux
      • Compiling on debian-based linux
      • Compiling on Red Hat based Linux
      • Compiling from the subversion source code repository
      • Running the VMWare virtual machine
      • Other platforms
      • Configuring the user interface
      • Configuring multiple models in the user interface
      • Configuring as a Python extension module
    • FAQ
    • Developer guide
      • Code structure
      • Class diagram
      • Solver
        • Solver features
        • Planning algorithm
          • Top level loop
          • Demand solver
          • Buffer solver
          • Flow solver
          • Load solver
          • Operation solver
          • Resource solver
        • Cluster and level algorithm
      • Extension modules
      • Version control
      • Style guide
      • Portability
      • Security
      • Internationalization
      • Translating the user interface
      • Adding or customizing a report
      • Unit tests
        • buffer_procure_1
        • calendar
        • callback
        • cluster
        • constraints_combined_1
        • constraints_combined_2
        • constraints_leadtime_1
        • constraints_material_1
        • constraints_material_2
        • constraints_material_3
        • constraints_material_4
        • constraints_resource_1
        • constraints_resource_2
        • constraints_resource_3
        • constraints_resource_4
        • constraints_resource_5
        • datetime
        • deletion
        • demand_policy
        • flow_alternate_1
        • flow_alternate_2
        • flow_effective
        • forecast_1
        • forecast_2
        • forecast_3
        • forecast_4
        • forecast_5
        • forecast_6
        • jobshop
        • load_alternate
        • load_effective
        • lpsolver_1
        • multithreading
        • name
        • operation_alternate
        • operation_available
        • operation_effective
        • operation_pre_post
        • operation_routing
        • pegging
        • problems
        • python_1
        • python_2
        • python_3
        • safety_stock
        • sample_module
        • scalability_1
        • scalability_2
        • scalability_3
        • setup_1
        • setup_2
        • skill
        • xml
        • xml_remote
    • License
      • GNU Affero General Public License
      • GNU Free Documentation License
    • Third party add-ons
  • Copyright © 2010-2013 frePPLe bvba