DataTables Widget
How to insert a widgetYou can easily insert a DataTable as a widget into any entry.
Click the Insert Widget icon in the toolbar and select "DataTables" in the widgets list.
After filling in the form, click "OK" to insert the widget.
The widget will appear when you save the entry.
The controls at the top of the table offer easy sorting and filtering.
Widget Options
To filter the entries displayed in the table, you can specify one or more entry type names, and a search expression.
For example, to display just task entries, you could specify "task" for the entry type filter; or x(task) for the search expression.
To indicate what columns you'd like to display, you can type the names of the "entry fields" that you want to see. In this example, we're displaying the Traction ID, Title, Submission Date/
The following options are available:
- assigned
- author_last_update
- author_original
- color
- comment_target
- completed
- completion_status
- count_attachments
- count_comments
- count_events
- count_shares
- count_tasks
- count_xrefs_all
- count_xrefs_incoming
- count_xrefs_outgoing
- date_created
- date_lastmodified
- date_sorting
- due
- duration
- estimate
- event_allday
- event_date
- event_duration
- event_end
- event_start
- event_target
- goal
- invitees
- location
- members
- milestone
- moderation_status
- owners
- priority
- project
- share_target
- start
- subscribed
- tags
- task_start_to_completion
- task_start_to_due
- task_target
- tasks_root
- thread_root
- title
- tododone
- tractionid
Table Styles
You can control the visual appearance of the table by selecting one or more styles:
- striped — Alternating row background colors (default)
- border — Borders around each cell
- hover — Highlight rows on mouse hover
- sm — Compact rows with smaller padding
Page Length and Length Menu
- page_length — The default number of rows shown per page (default: 10)
- length_menu — The options available in the "Show entries" drop-down list (default: 10,25,50,100)
Column Control
When Column Control (usedtcc) is enabled, each column header gets a dropdown panel for filtering and sorting. You can choose which items appear in the panel using dtccfields (options: search, spacer, orderAsc, orderDesc, orderClear).
Column Search
When show_columnsearch is enabled (the default), a search box appears below each column header, allowing per-column filtering.
State Save
When state_save is enabled (the default), the DataTable remembers the user's sort order, filter, and page between visits.
Server-Side Processing
When serverside is enabled, paging, global search, and sorting are handled by the server on each request rather than loading all rows at once into the browser. This is recommended for large data sets. See "Server-Side Processing" below.
Export and Display Buttons
- show_export — Show the export buttons (CSV, Excel, PDF, Copy, Print) below the table (default: true)
- show_fullscreen — Show a "Full Screen" button (default: controlled by journal configuration)
- show_newtab — Show an "Open in New Tab" button below the table (default: false)
- pdf_orientation — Portrait or landscape orientation for PDF export (default: portrait)
Sum Footer
sum — Specify a comma-separated list of column index numbers (starting from 0) to show a sum total in the table footer.
For example, sum=2,3 shows the sum of columns 3 and 4. Note: unavailable when show_columnsearch is enabled, as the footer area is used for the column search boxes.
For Developers: DataTables Library
Usage (1) - An example view
Load the "datatables_example" view by entering
/type datatables_example into TeamPage's search box, and pressing enter. Here you can experiment by changing the values of the parameters.Usage (2) - with a Section Title
This plug-in supports showing the results of a section in a DataTable, with HTML and styles similar to those of a section table widget.
To display this widget in an IFRAME, you can invoke the parent.
<com.traction.sdl.datatables.parent#datatable-section id="foo" proj="*" ... />
Usage (3) - without a Section Title
To display a similar widget but without a section title, instead use the "datatable-iframe-div" function, like this:
<com.traction.sdl.datatables.parent#datatable-iframe-div id="foo" proj="*" ... />
Parameters
These functions require the following variables:
- id = An ID to be used for the DataTable, as part of the DOM ID for the IFRAME, its container DIV, etc.
- proj = The names of the spaces for the <entries> tag used in the child page.
- entries_type = The value of type= parameter in <entries> tag in the child page displayed in the iframe.
- fields = Names of the entry fields, displayed as the columns of the DataTable.
The following variables are optional, or may be conditionally required depending upon the value specified by the "entries_type" variable.
- cat = The value of cat= parameter in <entries> tag in the child page displayed in the iframe.
- edate = The value of edate= parameter in <entries> tag in the child page displayed in the iframe.
- search = The value of search= parameter in <entries> tag in the child page displayed in the iframe.
- entrytypesfilter = The value of entrytypesfilter= parameter in <entries> tag in the child page displayed in the iframe.
- max = The value of max= parameter in <entries> tag in the child page displayed in the iframe.
- lang = Used in the child page's <html> tag, as lang="value".
- length_change = Indicates to display the numbers-per-page control in the top-left in the DataTable.
- show_search = Indicates to display the Search Box in the top-right in the DataTable.
- show_info = Indicates to display the Information in the bottom-left in the DataTable.
- paging = Indicates to display the page controls in the bottom-right in the DataTable.
- ordering = Indicates whether the ordering (sort by clicking the heading row) is allowed.
- orderdir = If ordering is allowed, this sets the direction of the ordering. (none/
asc/ desc) - orderidx = If ordering is allowed, this points the index of the base column of ordering. (Starts with 0 from left)
- sdate = The value of sdate= parameter in <entries> tag — start of the date range filter.
- goalid = Filter entries by a goal. Specify the Traction ID of the goal entry (e.
g. SpaceName123). - milestoneid = Filter entries by a milestone. Specify the Traction ID of the milestone entry.
- tractionid = Entry ID(s) to display. Comma-separated. Only used when entries_type=multi.
- fqid = Entry FQID(s) to display. Comma-separated. Only used when entries_type=multi.
- table_styles = Comma-separated list of visual style names applied to the table: striped, border, hover, sm (default: striped).
- page_length = The initial number of rows per page (default: 10).
- length_menu = Comma-separated list of page length options shown in the drop-down (default: 10,25,50,100).
- show_columnsearch = Indicates to display a search box below each column header. Note: hidden automatically in server-side processing mode.
- usedtcc = Indicates whether the Column Control extension is enabled (default: true). Note: in server-side processing mode, sort icons are hidden for columns that do not support server-side sorting.
- dtccfields = Items shown in the Column Control dropdown panel. Options: search, spacer, orderAsc, orderDesc, orderClear (default: all). Note: in server-side processing mode, search and spacer are removed automatically.
- state_save = Indicates whether the DataTable recalls its previous state (sort, filter, page) when the user returns to the page (default: true).
- serverside = Indicates whether server-side processing is enabled. See "Server-Side Processing" below (default: false).
- show_export = Indicates whether the export buttons (CSV, Excel, PDF, Copy, Print) are displayed below the table (default: true).
- show_fullscreen = Indicates whether the "Full Screen" button is displayed below the table (default: controlled by journal configuration).
- show_newtab = Indicates whether the "Open in New Tab" button is displayed below the table (default: false).
- pdf_orientation = The page orientation for PDF export: portrait or landscape (default: portrait).
- sum = Comma-separated column index numbers (0-based from left) for which a sum total is shown in the table footer. Not available when show_columnsearch is enabled.
Server-Side Processing
By default, the DataTable loads all matching entries in a single request and handles paging, searching, and sorting entirely in the browser. For large data sets this can be slow.
When serverside=true, the table fetches only one page of entries per request, and the server handles paging, global text search, and sorting on each interaction.
Limitations in server-side processing mode:
- Sorting: Only the title and date_created columns support server-side sorting. Clicking the header of any other column (such as assigned) has no effect, and sort icons are not shown for those columns.
- Column search: Per-column search boxes (show_columnsearch) are not supported and are hidden automatically.
- Column Control: The search and spacer items in the Column Control dropdown are removed automatically.
When serverside=true, the max parameter is ignored — the server returns exactly the number of rows requested by the DataTable's page length per request.
Attachments:
example_of_the_example_view.png
widget1.png
widget2.png
widget3.png
widget4.png
widgetoption_task.png
widgetoption_entries_type.png
Article: Forum6642 (permalink)
Categories: :Doc:plug-in
Date: June 5, 2016; 4:58:35 PM Eastern Daylight Time
Author Name: Takashi Okutsu
Author ID: takashi
Categories: :Doc:plug-in
Date: June 5, 2016; 4:58:35 PM Eastern Daylight Time
Author Name: Takashi Okutsu
Author ID: takashi