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 customise the table that is 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.

Properties

A number of properties are set by the framework and rarely need to be changed. These have been marked in the following table as auto. Some properties are set with a default value, the default value (and where it is set) is indicated in the table below:

Eden Name	Purpose	Value	Remarks
dataTableSelectable	If set this allows the rows to be selected.	Boolean	This is set up as a property of response.s3
actions	The list of action buttons to be displayed in the first column.	List of actions. Each action is a dictionary values. And consists of the label, the HTML class and the URL. Optionally it may also include a restrict list that restricts these buttons to being displayed to just the ids on the list.	This is set up as a property of response.s3
dataTableID auto	The HTML id that will be used to identify this table	String default value 'list'	Set up using s3mgr.configure in the pre-processing
dataTable_iDisplayLength auto	The number of rows to be displayed on a page	Integer	Confusion... dataTable_iDisplayLength and iDisplayLength
no_sspag auto	This will turn off pagination	Boolean	Pagination is the default and nothing needs to be done to enable it.
sortby	This will do an initial sort on the selected column or columns	list of sorting rules. The sorting rules are a list that comprises of the column number followed by the sort direction	default value [[1,'asc']]
dataTable_sDom auto	This defines where the controls of the DataTable will be positioned	String explained in the DataTables documentation	default value 'fril<"dataTable_table"t>pi' See ​http://www.datatables.net/usage/options for more information
dataTable_sPaginationType	This defines what controls are displayed to allow the user to page through the records	String either 'two_button' or 'full_numbers' default value 'full_numbers'
dataTableDisplay	This can be used to change how a cell displays the text	List of translations. Each translation is a dictionary item and consists of the column number, the value to look for and its replacement
dataTableStyleDisabled	This can be used to give a style to represent disabled text	list of ids to apply this style	This adds the class 'disable' to the tr element
dataTableStyleAlert	This can be used to give a style to represent an alert condition for the row	list of ids to apply this style	This adds the class 'alert' to the tr element
dataTableStyleWarning	This can be used to give a style to represent a warning condition for the row	list of ids to apply this style	This adds the class 'warning' to the tr element

Examples

The following example illustrate how to implement dataTables in your code. It uses the following base code:

Model code snippet:

  resourcename = "csv"
  tablename = module + "_" + resourcename
  table = db.define_table(tablename,
                          Field("name", required=True, notnull=True),
                          Field("path", type="upload", uploadfield=True, required=True, notnull=True),
                          comments(),
                          migrate=migrate,
                          *(s3_timestamp() + s3_uid()))

  table.name.comment = DIV(_class = "tooltip",
                           _title = T("Name") + "|" + T("Enter a name of the CSV you are uploading."))

  s3.crud_strings[tablename]= Storage(
          title_create = T("Upload a CSV file"),
          title_list = T("List of CSV files uploaded"),
          label_list_button = T("List of CSV files"),
          )

Controller code snippet:

def csv():

    """ RESTful Controller """

    module = "importer"
    resourcename = "csv"
    tablename = module + "_" + resourcename
    table = db[tablename]

    def postp(r, output):
        return output

    response.s3.postp = postp
    return s3_rest_controller(module, resourcename)  }}}

This is sufficient to generate a vanilla dataTable as follows:

Adding Buttons

Adding Buttons conditionally

Changing the displayed text

Sorting by a selected column

Filter Rows

Selecting Rows

Highlighting Rows

Highlighting Cells