Code sample: OData.JS

A DevForce entity model that supports a .NET distributed client application can also be accessed in an HTML/JavaScript client using the DevForce OData APIs as we demonstrate in this code sample.

• Platform: HTML/JavaScript
• Language: C#
• Download: Simple JS OData Tour
• Prerequisites: DevForce 6.7 or later
  
  

A simple OData Javascript Sample

This sample shows how to build a simple HTML/JavaScript client to query and save changes to a DevForce entity model.

Suppose you have an existing Line of Business Application (LOB) written in a .NET client technology such as WPF, Windows Forms, or Silverlight. Suddenly, you face an immediate need to display data from your application on a non-.NET device; you also need to make simple changes from that device such as adding a new customer or a new order.

You want to do it in HTML with a minimum of fuss and you need to get it done quickly. You need a way to retrieve entities, display them, and update the database. You don't need anything fancy. You don't need a JavaScript business model running in the browser with change tracking and validation. 

One approach is to expose the necessary subset of your existing DevForce entity model as an OData service and consume it in an HTML client. That's what we do in this sample, a single screen web page that queries and saves customer and order information to the NorthwindIB tutorial database. Here's the page:

Its capabilities include:

• Search for customers by name (enter name in search TextBox and press the button)
• Add a new Customer by pressing the "Add test customer" button
• Review selected Orders
• Add a new OrderDetailExtended (see below) to one of the orders by pressing the "Add test item" button 
• Review the OData entity model metadata
  
  

Implementation

The sample consists of a single web project, "SimpleJsOdataTour".

The lone web page, default.html, is almost exclusively vanilla html (not even HTML 5) in keeping with the "unobtrusive JavaScript" practice. The application-specific JavaScript is imported at the bottom of the page which puts the page in motion by a call into the main function of application.js.

The focus of this sample is on a handful of short JavaScript application files, located in the "scripts" folder, the kind you would write to get the job done. "application.js" is the master script controlling the action. It delegates to the customer.js and order.js scripts which handle details of the "Customers" and "Orders" sections. 

These three scripts demonstrate how to get and save your entity data using the jQuery and DataJS libraries which are located in the "external" folder. The Microsoft-sponsored DataJS library is particularly helpful for accessing OData data sources. 

The DevForce OData data source was created in the manner described in "Enabling OData". It exposes a subset - just three entity types - of the NorthwindIB tutorial entity model; you can view the full model in the Entity Framework's EDM Designer by double-clicking NorthwindIB.edmx. 

The HTML page is spare, barely sufficient for our minimal requirements. We're concentrating on data access with JavaScript and OData, not HTML or JavaScript programming in general.

The embedded ReadMe.txt file explains more of the details of the sample solution.

Clear the test data

When you press either of the "Add" buttons, you save new test data to the NorthwindIB tutorial database. Use the DeleteTestRecords.sql script, under "Solution Items", to delete these test records from the database when you're done playing with the application.

• Double-click DeleteTestRecords.sql to see the script in a code editor window
• Right-mouse click anywhere in the window and pick "Execute SQL" from the context menu
• Connect to the database as instructed in the pop-up dialog

You should see three entries displayed in the "Messages" window reporting the number of rows deleted in the Customer, OrderDetail and Product tables.

The OrderDetailExtended read-only entity

This sample contains an "Easter egg" of sorts. One of the entities, OrderDetailExtended, is actually read-only. It is mapped to a view in the database that consists of data drawn from two different tables, "OrderDetail" and "Product". You cannot update such a view in a SQL database.

Yet the application seems to be able to create OrderDetailExtended entities. How does it do it? The secret is in the OrderDetailExtendedSaveInterceptor which is called inside the custom NorthwindIBEntities EntityManager. This interceptor detects the client's attempt to save a new OrderDetailExtended; it discards that new OrderDetailExtended, converting its contents into a new OrderDetail entity and a new Product entity - both writable entities mapped to the "OrderDetail" and "Product" tables. It saves these two entities instead of the OrderDetailExtended. 

Pretty clever and pretty useful when you want a bare-bones "view object" either for easy client programming or to hide information that shouldn't be accessible on a remote client machine. The price is some compensating complexity on the server.

This is not a JavaScript-only gambit; the OrderDetailExtended and OrderDetailExtendedSaveInterceptor are part of this application's OData service implementation and would be available to any OData client. We could have embedded this logic in the TourEntityServerSaveInterceptor in which case it would have been available to standard DevForce clients as well as OData clients.