Changes between Version 23 and Version 24 of DeveloperGuidelines/DataTables


Ignore:
Timestamp:
09/04/12 13:01:47 (9 years ago)
Author:
graeme
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • DeveloperGuidelines/DataTables

    v23 v24  
    11[[TOC]]
    22= !DataTables =
     3'''This page is being reworked...'''
    34== Introduction ==
    45Sahana 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.
    5 == Changes ==
    6 '''This section is being reworked...'''
     6== The Basics ==
    77The 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.
    88
     
    9898            else:
    9999                # Get any subsequent request for data which will be sent back as json
    100                 warehouse = dt.json("warehouse_list",
     100                warehouse = dt.json(totalrows,
     101                                    filteredrows,
     102                                    "warehouse_list",
    101103                                    int(vars.sEcho),
    102                                     totalrows,
    103                                     filteredrows,
    104104                                    )
    105105                return warehouse
     
    108108   }}}
    109109}}}
    110 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.
     110Now 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 now no longer requires the dt_pagination parameter.
     111== Configuring the table ==
     112=== Adding action buttons ===
     113The default buttons can be expanded upon by creating a list of buttons to be added to the table. Each button is defined by a dictionary which describes the button. The dictionary can consist of the following items:
     114||= Item Name =||= Description =||
     115|| label || The name that will appear on the button ||
     116|| _class || The class used to display the button, typically use "action-btn" for text and "action-icon" for icons ||
     117|| url || The url which will be used when the button is pressed. Use "[id]" for substituting the id of the record ||
     118|| icon || Optionsal, the icon to be used in place of text ||
     119{{{
     120#!div style="font-size: 80%"
     121Controller code snippet:
     122  {{{#!python
     123        from s3.s3utils import S3DataTable
     124        vars = request.get_vars
     125        resource = s3db.resource("inv_warehouse")
     126        start = int(vars.iDisplayStart) if vars.iDisplayStart else 0
     127        limit = int(vars.iDisplayLength) if vars.iDisplayLength else s3mgr.ROWSPERPAGE
     128        totalrows = resource.count()
     129        list_fields = ["id",
     130                       "name",
     131                       "organisation_id",
     132                       ]
     133        rfields = resource.resolve_selectors(list_fields)[0]
     134        (orderby, filter) = S3DataTable.getControlData(rfields, current.request.vars)
     135        resource.add_filter(filter)
     136        filteredrows = resource.count()
     137        rows = resource.select(list_fields,
     138                               orderby="organisation_id",
     139                               start=start,
     140                               limit=limit,
     141                               )
     142        if rows:
     143            data = resource.extract(rows,
     144                                    list_fields,
     145                                    represent=True,
     146                                    )
     147            dt = S3DataTable(rfields, data)
     148            dt.defaultActionButtons(resource)
     149            if request.extension == "html":
     150                custom_actions = [dict(label=str(T("Stock")),
     151                                  _class="action-btn",
     152                                  url=URL(c="inv", f="warehouse",
     153                                          args=["[id]", "inv_item"]
     154                                          )
     155                                  ),
     156                                 ]
     157                dt.defaultActionButtons(resource, custom_actions)
     158                warehouses = dt.html(totalrows,
     159                                     filteredrows,
     160                                     "warehouse_list",
     161                                     )
     162            else:
     163                warehouse = dt.json(totalrows,
     164                                    filteredrows,
     165                                    "warehouse_list",
     166                                    int(request.vars.sEcho),
     167                                    )
     168                return warehouse
     169        else:
     170            warehouses = "No warehouses exist"
     171   }}}
     172}}}