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.

Required	Name	Description	Type	Default
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, // <th> 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.