REST-ful tables

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.

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.
  • This simple table can be extended by specifying your own model and column views:
    • 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.