wiki:DeveloperGuidelines/DataTables

Version 23 (modified by graeme, 9 years ago) ( diff )

--

Table of Contents

  1. Introduction
  2. Changes

DataTables

Introduction

Sahana Eden uses the JavaScript library DataTables http://www.datatables.net to display results returned from the database. The DataTables library provides a lot of properties and functions that can customise the table that will be produced. Sahana Eden doesn't expose all of the functionality that is available within the DataTables library this makes it easy to get DataTables up and running and it also ensures a consistent look and feel. However, it is possible to customise the DataTables through the Sahana Eden framework.

Changes

This section is being reworked... The Sahana Eden framework will produce a list of resources and put them in a DataTable however sometimes it is necessary to build a table for a specific task or to have multiple tables on the same page. To do this is it necessary to build a controller to manage the table.

Probably the simplest type of table will be one where all the data is sent from the server to the client and no server side pagination is required. This can be set up as follows:

Controller code snippet:

      from s3.s3utils import S3DataTable
      # Set up the resource
      resource = s3db.resource("inv_warehouse")
      # Find out how many records are in the resource
      totalrows = resource.count()
      list_fields = ["id",
                     "name",
                     "organisation_id",
                     ]
      # Get all the data from the resource
      rows = resource.select(list_fields,
                             orderby="organisation_id",
                             start=0,
                             limit=totalrows,
                             )
      if rows:
          # Format the resource data and pass them through their default represent
          data = resource.extract(rows,
                                  list_fields,
                                  represent=True,
                                  )
          # Get the resource fields
          rfields = resource.resolve_selectors(list_fields)[0]
          # Create the default S3DataTable 
          dt = S3DataTable(rfields, data)
          # create default actions buttons for the dataTable
          dt.defaultActionButtons(resource)
          # Create the html for the dataTable
          warehouses = dt.html(totalrows,
                               totalrows,
                               "warehouse_list",
                               dt_pagination="false",
                               )
      else:
          warehouses = "No warehouses exist"

This code gets the rows from the resource and passes the data into the S3DataTable html() function the extra parameter of note is the dt_pagination which when set to 'false' will turn server side pagination off. All the data will be sent to the client and DataTables will manage the filtering a sorting itself.

The next stage is to build a controller that can manage pagination. To do this the controller will need to additionally manage requests from DataTables for more data. This can be set up as follows:

Controller code snippet:

      from s3.s3utils import S3DataTable
      vars = request.get_vars
      resource = s3db.resource("inv_warehouse")
      # When a request is sent from DataTables it sends various information
      # about what data the user has requested, this includes details about
      # records the user wants and any sort or the filter instructions

      # Get the start and end details from dataTables
      start = int(vars.iDisplayStart) if vars.iDisplayStart else 0
      limit = int(vars.iDisplayLength) if vars.iDisplayLength else s3mgr.ROWSPERPAGE
      totalrows = resource.count()
      list_fields = ["id",
                     "name",
                     "organisation_id",
                     ]
      # Get the filter and sort instructions from dataTables
      rfields = resource.resolve_selectors(list_fields)[0]
      (orderby, filter) = S3DataTable.getControlData(rfields, current.request.vars)
      # Now set up the resource filter and find out how many row are in the filtered resource
      resource.add_filter(filter)
      filteredrows = resource.count()
      # Get all the data from the resource
      rows = resource.select(list_fields,
                             orderby="organisation_id",
                             start=start,
                             limit=limit,
                             )
      if rows:
          data = resource.extract(rows,
                                  list_fields,
                                  represent=True,
                                  )
          dt = S3DataTable(rfields, data)
          dt.defaultActionButtons(resource)
          if request.extension == "html":
              # Get the html for the initial call to the dataTable
              warehouses = dt.html(totalrows,
                                   filteredrows,
                                   "warehouse_list",
                                   )
          else:
              # Get any subsequent request for data which will be sent back as json 
              warehouse = dt.json("warehouse_list",
                                  int(vars.sEcho),
                                  totalrows,
                                  filteredrows,
                                  )
              return warehouse
      else:
          warehouses = "No warehouses exist"

Now the controller needs to manage the two standard request extensions for !dataTables: html which is used for the initial table; and !aaData which is used for subsequent calls. When the data is prepared for the !dataTable it needs to know the total rows in the table and the number of rows that are available after filtering, the filter information is returned from !dataTables and the static helper method S3DataTable.getControlData will return the filter and sort information which the user has set up. The json method requires an extra parameter the sEcho which it passes to the server itself. This value just needs to be returned back to the client. Note that the html call no longer requires the dt_pagination parameter.

Attachments (8)

Download all attachments as: .zip

Note: See TracWiki for help on using the wiki.