Documentation

RESTful table

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:experimental
Included in AUI core?Not in core You must explicitly require the web resource key.
Web resource key:com.atlassian.auiplugin:aui-experimental-restfultable
Experimental since:3.7.0

Code

Working example

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

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

/**
 * URLS must follow this pattern
 * create  POST /urlOfRestResource
 * read  GET /urlOfRestResource[/id]
 * update  PUT /urlOfRestResource/id
 * delete  DELETE /urlOfRestResource/id
 */
@Path ("version")
@Consumes ({ MediaType.APPLICATION_JSON })
@Produces ({ MediaType.APPLICATION_JSON })
public class VersionResource
{
 
    @AnonymousAllowed
    @GET
    @Path ("{id}")
    public Response getVersion(@PathParam ("id") final String id)
 
    @PUT
    @Path ("{id}")
    public Response updateVersion(@PathParam ("id") final String id, final VersionBean bean)
 
 
    @POST
    public Response createVersion(final VersionBean bean)
 
    @DELETE
    @Path ("{id}")
    public Response delete(@PathParam ("id") final String id)
}
<table id="project-config-versions-table"></table>
new AJS.RestfulTable({
    autoFocus: true,
    el: jQuery("#project-config-versions-table"),
    allowReorder: true,
    resources: {
        all: "rest/project/HSP/versions?expand=operations",
        self: "rest/version"
    },
    columns: [
        {
            id: "status",
            header: ""
        },
        {
            id: "name",
            header: AJS.I18n.getText("common.words.name")
        },
        {
            id: "description",
            header: AJS.I18n.getText("common.words.description")
        },
        {
            id: "releaseDate",
            header: AJS.I18n.getText("version.releasedate")
        }
    ]
});

Options

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

RequiredNameDescriptionTypeDefault
Success

el

The <table> element

String, HTMLElement, jQuery

None

Success

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

Success

columns

An array of columns to render

{
    id: String, // entity property
    header: String, // &lt;th&gt; contents
    allowEdit: Boolean, // (optional) Can the cell be edited. Default is true.
    fieldName: String, // (optional) name or id of field to focus
    editView: AJS.RestfulTable.CustomEditView, // (optional) view to render when in edit mode
    createView: AJS.RestfulTable.CustomCreateView, // (optional) view to render when in create mode
    readView: AJS.RestfulTable.CustomReadView, // (optional) view to render when in read mode
    emptyText: String, // (optional) text to show when field is empty
}

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

deleteConfirmation

Show confirmation popup before deleting

Boolean

Events

Events have 3 contexts in which they can be triggered.

AJS.RestfulTable

myRestfulTableInstance.bind(AJS.RestfulTable.Events.INITIALIZED, function () {
   alert("finished setup");
});

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.EditRow

var createRow = myRestfulTableInstance.getCreateRow();
createRow.bind(AJS.RestfulTable.Events.VALIDATION_ERROR, function (errors) {
   alert("fix your validation errors before creating new row");
});

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

myRestfulTableInstance.bind(AJS.RestfulTable.Events.ROW_INITIALIZED, function (row) {
    row.bind(AJS.RestfulTable.Events.RENDER, function () {
       this.$el.addClass("myclass");
    });
});

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.EDIT

Switches from readonly to edit mode

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 it's 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 succssful 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 renderes for the read/create/edit modes of individual columns.