REST Updating (igGrid)

Topic Overview

Purpose

This topic explains igGrid™ support for REST services.

Required background

The following table lists the topics and articles required as a prerequisite to understanding this topic.

• Concepts
  • REST
  • OData
  • HTTP
• Topics
  • igGrid Overview: The igGrid is a jQuery-based client-side grid that is responsible for presenting and manipulating tabular data. Its whole lifecycle is on the client-side making it independent of any specific server-side technology.
  • igGrid/igDataSource Architecture Overview: This document explains the architecture of igDataSource.
  • Binding to REST Services (igDataSource): This document demonstrates how to bind REST services to the Ignite UI for jQuery™ data source, or igDataSource, control.
• External Resources
  • Representational State Transfer (REST)
  • Open Data Protocol
  • HTTP/1.1 RFC

In this topic

This topic contains the following sections:

• Introduction
• igGrid REST Properties
• Control Configuration Summary
• Send batch REST requests
• Custom style Url
• Creating custom REST serializer
• Related Content

Introduction

igGrid REST summary

REST frameworks are created on top of the HTTP/1.1 protocol. One of their key features is that they leverage the HTTP/1.1 verbs GET, POST, PUT and DELETE to identify the type of operation in the request.

In order to provide REST support, the $.ig.RESTDataSource type was created. REST settings are configured through the restSettings property. The $.ig.RESTDataSource collects the data using HTTP verbs. When the saveChanges method is called, the $.ig.RESTDataSource serializes the request and sends it as a whole (if batch is set to true) or in individual entity chunks (if batch is set to false) grouped by verb type.

By default, the $.ig.RESTDataSource serializes the requests using the JSON format. Support for other formats can be accomplished by implementing the contentSerializer function.

The igGrid supports REST binding using the $.ig.RESTDataSource internally. It inherits all $.ig.RESTDataSource options, meaning these options can be set directly on the igGrid. In fact, you don’t need to directly configure the $.ig.RESTDataSource at all.

It is important to note that restSettings are used when the igGridUpdating feature is enabled. On calling saveChanges, all the inserted rows are sent in a POST request, all deleted rows are sent with a DELETE request and all updated rows are sent with a PUT request.

REST support is implemented on the client side. On the server side you can use any technology which can produce a REST service. For example you can use an ASP.NET MVC 4 WebAPI implementation or you can create your own in ASP.NET MVC2/3.

There are two modes of a REST request. One is batch mode and the other is non-batch mode. The modes differ by how they package the data and also how they construct the URL. In the following tables you can see the request specifics defined by each REST mode:

Non-batch default URL parameter table:

Batch default URL parameter table:

Note: In the igGrid, restSettings can be set dynamically at runtime.

It is possible to set the url only for one verb in the rest settings and the url is used by the other verbs. This behavior is only valid for the url option. Batch and Template options are not re-used between the verb settings.

Example:

The following code:

In JavaScript:

restSettings: {
    create: {
        url: "/api/products/"
    }
}

Is interpreted as:

In JavaScript:

restSettings: {
    create: {
        url: "/api/products/"
    },
    update: {
        url: "/api/products/"
    },
    remove: {
        url: "/api/products/"
    }
}

In the following screenshot you can see the REST request made by the igGrid when the saveChanges method is executed.

igGrid REST Options

The following table explains the options of the igGrid REST settings and lists the default and recommended values.

Control Configuration Summary

Send batch REST requests

The $.ig.RESTDataSource supports two types of requests:

• Non-batch mode – in this mode, the data source sends each individual entity in a separate Ajax call to the server.
• Batch mode – in this mode, the data source wraps all the entities by verb type and sends them with up to tree Ajax calls to the server.

Option settings

The following table maps the desired configuration to option settings.

Example

The screenshot below demonstrates how the $.ig.RESTDataSource behaves as a result of the following settings:

Custom style URL

By default, the $.ig.RESTDataSource constructs the destination URL as explained earlier in the topic. If you have different routing logic on the server, then you can use a URL template to define your URLs. You can also use the URL template to construct OData-compatible URLs.

Note: Currently, ${id} is the only supported placeholder in the template string.

Option settings

The following table maps the desired configuration to option settings.

Example

The screenshot below demonstrates how the $.ig.RESTDataSource behaves as a result of the following settings:

Creating custom REST serializer

The $.ig.RESTDataSource supports JSON serialization out of the box. However you can implement a custom serializer.

Option settings

The following table maps the desired configuration to option settings.

Example

The screenshot below demonstrates how the $.ig.RESTDataSource behaves as a result of the following settings:

• contentType
  • “application/xml; charset=utf-8”
• contentSerializer
  • In JavaScript:

      function (ds) {
          // if ds contains JavaScript object literal like this: {"ID":9,"Name":"Product","Price":90.0,"Quantity":2 } then you can serialize it in XML like this
          return "<Product><ID>" + ds.ID + "</ID><Name>" + ds.Name + "</Name><Price>" + ds.Price + "</Price><Quantity>" + ds.Quantity + "</Quantity></Product>";    
      }
    

Related Content

Topics

The following topics provide additional information related to this topic.

• Binding to Web Services: This document demonstrates how to bind the Ignite UI for jQuery™ grid, or igGrid, to an OData protocol web-based data source.

• Getting started with igGrid, OData and WCF Data Services: This topic demonstrates how to setup a client-side jQuery grid with remote paging, filtering, and sorting by setting up a WCF Data Service in an ASP.NET Web Application and setting two options on the igGrid.