ToasterTable - Revision history

Michael Wood at 17:15, 17 May 2016

2016-05-17T17:15:19Z

← Older revision		Revision as of 17:15, 17 May 2016
Line 1:		Line 1:
	[[Category:Toaster]]		[[Category:Toaster]]

	== Introduction to ToasterTable ==		== Introduction to ToasterTable ==

Michael Wood at 17:15, 17 May 2016

2016-05-17T17:15:04Z

← Older revision		Revision as of 17:15, 17 May 2016
Line 1:		Line 1:
			[[Category:Toaster]]

	== Introduction to ToasterTable ==		== Introduction to ToasterTable ==

Elliot Smith at 15:29, 5 April 2016

2016-04-05T15:29:52Z

Elliot Smith at 15:28, 5 April 2016

2016-04-05T15:28:48Z

← Older revision		Revision as of 15:28, 5 April 2016
Line 525:		Line 525:
	* 'successful_builds' is the name of the action. This is used to map from the filter parameter in the querystring (see the next section).		* 'successful_builds' is the name of the action. This is used to map from the filter parameter in the querystring (see the next section).
	* 'Successful builds' is the label shown next to the radio button which activates this action in the popup.		* 'Successful builds' is the label shown next to the radio button which activates this action in the popup.
	* Q(outcome=Build.SUCCEEDED) shows the criteria used to filter the records in the table's queryset when the filter action is applied. The Q object is part of the Django API; it should reference field names which are present in the queryset to be filtered and can use any criteria available to Q objects. In the case of the MiniBuildsTable, the queryset consists of Build objects; the Q(outcome=Build.SUCCEEDED) object is used to filter this queryset, so we effectively get the result of Build.objects.all().filter(Q(outcome=Build.SUCCEEDED)) when the action is applied.		* Q(outcome=Build.SUCCEEDED) shows the criteria used to filter the records in the table's queryset when the filter action is applied. The [https://docs.djangoproject.com/en/1.9/topics/db/queries/#complex-lookups-with-q Q object] is part of the Django API; it should reference field names which are present in the queryset to be filtered and can use any criteria available to Q objects. In the case of the MiniBuildsTable, the queryset consists of Build objects; the Q(outcome=Build.SUCCEEDED) object is used to filter this queryset, so we effectively get the result of Build.objects.all().filter(Q(outcome=Build.SUCCEEDED)) when the action is applied.

	For examples of how to add TableFilterActionDay and TableFilterActionDateRange filter actions, see the BuildsTable class in tables.py.		For examples of how to add TableFilterActionDay and TableFilterActionDateRange filter actions, see the BuildsTable class in tables.py.

Elliot Smith at 15:27, 5 April 2016

2016-04-05T15:27:38Z

Elliot Smith at 15:26, 5 April 2016

2016-04-05T15:26:38Z

← Older revision		Revision as of 15:26, 5 April 2016
Line 1:		Line 1:
	~~'''*****This is a WIP*****'''~~

	== Introduction to ToasterTable ==		== Introduction to ToasterTable ==

Line 546:		Line 544:
	* The dialog is opened so the user can choose a filter to apply. The user clicks radio buttons, fills in fields etc.		* The dialog is opened so the user can choose a filter to apply. The user clicks radio buttons, fills in fields etc.
	* When the user clicks on the "Apply" button, the URL for the page is modified in place to reflect the filter criteria. The filter is represented in the URL by two querystring parameters:		* When the user clicks on the "Apply" button, the URL for the page is modified in place to reflect the filter criteria. The filter is represented in the URL by two querystring parameters:
	** <code>filter=<filter name>:<filter action></code> : the filter name maps to the name used when creating the TableFilter object; and the filter action corresponds to one of the names of a TableFilterAction object added to the TableFilter. For example, filter=outcome_filter:successful_builds will map to the outcome_filter TableFilter, and its successful_builds TableFilterAction.		** <code>filter=<filter name>:<filter action></code> : the filter name maps to the name used when creating the TableFilter object; and the filter action corresponds to one of the names of a TableFilterAction object added to the TableFilter. For example, ''filter=outcome_filter:successful_builds'' will map to the ''outcome_filter'' TableFilter and its ''successful_builds'' TableFilterAction.
	** <code>filter_value=<filter value string></code> : for a TableFilterActionToggle filter, this is always "on", to show that the filter is applied; for a TableFilterActionDay this is either "today" or "yesterday"; for a TableFilterActionDateRange, this is a "from,to" date range in the format "2015-12-09,2015-12-11".		** <code>filter_value=<filter value string></code> : for a TableFilterActionToggle filter, this is always "on", to show that the filter is applied; for a TableFilterActionDay this is either "today" or "yesterday"; for a TableFilterActionDateRange, this is a "from,to" date range in the format "2015-12-09,2015-12-11".
	* The table data is fetched via Ajax, using the filter and filter_value parameters as part of the URL. These set the filter name, action and value to use for filtering.		* The table data is fetched via Ajax, using the filter and filter_value parameters as part of the URL. These set the filter name, action and value to use for filtering.

Elliot Smith at 15:25, 5 April 2016

2016-04-05T15:25:43Z

← Older revision		Revision as of 15:25, 5 April 2016
Line 546:		Line 546:
	* The dialog is opened so the user can choose a filter to apply. The user clicks radio buttons, fills in fields etc.		* The dialog is opened so the user can choose a filter to apply. The user clicks radio buttons, fills in fields etc.
	* When the user clicks on the "Apply" button, the URL for the page is modified in place to reflect the filter criteria. The filter is represented in the URL by two querystring parameters:		* When the user clicks on the "Apply" button, the URL for the page is modified in place to reflect the filter criteria. The filter is represented in the URL by two querystring parameters:
	** filter=~~<~~filter name~~>~~:~~<~~filter action~~>~~ : the filter name maps to the name used when creating the TableFilter object; and the filter action corresponds to one of the names of a TableFilterAction object added to the TableFilter. For example, filter=outcome_filter:successful_builds will map to the outcome_filter TableFilter, and its successful_builds TableFilterAction.		** <code>filter=<filter name>:<filter action></code> : the filter name maps to the name used when creating the TableFilter object; and the filter action corresponds to one of the names of a TableFilterAction object added to the TableFilter. For example, filter=outcome_filter:successful_builds will map to the outcome_filter TableFilter, and its successful_builds TableFilterAction.
	** filter_value=~~<~~filter value string~~>~~ : for a TableFilterActionToggle filter, this is always "on", to show that the filter is applied; for a TableFilterActionDay this is either "today" or "yesterday"; for a TableFilterActionDateRange, this is a "from,to" date range in the format "2015-12-09,2015-12-11".		** <code>filter_value=<filter value string></code> : for a TableFilterActionToggle filter, this is always "on", to show that the filter is applied; for a TableFilterActionDay this is either "today" or "yesterday"; for a TableFilterActionDateRange, this is a "from,to" date range in the format "2015-12-09,2015-12-11".
	* The table data is fetched via Ajax, using the filter and filter_value parameters as part of the URL. These set the filter name, action and value to use for filtering.		* The table data is fetched via Ajax, using the filter and filter_value parameters as part of the URL. These set the filter name, action and value to use for filtering.
	* The back-end applies the requested filter action to the queryset (as well as any existing search string). Each filter action has a set of criteria which it applies to the queryset, as follows:		* The back-end applies the requested filter action to the queryset (as well as any existing search string). Each filter action has a set of criteria which it applies to the queryset, as follows:

Elliot Smith at 15:24, 5 April 2016

2016-04-05T15:24:51Z

← Older revision		Revision as of 15:24, 5 April 2016
Line 76:		Line 76:
	The self.default_orderby member set in __init__() specifies the default column to use for ordering the table. In this case, the completed_on field is used to sort the builds in the table; the "-" specifies reverse order, so the newest build appears at the top of the table. Note that the value for self.default_orderby should match the name of a field in the model, and the name of a column added to the table.		The self.default_orderby member set in __init__() specifies the default column to use for ordering the table. In this case, the completed_on field is used to sort the builds in the table; the "-" specifies reverse order, so the newest build appears at the top of the table. Note that the value for self.default_orderby should match the name of a field in the model, and the name of a column added to the table.

	See the [~~???adding more columns~~] section for full details of the column options available.		See the [#Column options] section for full details of the column options available.

	=== Add the template ===		=== Add the template ===
Line 164:		Line 164:
	* '''static_data_template''' (string; optional): The template to render for each row; the data for the row is interpolated into the template. This is more flexible than field_name, as you can add links, conditional statements and additional formatting each time the cell for this column is rendered for a record.		* '''static_data_template''' (string; optional): The template to render for each row; the data for the row is interpolated into the template. This is more flexible than field_name, as you can add links, conditional statements and additional formatting each time the cell for this column is rendered for a record.
	* '''orderable''' (boolean; default=False): True if the table can be ordered by this column. Note that if this is True, either field_name or static_data_name should match a name of one of the fields in the queryset for the ToasterTable. If not, Toaster will not be able to sort the table by that column.		* '''orderable''' (boolean; default=False): True if the table can be ordered by this column. Note that if this is True, either field_name or static_data_name should match a name of one of the fields in the queryset for the ToasterTable. If not, Toaster will not be able to sort the table by that column.
	* '''filter_name''' (string; optional): Name of the TableFilter associated with this column, which adds filtering behaviour for this column; see the [~~???~~Filter API] section for full details.		* '''filter_name''' (string; optional): Name of the TableFilter associated with this column, which adds filtering behaviour for this column; see the [#Filter API] section for full details.

	As an example, I'll add two columns to the Mini Builds table.		As an example, I'll add two columns to the Mini Builds table.
Line 460:		Line 460:
	[[File:MiniBuildsTable-outcomefilter.png\|750px\|Adding an outcome filter to the MiniBuildsTable]]		[[File:MiniBuildsTable-outcomefilter.png\|750px\|Adding an outcome filter to the MiniBuildsTable]]

	outcome_filter is the string used to refer to the filter in the querystring; see the section [How filters are applied] for more details about how filters are applied.		outcome_filter is the string used to refer to the filter in the querystring; see the section [#How filters are applied] for more details about how filters are applied.

	=== Add table filter actions ===		=== Add table filter actions ===
Line 550:		Line 550:
	* The table data is fetched via Ajax, using the filter and filter_value parameters as part of the URL. These set the filter name, action and value to use for filtering.		* The table data is fetched via Ajax, using the filter and filter_value parameters as part of the URL. These set the filter name, action and value to use for filtering.
	* The back-end applies the requested filter action to the queryset (as well as any existing search string). Each filter action has a set of criteria which it applies to the queryset, as follows:		* The back-end applies the requested filter action to the queryset (as well as any existing search string). Each filter action has a set of criteria which it applies to the queryset, as follows:
	** TableFilterActionToggle: ~~the~~ recordset is filtered by ~~a ???~~		** TableFilterActionToggle: The recordset is filtered by the criteria specified when the action is created (see [#Add table filter actions] for an example).
			** TableFilterActionDay: A date range clause is constructed at the time the filter action is applied. For example, if the field the filter action applies to is "completed_on", the day set for the TableFilterActionDay is "today", and today is 2016-03-05, the query clause (in pseudo-SQL) is "completed_on >= '2016-03-04 00:00:00' AND completed_on <= '2016-03-04 23:59:59'".
			** TableFilterActionDateRange: This is similar to TableFilterActionDay, but the user specifies the start and end dates; these are in the filter_value variable in the querystring. For example, if the field the filter action applies to is "completed_on" and the date range is "2016-03-01,2016-03-04", the query clause (in pseudo-SQL) is "completed_on >= '2016-03-01 00:00:00' AND completed_on <= '2016-03-04 23:59:59'".
	* The filtered queryset is returned as JSON.		* The filtered queryset is returned as JSON.
	* The Toaster UI code redraws the table with the filtered queryset.		* The Toaster UI code redraws the table with the filtered queryset.

Elliot Smith at 14:26, 5 April 2016

2016-04-05T14:26:46Z

← Older revision		Revision as of 14:26, 5 April 2016
Line 550:		Line 550:
	* The table data is fetched via Ajax, using the filter and filter_value parameters as part of the URL. These set the filter name, action and value to use for filtering.		* The table data is fetched via Ajax, using the filter and filter_value parameters as part of the URL. These set the filter name, action and value to use for filtering.
	* The back-end applies the requested filter action to the queryset (as well as any existing search string). Each filter action has a set of criteria which it applies to the queryset, as follows:		* The back-end applies the requested filter action to the queryset (as well as any existing search string). Each filter action has a set of criteria which it applies to the queryset, as follows:
	** TableFilterActionToggle: the recordset is filtered by		** TableFilterActionToggle: the recordset is filtered by a ???
	* The filtered queryset is returned as JSON.		* The filtered queryset is returned as JSON.
	* The Toaster UI code redraws the table with the filtered queryset.		* The Toaster UI code redraws the table with the filtered queryset.

Elliot Smith at 14:23, 5 April 2016

2016-04-05T14:23:36Z

← Older revision		Revision as of 14:23, 5 April 2016
Line 474:		Line 474:
	In the case of TableFilterActionDay and TableFilterActionDateRange, you specify the field which is used for the filter action. In the case of TableFilterActionToggle, you can use arbitrary criteria for the action.		In the case of TableFilterActionDay and TableFilterActionDateRange, you specify the field which is used for the filter action. In the case of TableFilterActionToggle, you can use arbitrary criteria for the action.

	To add an action to a filter, create an instance of the desired action class and use the TableFilter.add_action() method to associate it with a filter. For example, here's how to add two actions to the outcome_filter defined earlier; one to show successful builds, and the other to show failed builds:		To add an action to a filter, create an instance of the desired action class and use the TableFilter.add_action() method to associate it with a filter. For example, here's how to add two actions to the outcome_filter defined earlier: one to show successful builds, and the other to show failed builds:

	<pre>		<pre>
Line 514:		Line 514:
	[[File:MiniBuildsTable-outcomefilteractions.png\|750px\|Adding outcome filter actions to the MiniBuildsTable]]		[[File:MiniBuildsTable-outcomefilteractions.png\|750px\|Adding outcome filter actions to the MiniBuildsTable]]

	I'll break this down further to give ~~some~~ detail about how the filter action is created. Here's the code which creates the filter action to show successful builds only:		I'll break this down further to give a bit more detail about how the filter action is created. Here's the code which creates the filter action to show successful builds only:

	<pre>		<pre>
Line 525:		Line 525:

	The arguments to TableFilterActionToggle have the following meanings:		The arguments to TableFilterActionToggle have the following meanings:
	* 'successful_builds' is the name of the action. This is used to map from the filter parameter in the querystring.		* 'successful_builds' is the name of the action. This is used to map from the filter parameter in the querystring (see the next section).
	* 'Successful builds' is the label shown next to the radio button which activates this action in the popup.		* 'Successful builds' is the label shown next to the radio button which activates this action in the popup.
	* Q(outcome=Build.SUCCEEDED) shows the criteria used to filter the records in the table's queryset when the filter action is applied.		* Q(outcome=Build.SUCCEEDED) shows the criteria used to filter the records in the table's queryset when the filter action is applied. The Q object is part of the Django API; it should reference field names which are present in the queryset to be filtered and can use any criteria available to Q objects. In the case of the MiniBuildsTable, the queryset consists of Build objects; the Q(outcome=Build.SUCCEEDED) object is used to filter this queryset, so we effectively get the result of Build.objects.all().filter(Q(outcome=Build.SUCCEEDED)) when the action is applied.

			For examples of how to add TableFilterActionDay and TableFilterActionDateRange filter actions, see the BuildsTable class in tables.py.

	The next section explains how we go from clicking on a radio button in the filter popup to filtering the records shown in the table.		The next section explains how we go from clicking on a radio button in the filter popup to filtering the records shown in the table.
Line 535:		Line 537:
	The short version:		The short version:

	When a ToasterTable is rendered, a filter icon is shown on any column which has a filter_name defined for it. Clicking on this icon populates the filter dialog, then opens it so the user can select a filter to apply. When the user clicks on the "Apply" button in the dialog, the ~~page~~ is requested ~~with~~ the filter name, filter action, and filter value in the querystring. These parameters are ~~then~~ used to filter the records shown in the table.		When a ToasterTable is rendered, a filter icon is shown on any column which has a filter_name defined for it. Clicking on this icon populates the filter dialog, then opens it so the user can select a filter to apply. When the user clicks on the "Apply" button in the dialog, new data for the table is requested, using the filter name, filter action, and filter value from the querystring. These parameters are used to filter the records which are shown in the table.

	The long version:		The long version:

	* ~~Each~~ filter icon has a filter name associated with it.		* A filter icon for a column has a filter name associated with it.
	* When a filter icon is clicked, the Toaster UI makes an Ajax request to the Toaster back-end for data about that filter name.		* When a filter icon is clicked, the Toaster UI makes an Ajax request to the Toaster back-end for data about that filter name.
	* When the filter data is received (in JSON format), the filter dialog is populated with radio buttons (one per action), labels (one per action) and any additional fields (e.g. date range fields for TableFilterActionDateRange actions). The count of records which will be returned by ~~that~~ action is part of the data returned by the ~~server~~; if this is 0, the label and radio button are disabled. See static/js/table.js for the code which populates the filter dialog.		* When the filter data is received (in JSON format), the filter dialog is populated with radio buttons (one per action), labels (one per action) and any additional fields (e.g. date range fields for TableFilterActionDateRange actions). The count of records which will be returned by an action is part of the data returned by the back-end; if this is 0, the label and radio button are disabled. See static/js/table.js for the code which populates the filter dialog.
	* The dialog is opened so the user can choose a filter to apply. The user clicks radio buttons, fills in fields etc.		* The dialog is opened so the user can choose a filter to apply. The user clicks radio buttons, fills in fields etc.
	* When the user clicks on the "Apply" button, the URL for the page is modified in place to reflect the filter criteria. The filter is represented in the URL by two querystring parameters:		* When the user clicks on the "Apply" button, the URL for the page is modified in place to reflect the filter criteria. The filter is represented in the URL by two querystring parameters:
Line 547:		Line 549:
	** filter_value=<filter value string> : for a TableFilterActionToggle filter, this is always "on", to show that the filter is applied; for a TableFilterActionDay this is either "today" or "yesterday"; for a TableFilterActionDateRange, this is a "from,to" date range in the format "2015-12-09,2015-12-11".		** filter_value=<filter value string> : for a TableFilterActionToggle filter, this is always "on", to show that the filter is applied; for a TableFilterActionDay this is either "today" or "yesterday"; for a TableFilterActionDateRange, this is a "from,to" date range in the format "2015-12-09,2015-12-11".
	* The table data is fetched via Ajax, using the filter and filter_value parameters as part of the URL. These set the filter name, action and value to use for filtering.		* The table data is fetched via Ajax, using the filter and filter_value parameters as part of the URL. These set the filter name, action and value to use for filtering.
	* The back-end applies the requested filter to the queryset (as well as any existing search string) ~~and returns~~ it as JSON.		* The back-end applies the requested filter action to the queryset (as well as any existing search string). Each filter action has a set of criteria which it applies to the queryset, as follows:
			** TableFilterActionToggle: the recordset is filtered by
			* The filtered queryset is returned as JSON.
	* The Toaster UI code redraws the table with the filtered queryset.		* The Toaster UI code redraws the table with the filtered queryset.

← Older revision		Revision as of 15:29, 5 April 2016
Line 74:		Line 74:
	The self.default_orderby member set in __init__() specifies the default column to use for ordering the table. In this case, the completed_on field is used to sort the builds in the table; the "-" specifies reverse order, so the newest build appears at the top of the table. Note that the value for self.default_orderby should match the name of a field in the model, and the name of a column added to the table.		The self.default_orderby member set in __init__() specifies the default column to use for ordering the table. In this case, the completed_on field is used to sort the builds in the table; the "-" specifies reverse order, so the newest build appears at the top of the table. Note that the value for self.default_orderby should match the name of a field in the model, and the name of a column added to the table.

	See the [[#Column options]] section for full details of the column options available.		See the [[#Column options\|Column options]] section for full details of the column options available.

	=== Add the template ===		=== Add the template ===
Line 162:		Line 162:
	* '''static_data_template''' (string; optional): The template to render for each row; the data for the row is interpolated into the template. This is more flexible than field_name, as you can add links, conditional statements and additional formatting each time the cell for this column is rendered for a record.		* '''static_data_template''' (string; optional): The template to render for each row; the data for the row is interpolated into the template. This is more flexible than field_name, as you can add links, conditional statements and additional formatting each time the cell for this column is rendered for a record.
	* '''orderable''' (boolean; default=False): True if the table can be ordered by this column. Note that if this is True, either field_name or static_data_name should match a name of one of the fields in the queryset for the ToasterTable. If not, Toaster will not be able to sort the table by that column.		* '''orderable''' (boolean; default=False): True if the table can be ordered by this column. Note that if this is True, either field_name or static_data_name should match a name of one of the fields in the queryset for the ToasterTable. If not, Toaster will not be able to sort the table by that column.
	* '''filter_name''' (string; optional): Name of the TableFilter associated with this column, which adds filtering behaviour for this column; see the [[#Filter API]] section for full details.		* '''filter_name''' (string; optional): Name of the TableFilter associated with this column, which adds filtering behaviour for this column; see the [[#Filter API\|Filter API]] section for full details.

	As an example, I'll add two columns to the Mini Builds table.		As an example, I'll add two columns to the Mini Builds table.
Line 458:		Line 458:
	[[File:MiniBuildsTable-outcomefilter.png\|750px\|Adding an outcome filter to the MiniBuildsTable]]		[[File:MiniBuildsTable-outcomefilter.png\|750px\|Adding an outcome filter to the MiniBuildsTable]]

	outcome_filter is the string used to refer to the filter in the querystring; see the section [[#How filters are applied]] for more details about how filters are applied.		outcome_filter is the string used to refer to the filter in the querystring; see the section [[#How filters are applied\|How filters are applied]] for more details about how filters are applied.

	=== Add table filter actions ===		=== Add table filter actions ===
Line 548:		Line 548:
	* The table data is fetched via Ajax, using the filter and filter_value parameters as part of the URL. These set the filter name, action and value to use for filtering.		* The table data is fetched via Ajax, using the filter and filter_value parameters as part of the URL. These set the filter name, action and value to use for filtering.
	* The back-end applies the requested filter action to the queryset (as well as any existing search string). Each filter action has a set of criteria which it applies to the queryset, as follows:		* The back-end applies the requested filter action to the queryset (as well as any existing search string). Each filter action has a set of criteria which it applies to the queryset, as follows:
	** TableFilterActionToggle: The recordset is filtered by the criteria specified when the action is created (see [[#Add table filter actions]] for an example).		** TableFilterActionToggle: The recordset is filtered by the criteria specified when the action is created (see [[#Add table filter actions\|Add table filter actions]] for an example).
	** TableFilterActionDay: A date range clause is constructed at the time the filter action is applied. For example, if the field the filter action applies to is "completed_on", the day set for the TableFilterActionDay is "today", and today is 2016-03-05, the query clause (in pseudo-SQL) is "completed_on >= '2016-03-04 00:00:00' AND completed_on <= '2016-03-04 23:59:59'".		** TableFilterActionDay: A date range clause is constructed at the time the filter action is applied. For example, if the field the filter action applies to is "completed_on", the day set for the TableFilterActionDay is "today", and today is 2016-03-05, the query clause (in pseudo-SQL) is "completed_on >= '2016-03-04 00:00:00' AND completed_on <= '2016-03-04 23:59:59'".
	** TableFilterActionDateRange: This is similar to TableFilterActionDay, but the user specifies the start and end dates; these are in the filter_value variable in the querystring. For example, if the field the filter action applies to is "completed_on" and the date range is "2016-03-01,2016-03-04", the query clause (in pseudo-SQL) is "completed_on >= '2016-03-01 00:00:00' AND completed_on <= '2016-03-04 23:59:59'".		** TableFilterActionDateRange: This is similar to TableFilterActionDay, but the user specifies the start and end dates; these are in the filter_value variable in the querystring. For example, if the field the filter action applies to is "completed_on" and the date range is "2016-03-01,2016-03-04", the query clause (in pseudo-SQL) is "completed_on >= '2016-03-01 00:00:00' AND completed_on <= '2016-03-04 23:59:59'".
	* The filtered queryset is returned as JSON.		* The filtered queryset is returned as JSON.
	* The Toaster UI code redraws the table with the filtered queryset.		* The Toaster UI code redraws the table with the filtered queryset.

← Older revision		Revision as of 15:27, 5 April 2016
Line 74:		Line 74:
	The self.default_orderby member set in __init__() specifies the default column to use for ordering the table. In this case, the completed_on field is used to sort the builds in the table; the "-" specifies reverse order, so the newest build appears at the top of the table. Note that the value for self.default_orderby should match the name of a field in the model, and the name of a column added to the table.		The self.default_orderby member set in __init__() specifies the default column to use for ordering the table. In this case, the completed_on field is used to sort the builds in the table; the "-" specifies reverse order, so the newest build appears at the top of the table. Note that the value for self.default_orderby should match the name of a field in the model, and the name of a column added to the table.

	See the [#Column options] section for full details of the column options available.		See the [[#Column options]] section for full details of the column options available.

	=== Add the template ===		=== Add the template ===
Line 162:		Line 162:
	* '''static_data_template''' (string; optional): The template to render for each row; the data for the row is interpolated into the template. This is more flexible than field_name, as you can add links, conditional statements and additional formatting each time the cell for this column is rendered for a record.		* '''static_data_template''' (string; optional): The template to render for each row; the data for the row is interpolated into the template. This is more flexible than field_name, as you can add links, conditional statements and additional formatting each time the cell for this column is rendered for a record.
	* '''orderable''' (boolean; default=False): True if the table can be ordered by this column. Note that if this is True, either field_name or static_data_name should match a name of one of the fields in the queryset for the ToasterTable. If not, Toaster will not be able to sort the table by that column.		* '''orderable''' (boolean; default=False): True if the table can be ordered by this column. Note that if this is True, either field_name or static_data_name should match a name of one of the fields in the queryset for the ToasterTable. If not, Toaster will not be able to sort the table by that column.
	* '''filter_name''' (string; optional): Name of the TableFilter associated with this column, which adds filtering behaviour for this column; see the [#Filter API] section for full details.		* '''filter_name''' (string; optional): Name of the TableFilter associated with this column, which adds filtering behaviour for this column; see the [[#Filter API]] section for full details.

	As an example, I'll add two columns to the Mini Builds table.		As an example, I'll add two columns to the Mini Builds table.
Line 458:		Line 458:
	[[File:MiniBuildsTable-outcomefilter.png\|750px\|Adding an outcome filter to the MiniBuildsTable]]		[[File:MiniBuildsTable-outcomefilter.png\|750px\|Adding an outcome filter to the MiniBuildsTable]]

	outcome_filter is the string used to refer to the filter in the querystring; see the section [#How filters are applied] for more details about how filters are applied.		outcome_filter is the string used to refer to the filter in the querystring; see the section [[#How filters are applied]] for more details about how filters are applied.

	=== Add table filter actions ===		=== Add table filter actions ===
Line 548:		Line 548:
	* The table data is fetched via Ajax, using the filter and filter_value parameters as part of the URL. These set the filter name, action and value to use for filtering.		* The table data is fetched via Ajax, using the filter and filter_value parameters as part of the URL. These set the filter name, action and value to use for filtering.
	* The back-end applies the requested filter action to the queryset (as well as any existing search string). Each filter action has a set of criteria which it applies to the queryset, as follows:		* The back-end applies the requested filter action to the queryset (as well as any existing search string). Each filter action has a set of criteria which it applies to the queryset, as follows:
	** TableFilterActionToggle: The recordset is filtered by the criteria specified when the action is created (see [#Add table filter actions] for an example).		** TableFilterActionToggle: The recordset is filtered by the criteria specified when the action is created (see [[#Add table filter actions]] for an example).
	** TableFilterActionDay: A date range clause is constructed at the time the filter action is applied. For example, if the field the filter action applies to is "completed_on", the day set for the TableFilterActionDay is "today", and today is 2016-03-05, the query clause (in pseudo-SQL) is "completed_on >= '2016-03-04 00:00:00' AND completed_on <= '2016-03-04 23:59:59'".		** TableFilterActionDay: A date range clause is constructed at the time the filter action is applied. For example, if the field the filter action applies to is "completed_on", the day set for the TableFilterActionDay is "today", and today is 2016-03-05, the query clause (in pseudo-SQL) is "completed_on >= '2016-03-04 00:00:00' AND completed_on <= '2016-03-04 23:59:59'".
	** TableFilterActionDateRange: This is similar to TableFilterActionDay, but the user specifies the start and end dates; these are in the filter_value variable in the querystring. For example, if the field the filter action applies to is "completed_on" and the date range is "2016-03-01,2016-03-04", the query clause (in pseudo-SQL) is "completed_on >= '2016-03-01 00:00:00' AND completed_on <= '2016-03-04 23:59:59'".		** TableFilterActionDateRange: This is similar to TableFilterActionDay, but the user specifies the start and end dates; these are in the filter_value variable in the querystring. For example, if the field the filter action applies to is "completed_on" and the date range is "2016-03-01,2016-03-04", the query clause (in pseudo-SQL) is "completed_on >= '2016-03-01 00:00:00' AND completed_on <= '2016-03-04 23:59:59'".
	* The filtered queryset is returned as JSON.		* The filtered queryset is returned as JSON.
	* The Toaster UI code redraws the table with the filtered queryset.		* The Toaster UI code redraws the table with the filtered queryset.