REST-ful tables - AUI Documentation

Summary

A table whose entities/rows are retrieved, added and updated via rest (CRUD). It uses backbone.js to sync the tables state back to the server and vice versa, avoiding page refreshes.

Status

API status:	general
Web resource key:	`com.atlassian.auiplugin:aui-restfultable`
AMD Module key:	N/A
Experimental API:	3.7.0
General API:	5.8

Working example

An example can be found by running the AUI refapp, and navigating to the restfultable test page

Code

Below is an example table to configure versions for a JIRA project.

ID:status:description:

" + eventName + "

Options

The following options are available when creating a new AJS.RestfulTable.

Required	Name	Description	Type	Default
required option	el	The <table> element	String, HTMLElement, jQuery	None
required option	resources	A map of resources: all - url or function that returns a collection of all table entities self - url to sync entity to server using CRUD	String, Function String	None
required option	columns	An array of columns to render	Array	None
	noEntriesMsg	A message that will be displayed in the table when there are no entries	String	None
	model	Backbone.Model representation used for entities AJS.RestfulTable.EntryModel	AJS.RestfulTable.EntryModel	AJS.RestfulTable.EntryModel
	reverseOrder	When all the entries are retrieved from the "all" resource, reverse the order.	Boolean	false
	autoFocus	Whether or not to auto focus the first field of the create row	Boolean	false
	loadingMsg	A message that will be displayed in the table when it is loading	String	Loading
	allowCreate	Whether or not user can create new entries	Boolean	true
	allowEdit	Whether or not the user can edit table	Boolean	true
	allowReorder	Whether or not the user can reorder rows	Boolean	false
	allowDelete	Whether or not a row can be deleted	Boolean	true
	createPosition	If set to "bottom", creates new rows at the bottom of the table instead of the top.
	id	The id for the table. This id will be used to fire events specific to this instance.
	cancelAccessKey	Sets accesskey attribute
	submitAccessKey	Sets accesskey attribute
	deleteConfirmationCallback	Function returning promise. If promise is resolved row will be deleted, if rejected deletion will be prevented	Function -> Promise

Events

Events have 3 contexts in which they can be triggered.

AJS.RestfulTable

Name	Description	Arguments
AJS.RestfulTable.Events.INITIALIZED	triggered when the table has finished initial render	None
AJS.RestfulTable.Events.ROW_INITIALIZED	triggered when a row is rendered	AJS.RestfulTable.Row
AJS.RestfulTable.Events.ROW_ADDED	triggered when a row is added to the RestfulTable	AJS.RestfulTable.Row
AJS.RestfulTable.Events.ROW_REMOVED	triggered when a row is removed from the RestfulTable	AJS.RestfulTable.Row
AJS.RestfulTable.Events.EDIT_ROW	triggered when a row edit is started by the user	AJS.RestfulTable.EditRow
AJS.RestfulTable.Events.REORDER_SUCCESS	triggered when a successful drag and drop reordering of rows is performed	XmlHttpRequest object
AJS.RestfulTable.Events.SERVER_ERROR	triggered when the server returns a non-200 response for an operation; at the table level, this is mainly drag and drop operations.	Response data XmlHttpRequest object

AJS.RestfulTable.EditRow

Name	Description	Arguments
AJS.RestfulTable.Events.CANCEL	Switches row back to read only mode, restoring values None	None
AJS.RestfulTable.Events.SAVE	Sends updated values back to server and switches back to readonly mode <boolean> - whether to focus read-only view	None
AJS.RestfulTable.Events.CREATED	Triggered when a new entry has been created	None
AJS.RestfulTable.Events.FOCUS	Gives focused style, removing focus from any other row.	<string> - name of field to focus
AJS.RestfulTable.Events.BLUR	Removes focused style, restoring focus back to the createRow	None
AJS.RestfulTable.Events.SUBMIT_STARTED	Triggered when update/create request to server started	None
AJS.RestfulTable.Events.SUBMIT_FINISHED	Triggered when update/create request to server finished	None
AJS.RestfulTable.Events.VALIDATION_ERROR	Triggered when server returns validation errors	Object - errors
AJS.RestfulTable.Events.RENDER	Triggered when row has rendered	None

AJS.RestfulTable.Row

Name	Description	Arguments
AJS.RestfulTable.Events.FOCUS	Gives focused style, removing focus from any other row.	None
AJS.RestfulTable.Events.BLUR	Removes focused style, restoring focus back to the createRow	None
AJS.RestfulTable.Events.UPDATED	Fades row from blue to transparent	None
AJS.RestfulTable.Events.MODAL	Disables all interactions on table, except for this row	None
AJS.RestfulTable.Events.MODELESS	Enables all interactions on table	None
AJS.RestfulTable.Events.RENDER	Triggered when row has rendered	None

Methods

Methods have 3 contexts in which they can be called

AJS.RestfulTable

Name	Description	Arguments	Returns
addRow	Adds row to collection and renders it	<Backbone.Model> model <Integer> index	AJS.RestfulTable
getColumnCount	Gets the number of columns in the table	None	Number
isEmpty	Returns true if there are no entries in the table	None	Boolean
getModels	Gets backbone collection	None	Backbone.Collection
getTable	Gets jQuery element for <table>	None	jQuery
getTableBody	Gets jQuery element for <tbody>	None	jQuery
getCreateRow	Gets view used for create row (first row in table)	None	AJS.RestfulTable.EditRow
showNoEntriesMsg	Shows message options.noEntriesMsg to the user if there are no entries	None	AJS.RestfulTable
removeNoEntriesMsg	Removes message options.noEntriesMsg to the user if there ARE entries	None	AJS.RestfulTable
edit	Converts readonly row to editable view	<String> field - field name to focus AJS.RestfulTable.Row row	AJS.RestfulTable.EditRow

AJS.RestfulTable.EditRow

Name	Description	Arguments	Returns
hasFocus	Returns true if row has focused class	None	Boolean
focus	Focus specified field, first field or the first field with an error (in order)	<String> field - field name to focus	AJS.RestfulTable.EditRow
unfocus	Unfocuses row and disables its submit button	None	AJS.RestfulTable.EditRow
disable	Disables all fields and fades out row	None	AJS.RestfulTable.EditRow
enable	Enables all fields, and returns row to full opacity	None	AJS.RestfulTable.EditRow
showLoading	Shows loading indicator	None	AJS.RestfulTable.EditRow
hideLoading	Hides loading indicator	None	AJS.RestfulTable.EditRow
submit	Serialises form fields and updates client and server model	<Boolean> focusUpdated - flag of whether to focus read-only view after successful submission	AJS.RestfulTable.EditRow

AJS.RestfulTable.Row

Name	Description	Arguments	Returns
sync	Save changed attributes back to server and re-render	<object> attr	AJS.RestfulTable.Row
refresh	Get model from server and re-render	None	AJS.RestfulTable.Row
edit	Switches row into edit mode	None	AJS.RestfulTable.Row
focus	Focuses row	None	AJS.RestfulTable.Row
unfocus	Unfocuses row	None	AJS.RestfulTable.Row
showLoading	Shows loading indicator	None	AJS.RestfulTable.Row
hideLoading	Hides loading indicator	None	AJS.RestfulTable.Row

Setup

For a simple table you need only configure 3 options:

el - The element you wish to populate
resources

all - Rest resource OR function that retrieves all entities
self - Rest resource to sync a single entities state (CRUD)

columns - Which properties of the entities to render. The id of a column maps to the property of an entity.

model - Allows you to modify and format what is sent and received from the server for each entity/row. Also allowing additional logic to be supplied to your views.
column views - Allow you to specify custom renderers for the read/create/edit modes of individual columns.