Wednesday, April 13, 2011

RIA/JS - jQuery client for WCF RIA Services

by Jeff Handley via Jeff Handley on 4/13/2011 9:42:41 PM

Today at MIX11, Brad Olenick announced RIA/JS, a jQuery client for WCF RIA Services.  This is an early preview that we want to get your feedback on.  Long before WCF RIA Services V1.0 was released, we started talking RIA Services support for AJAX; in fact, you can see the item here on the RIA Services Wish List (11th ranked as of today).  We hope that you’ll grab this preview and let us know if you like the direction we’re going.

RIA/JS Features

In today’s state the features are somewhat limited, but many of the basic scenarios are in place:

1. Query support with sorting, paging, filtering
2. Changeset submission with two edit modes:
   1. “Implicit Commit” or “write-thru edits” where updates to field values are automatically submitted to your DomainService.  This can enable a Netflix.com or Mint.com experience where field changes are submitted to the server as soon as the user tabs out of the field.
   2. “Buffered Changes” mode, where your code must call commitChanges() to submit your changeset to the DomainService.  Those that have used the Silverlight client will be most familiar with this mode - a submit button is often used to trigger the commit.
3. Data change events including collection changes
4. Client-side change tracking with an entity state API for determining what entities and properties have been edited
5. Entity data model support that allows you to navigate through associated entity properties and collections
6. Client-side validation by exposing your server-side validation metadata in jQuery validation format

Contents and Prerequisites

This jQuery client is broken up into several script files.  The factoring of these files will likely change with subsequent releases.

1. DomainServiceProxy.js - provides an API for executing queries against your DomainService, with filtering, sorting, and paging.
2. EntitySet.js - Change tracking for a set of entities
3. DataContext.js - Client-side cache support, managing the entity sets
4. DataSource.js - A base datasource that is used for both remote and local data sources
5. RemoteDataSource.js - A datasource specific to a WCF RIA Services DomainService
6. LocalDataSource.js - A datasource that operates over local data already on the client
7. AssociatedEntitiesDataSource.js - A datasource that operates over an associated entities collection already on the client
8. jquery.array.js - A jQuery plug-in that provides array change methods and events (similar to INotifyCollectionChange)
9. jQuery.datasource.js - A jQuery plug-in that provides a simple jQuery-friendly API for working with data sources

There are a few other script files that you will need to use as well:

1. WCF RIA Services V1.0 SP2 Preview (April 2011) - This is required for the jQuery client to work, because we rely on an update to the hosting assembly for the JSON endpoint to be able to expose metadata
2. jQuery 1.4.4 - Currently only version 1.4.4 is supported.  We are working to get things going against 1.5+.
3. jQuery Data Link - To provide HTML DOM to jQuery object linking (similar to Silverlight’s Data Binding)
4. jQuery Templates - To generate HTML on the client based on query results
5. jQuery Validate - To perform validation against the server-provided validation metadata

RIA/JS Installation

The RIA/JS library is available in two forms:

1. Included in the WCF RIA Services Toolkit (April 2011).  The script files are included in your Program Files under Microsoft SDKs\RIA Services\v1.0\Toolkit\Scripts
2. By referencing the RIAServices.jQuery NuGet package

Super QuickStart

Update: As of the August 2011 drop of RIA/JS, this walkthrough is now obsolete.  jquery.array.js and jquery.datalink.js are no longer included in RIA/JS; instead, we have jquery.observable.js included.  Additionally, the August 2011 preview works with jQuery 1.5.1+ instead of 1.4.4.

For an updated walkthrough, please refer to the WCF CodePlex site where the BigShelf application is used.

Let’s walk through a super quickstart that illustrates how to query and submit data through the jQuery client.

• Open Visual Studio 2010 and hit File\New Project
  • Choose either an ASP.NET MVC 3 application or an ASP.NET Web Application
  • Name it “CustomerApp” and click OK
  • If you chose MVC, then select the Internet Application template
• Right-click on References and select Add Library Package Reference…
  • Find and select RIAServices.jQuery and click Install to install the package
  • Click Close to close the Library Package Reference window
• Right-click on the project and choose Add\New Item… so that we can add a DomainService
  • Select Domain Service Class, name it CustomerService.cs and click Add
  • Click OK to complete the wizard (to add an empty domain service class)
• Paste the following code into the domain service class file to complete the server-side code

[EnableClientAccess()]
public class CustomerService : DomainService
{
    public IQueryable<Customer> GetCustomers()
    {
        return new[] {
            new Customer { CustomerId = 1, CustomerName = "John Doe" }
        }.AsQueryable();
    }
 
    public void UpdateCustomer(Customer customer)
    {
    }
}
 
public class Customer
{
    [Key]
    public int CustomerId { get; set; }
 
    public string CustomerName { get; set; }
}

• Open the default page for the application
  • In MVC, it’s /Views/Home/Index.cshtml
  • In a Web Application case, it’s Default.aspx
• Select the following files from the /Scripts folder, and drag them into the page (to create the necessary <script> tags):
  • DataContext.js
  • DataSource.js
  • DomainServiceProxy.js
  • EntitySet.js
  • jquery-1.4.4.min.js (not needed when using MVC, as it’s already included in the layout.  If using a Web Application, you might have to go download it)
  • jquery.array.js
  • jquery.datalink.js
  • jquery.datasource.js
  • RemoteDataSource.js
• Update the <script> tags to fix the paths if necessary, so that they all start with /Scripts
  • Hold the Alt key and drag the mouse to make a rectangular selection, then hit delete to update the paths all at once
• Add the following code to the page: (the <script> tags that you just created are shown here too)

<script src="/Scripts/DataContext.js" type="text/javascript"></script>
<script src="/Scripts/DataSource.js" type="text/javascript"></script>
<script src="/Scripts/DomainServiceProxy.js" type="text/javascript"></script>
<script src="/Scripts/EntitySet.js" type="text/javascript"></script>
<script src="/Scripts/jquery.array.js" type="text/javascript"></script>
<script src="/Scripts/jQuery.DataLink.js" type="text/javascript"></script>
<script src="/Scripts/jquery.datasource.js" type="text/javascript"></script>
<script src="/Scripts/RemoteDataSource.js" type="text/javascript"></script>
 
<script type="text/javascript">
 
    $(function () {
 
        var serviceUrl = "/CustomerApp-CustomerService.svc";
        var customers = [];
 
        var render = function (loadedCustomers) {
            $("#customerForm input[name='CustomerName']").val(loadedCustomers[0].CustomerName);
            $("#customerForm").link(loadedCustomers[0]);
        };
 
        $([customers]).dataSource({
            serviceUrl: serviceUrl,
            queryName: "GetCustomers",
            refresh: render
        }).refresh();
 
    });
 
</script>
 
<div id="customerForm">
    Name: <input type="text" name="CustomerName" />
</div>

• In CustomerService.cs, put a breakpoint within the UpdateCustomer method, and press F5 to run the application - You now have a read/write jQuery client hitting your Domain Service!
  • The textbox should be filled in with “John Doe”
  • Change the textbox to your name and press Tab
  • Your breakpoint will be hit, and the Customer passed into UpdateCustomer will have your name
  • Stop the debugger
• Go back to your HTML and update the dataSource code to also specify bufferChanges: true within the options.

$([customers]).dataSource({
    serviceUrl: serviceUrl,
    queryName: "GetCustomers",
    bufferChanges: true,
    refresh: render
}).refresh();

• Add a button to the form:

<input type="button" value="Update Customer" id="submit" />

• Wire up the button to commit pending changes on the dataSource: (add this code after the block that configures the dataSource)

$("#submit").click(function () {
    $([customers]).dataSource().commitChanges();
});

• Keeping the breakpoint in your UpdateCustomer method, run the application again using F5 - You are now building up a changeset on the client! woo!
  • The textbox should load as “John Doe”
  • Change the textbox to your name and press Tab
  • NOTICE: The DomainService method is not called, yet…
  • Click the Update Customer button
  • Your breakpoint will be hit, and the Customer passed into UpdateCustomer will have your name

More Info…

We will be publishing more details about this new jQuery client for WCF RIA Services.  You can also find more information and the BigShelf sample application at http://jeffh.me/wcfjquery.