CRUD Basics

The CRUD (Create, Read, Update, Delete) model is a common pattern developers use to interface with data on the server-side. By utilizing a URL based REST (Representational State Transfer) endpoint, users can manipulate data on the server by making simple HTTP requests to a URL (so long as those requests follow a certain pattern).

ZingGrid utilizes this REST pattern to automatically perform CRUD actions on a given endpoint for you whenever a user manipulates a grid.

To make setup quick and easy, ZingGrid has enabled some default behaviors for CRUD grids based on some common REST API configurations (but you can always extend or override these behaviors to best suit your needs).

Enable CRUD

To allow users to perform CRUD actions on your grid, you need to add two attributes: src and editor-controls. The src attribute sets the endpoint you'd like the grid to use and the editor-controls is a boolean to let the grid know you want all CRUD actions enabled. ZingGrid will then automatically set up the GET, POST, PUT and DELETE requests to your endpoint when defining these two attributes. (You can override this default behavior).

When your grid makes a POST request to create a new row, make sure that your API responds with an object containing the id of the newly created row. The key for this value in the object must correspond to any idKey you have specified (by default this is just id). For example, if you have not specified an idKey and the id of your new row is 5, then you might return { id: 5 }.

An example grid using src and editor-controls might look like the following:

<zing-grid
  src="https://zinggrid-rest-example-datasets.glitch.me/comments"
  editor-controls>
</zing-grid>

To create a more full, interactive example, we'll add on a few extra attributes (see below). More information on each attribute can be viewed on the <zing-grid> page.

<zing-grid
  src="https://zinggrid-rest-example-datasets.glitch.me/comments"
  caption="CRUD Endpoint"
  editor-controls
  pager
  page-size="5"
  layout="row">
</zing-grid>

CRUD Enabled Grid

Here is our complete grid with CRUD capabilities:

CRUD Defaults

The table below lists the default HTTP methods used for each CRUD action, as well as the expected response code. For example, creating a row will send an HTTP request with the POST method; an HTTP response a code of 200-299 is expected upon a successful insertion of the data and a code of ≥400 is expected upon a failed insertion. Along with this response code, one of three things is expected in the response body: the entire dataset, the single record that was just inserted, or just the ID of the new record that was inserted.

Override Defaults

To override any of the default actions, you will need to use the <zg-param> element. Within the main <zing-grid> element, add one <zg-param> element for each of the CRUD actions you'd like to modify. Each param element will take two attributes: name and value.

The name attribute lets you specify which of the four CRUD actions you will be modifying. To select one of the actions, simply use one of the following four values: createOptions, readOptions, updateOptions, or deleteOptions.

The value attribute lets you specify what changes you'd like to make to the default CRUD actions. It takes a JSON object as its value. To see what options you have to choose from, see the below example. Note: this object includes every option, but you're free to pick and choose which ones you would like to include. To see more details about what specific values an option can have, the search menu in the top right of this page can direct you to where that option is in the docs.

Here is an example JSON object listing available values for the value attribute:

{
  // to change the read method of the action to POST
  "method": "POST",
  // takes a JSON packet to be sent to the server in place of the action
  // in this case user_id is always one.
  "body": {user_id:1},
  "requestType": "application/json",
  "exclude": "",
  "headers": {"Authorization": "Basic super-secrete-key"},
  "mode": "no-cors",
  "responseType": "",
  "src": "",
  "queryString": ""
}

The body value can be a static JSON, like so:

<!-- basic option with static body -->
<zg-param name="readOptions" value='{"body": {"user_id":1}}'></zg-param>
<zg-param name="createOptions" value='{"body": {"user_id":1}}'></zg-param>
<zg-param name="updateOptions" value='{"body": {"user_id":1}}'></zg-param>
<zg-param name="deleteOptions" value='{"body": {"user_id":1}}'></zg-param>

The body value can also be a function which returns an object, like so:

<!-- basic options with function reference for body -->
<zg-param name="readOptions" value='{"body": "_fncStringReference"}'></zg-param>
<zg-param name="createOptions" value='{"body": "_fncStringReference"}'></zg-param>
<zg-param name="updateOptions" value='{"body": "_fncStringReference"}'></zg-param>
<zg-param name="deleteOptions" value='{"body": "_fncStringReference"}'></zg-param>

// function returns an object
function _fncStringReference(record) {
  return {
    // to change the read method of the action to POST
    method: 'POST',
    // takes a JSON packet to be sent to the server in place of the action
    // in this case user_id is always one.
    body: {user_id:1},
    requestType: 'application/json',
    exclude: '',
    headers: {"Authorization": "Basic super-secrete-key"},
    mode: 'no-cors',
    responseType: '',
    src: '',
    queryString: ''
  }
}