There is one thing that we need to get out of the way first, a breaking change. In v0.0.10 and below, queries and some instances of calls to save_changes would return a single entity if there was only one returned. This was confusing and could lead to errors. As a consumer of the gem, you wouldn’t know if a call to the Service’s execute method was a single object or an enumerable. Instead of you having to guess, those calls now return enumerables all the time. This applies to calls to execute and save_change additions. Updates, deletes, and add_link calls (we’ll get to those in a minute), as well as batch saves all return Booleans, but single save_change add calls will return an enumerable because those results are parsed similar to execute calls.

Now that that’s out of the way, let’s look at the new features.

The Features

Partial Results

The first change is thanks to arienmalec. OData allows services to do server-side paging in Atom by defining a next link. The default behavior is to repeatedly consume partial feeds until the result set is complete, for example:

svc.Partials
results = svc.execute # => retrieves all results in the Partials collection

If desired (e.g., because the result set is too large to fit in memory), explicit traversal of partial results can be requested via options:

svc = OData::Service.new "http://example.com/Example.svc", { :eager_partial => false }
svc.Partials
results = svc.execute # => retrieves the first set of results returned by the server
if svc.partial? # => true if the last result set was a partial result set (i.e., had a next link)
  results.concat svc.next # => retrieves the next set of results
end
while svc.partial? # => to retrieve all partial result sets
  results.concat svc.next
end

Single Layer Inheritance

This feature was long overdue! Back in July 2010, Scott Allen wrote a post about ruby_odata where he mentioned a change to the Service class that would parse models with single layer inheritance. His code has finally been integrated into ruby_odata. Note, that the addition currently only support single layer inheritance, but that should handle most of the cases you will encounter.

Querying Links

There are times when you don’t necessarily want to bring down full navigation property entities. In these cases the OData protocol has support for Addressing Links Between Entities. To support this, there is a new method that can be tacked on to a single entity query (e.g. finding an entity by id) called links where you pass the name of the navigation property of the links that you want to retrieve. For example:

svc.Categories(1).links("Products")
product_links = svc.execute # => returns URIs for the products

Add Link

There are times when you need to create a linkage between a parent and a child, and you don’t want be required to perform an add or update. You can now simply call the add_link method on the OData::Service with the parent object, the name of the navigation property, and the child object. Finally, call save_changes. For example:

svc.add_link(<Parent>, <Navigation Property Name>, <Child>)
svc.save_changes

Lazy Loading

In previous versions of ruby_odata, if you wanted to perform lazy loading of navigation properties you would need to do it manually, which was extremely ugly. I’m happy to say that there is now a way to perform lazy loading in a graceful way. All you need to do is to call the load_property method on the OData::Service with the entity to fill and the name of the navigation property. For example:

# Without expanding the query
svc.Products(1)
prod1 = svc.execute.first
# Use load_property for lazy loading
svc.load_property(prod1, "Category")

Reflection / Introspection

Paul Gallagher (tardate) had a great suggestion: Why should you have to look at the EDMX metadata file directly when ruby_odata parses all that data? You can now use the OData::Service to access a list of the collections that the service exposes. There is also a classes method, which gives you a list of the classes generated by the OData::Service. A function_imports method, which will list function imports exposed by the service (we’ll get to those in a minute). On a class, you can call the class method, properties, which as you guessed will give you information about each property. Each of these methods return hashes where the keys are the name, and the values are hashes of the metadata for the member that you are introspecting.

Function Imports

Quite a while ago, I received an message from a user via this blog asking about the ability to call custom service methods. Within a WCF Data Service, you can expose your own custom methods, which get translated into the EDMX as FunctionImports. These aren’t to be confused with Entity Framework’s FunctionImports. These will be parsed and dynamically added as methods to the OData::Service. When you call one of the methods, they will return a result without you needing to make a call to execute or save_changes. There are different result types. You may get back a true if the FunctionImport doesn’t return any content (for example, a delete). You may get back a single entity, or a collection of entities. Finally, you may get back a single primitive value (e.g. Integer, String, etc), or a collection of primitive values. You can use the function_imports method on the Service to determine the type that will be returned.

Namespaces

In the same message as the request for the custom service methods (ok, it was actually a reply), the user mentioned that he received type conflicts with the generated classes if one by the same name already existed. If this is a problem for you, you now have the ability to tell the OData::Service to generate the models in a specific namespace. There is a new option that can be passed in to the constructor’s option hash, :namespace. If you use this option, there shouldn’t be any collisions. You can pass a namespace in either Ruby (with double colons, e.g. RubyOData::Rocks) or .NET style (with periods, e.g. RubyOData.Rocks) if there is more than one part to the namespace that you want to use. If you don’t provide a namespace, then ruby_odata will generate the classes without any namespace just as it has before.

The Beginnings of Something Cool?

As developers, the majority of the time we either retrieve collections or a single entity, usually by an ID. I didn’t really like the current steps to retrieve a single entity by ID:

svc.Categories(1)
category = svc.execute.first

Sort of ugly, right? So inspired by Ruby on Rails, I added a class method for each created class so that you could just do this:

category = Category.first(1)

Great, right? It’s a little nicer, but sadly it’s a one trick pony right now. There’s no filtering, eager loading, etc. My idea was to hopefully expand on the concept like Rails and ActiveRecord, but for now it’s just an easier, cleaner way to get an entity.

Testing

In addition to the new features, I’ve been busy working on the testing suite.

No More Hardcoded URIs

Having to rely on Windows for testing has made me stick to Windows and e-TextEditor for ruby_odata development. The key word there is actually testing. All that Windows is required for is hosting the WCF Data Service for the Cucumber integration tests, but Cucumber is just one part of it, RSpec is the other. It’s no denying that Ruby on Windows is slower than its *nix counterparts (not to knock the RubyInstaller.com team, if it wasn’t for them, Ruby on Windows would be non-existent). Where you really see a slowdown is when you are doing TDD/BDD testing. You need tests to run fast, and if you ran the command time rake spec, my Windows box is more than 4 times slower than my old MacBook (note, not a Pro), which has similar hardware. Now, multiply that by every spec I write and I want to throw my machine out a window. So, in an effort to migrate development, the URLs and ports required for the sample WCF service are now dynamic. Take a look at features/support/constants.rb for more information. Thanks to Sean Carpenter (scarpenter) for his fork where he changed the static values in that file to be optionally set by environment variables.

Hello New Technology

I decided to change up the technologies used within the test service. First, no more SQL Express, hello SQL Compact 4. Why the change? SQL Compact 4 is simply DLL deployed, you don’t need to install anything, cool. Also, since SQL Compact 4 databases are file based, instead of having to truncate to clean the database for testing, the file could just be blown away and rebuilt easily.

So, a new database, how about a new ORM? Entity Framework 4.1, also known as “magic unicorn edition” is now being used. EF 4.1 “Code First” as it is called, is just awesome. Ditching Entity Framework’s EDMX for pure code, now that is right up my alley.

Finally, since I switch to EF 4.1, the current released version of WCF Data Services, well, didn’t work right. You know what did? The WCF Data Services October 2011 CTP, w00t.

Everything you need should be in the new test project (now called RubyODataService, changed from SampleService, though that’s still in the test URLs) thanks to NuGet and my copying of the WCF DS CTP DLLs to the packages directory since there wasn’t a NuGet package for it).

Pickle

I love the pickle gem. Aside from being authored by a guy with my last name (no relation), pickle makes Cucumber features so much nicer to read. Throughout development of ruby_odata, I’ve written my own step definitions to do things, essentially cloning what pickle does out-of-the-box, e.g. creating models, asserting against models, etc. I had toyed with getting pickle to work around June of last year, but was having issues. As time passed and experience grew, I finally got it all working. I used it in a few places in new tests, but I hope to do a complete overhaul. My pickle adapter also needs a bit of work since I didn’t put it through all of its paces, and some things need to be added to ruby_odata before it will function as expected. All in all though, it is great to finally have pickle working.

Conclusion

I hope that you find the new version of ruby_odata to be useful. In the next version, I hope to further enhance the gem with more of the different operations that OData can perform. I’m sure I’ll perform some more housekeeping in the test suite removing my ugly Cucumber steps for nice, clean Pickle steps.

What would you like to see in the new version? Add your suggestions to the issues section on GitHub. I’d also like to know what you think of the API as it stands right now. I’ve essentially been following the OData Silverlight client API syntax (e.g. AddTo<Collection Name> methods, add_link, etc). With the addition of the :first class method, it got me thinking of a bit of a different approach. Not necessarily giving up one for the other, but I think another more Ruby-esq style could co-exist. Anyway, that’s all for now, go forth and do cool things with ruby_odata. I’d love to know how you are using the gem. I was excited to find out that ruby_odata was being utilized by the rgovdatablog gem.

I skipped an update for v0.0.9, so let’s revisit what was added/fixed back then. The major change was support for self-signed SSL certificates. That addition was courtesy of J.D Mullin. I’m sure you remember his contributions back in v0.0.8 when he added Basic HTTP Authentication. Aside from J.D.’s contributions, the library was refactored to only make one call to the service for building classes and collections. Finally, a few bug fixes wrapped up the release.

Now onto v0.0.10. A lot of changes were implemented in this release that ended up allowing for wider support for ruby_odata. Thanks to input from Michael Koegel (@konfusius), Alvaro Tejada (@Blag), Ingo Sauerzapf (@IngoS11), and Juergen Schmerder (@schmerdy) (I apologize if I missed anyone!), ruby_odata now supports (at least basic functionality) for SAP NetWeaver GateWay.

Another big change is the initial support for feed customizations. Properties may not be represented within the <m:properties> collection of an entity. Currently ruby_odata supports SyndicationTitle and SyndicationSummary, but adding the other syndication options should be easy to support. If you can supply me with the metadata and a copy of the output that includes the additional feed customizations, I will be happy to add them (or feel free to fork the project and add them yourself).

Here’s are the complete list of changes for v0.0.10:

• New Features
  • Added the ability to pass additional parameters that are appended to the query string for requests
  • Added initial support for feed customizations (SyndicationTitle and SyndicationSummary)
  • Enhanced ruby_odata’s awareness of classes based on the metadata instead of relying on results that are returned
• Bug Fixes
  • Fixed issues with nested collections (eager loading)
  • Handled ArgumentError on the Time.parse for older versions of Ruby; used DateTime.parse instead if Time.parse fails
  • Removed the camelize method call when building the root URL for collections (reported by mkoegel, issue #3 on github)
  • Handled building results (classes) where the category element is missing but there is a title element instead (reported by mkoegel, issue #3 on github in the comments)
• Other
  • Change HTTP port to 8989 since 8888 conflicts with the Intel AppStore
  • Refactored service step for HTTP calls where the service address is defined within the step making it easier to make changes in the future

For the next release, I hope to continue to fix issues, finally add support for inheritance, add the ability to call a custom WebGet methods added to the service, and hopefully namespacing of entities to limit collisions. Do you have other requests? Add them to the issues list on GitHub. The previous Lighthouse site for issues has been closed in favor of using GitHub.

require 'lib/ruby_odata'
svc = OData::Service.new "http://127.0.0.1:8888/SampleService/Entities.svc", { :username => "bob", :password=> "12345" }

In addition to the big change by @jdmullin, the following changes are apart of the new version:

• Support for nullable primitive types being returned from an OData service.
• A change in ActiveSupport 3.0.x broke additions in ruby_odata when you associate a previously saved entity.  This has been corrected, and ActiveSupport 2.3.x (tested 2.3.11) and 3.0.x (tested 3.0.5) are now supported. 
• Ruby 1.9.2 is now supported.

Other “backend” type enhancements were added:

• Removed Jeweler for releasing gems
• Moved to bundler
• Updated README to reflect new changes
• Updated DB management so that testers aren’t required to move files around
• Fixed gemspec to list the development gems
• Developers can just do a “bundle install” to get all the required gems

One interesting thing that I found while testing is that Ruby 1.9.2 is much faster when running Cucumber tests on Windows.  I was using Ruby 1.8.7-p330 vs 1.9.2-p180 on Windows (RubyInstaller rocks!).  Here’s a snapshot:

Note there is a bit of a problem using Ruby 1.9.2 w/ Cucumber on Windows.  The problem is that when using bundler or “gem install,” the json gem gets installed as the x86-mingw32 version.  Running cucumber on Windows with Ruby 1.9.2 (using the incorrectly compiled json gem) yields a msvcrt-ruby18.dll error.  The way I fixed the error was to install the RubyInstaller DevKit, and then reinstall the gem “correctly” using:

gem uninstall json
gem install json --platform=ruby -v 1.4.6

What we are doing is uninstalling the incorrect copy of the json gem and then installing v1.4.6 of json using the –platform=ruby flag which will involve the DevKit to compile the gem for us.  Note that the json gem version required by Cucumber 0.10.0 is ~> 1.4.6, and there is a new version out, so the -v 1.4.6 forces the correct one.  Found the solution on StackOverflow,  but it seems that there should be a better way to solve this, perhaps with bundle-config?

Initial Breakdown

Given the three strategies that Shawn had identified, we had pretty much focused on just WCF Data Services and WCF RIA Services.  Plain old WCF services are useful for a lot of things, but they aren’t very flexible on their own.  Things like client-side shaping, sorting, filtering or paging are rough, plus I don’t see the value in writing boilerplate service code for CRUD operations.  I suppose you could use something like a T4 template for that, but for “standard” web services the thing I really don’t like is SOAP.  I won’t wax poetic about how REST makes so much more sense than SOAP, but if you are interested, you should check out RESTful .NET: Build and Consume RESTful Web Services with .NET 3.5 by Jon Flanders, it’s a fantastic book.  Sure, you could have a standard WCF Service using REST instead of SOAP, but I don’t believe that you can generate a proxy against a WCF REST service (I don’t mind WebClient/HttpWebRequest code).  That isn’t a deal breaker, but it is when writing a lot of code against a lot of objects.   We decided that standard WCF just wasn’t the easiest option for the lion’s share of the work.

So that leaves us with WCF Data Services or WCF RIA Services.  For a previous project we had discounted using WCF RIA Services for the majority of the data access (though, we did use it for user roles and such).  Trying to go into a new project with an open mind, we thought we should dig a little deeper into RIA, after all, it “seems” to be the approach that you should use for a business application as you’ll see.

WCF RIA Services Overview

So you’re building a “Business Application,” right?  Well I guess a good place to start would be File >> New Project >> Silverlight Business Application, right?  Well this assumes some things, like that you want to use things like Silverlight Navigation (yes, please), controls for user login and registration (partially ok, but we’re using Windows Authentication and don’t need registration code), and it assumes that you want to use RIA Services (maybe, but you wouldn’t be reading this post if this was clear-cut answer).  I like the concept of RIA Services very much, but the implementation has some fundamental flaws.  Let’s start with a couple of pros that RIA provides where I see real value:

Validation

Who likes validation code?  Hmmm, no hands raised?  RIA’s validation seems fantastic (at least on paper; I haven’t tried all of them in practice).  Having validation code that is shared between the client and server is cool and it’s a nice addition to Silverlight.  This is really the single compelling reason behind using RIA Services for me.

Sharing Code

Sometimes there is a disconnect between your entity model and the code you want to expose to the client.  For example, let’s say you have a Person object that has a First and Last Name.  Well, you want to expose a property called DisplayName to the client, which joins the First and Last Name.  With RIA, the DisplayName property can be added on the server and Silverlight will see it.  With something like WCF Data Services, you would need to augment the Person class on the Silverlight side, where the server knows nothing about this property (Is that a big deal in this example?  Not really).

Shawn’s post lists more than discussed here, but those two really stand out as useful to me.  I want to embrace WCF RIA Services, but a few of the cons really rub me the wrong way.

Model and Service Disconnect

Referring to Shawn’s post, the very first con is “Entity Changes Don’t Cascade to Contract.”   What does this mean?  Let’s say you are incrementally building an app for managing products.  You start with a very simple model with only one entity exposed, “Product.”  You add the Products to your model, and you expose this over RIA Services using the wizard (listed as a pro on Shawn’s post, but wizards aren’t always a blessing as you’ll see).  Anyway, so far so good.  You continue your development, and you find out you need to add a “Category” entity to your model.  Assuming you’re using Entity Framework, you update your model from the database (good tooling), and then you try to expose the entity over your RIA Service.  Ummm…  You try clicking and right-clicking all over looking for something like “Update RIA Service from Model” only to find that it doesn’t exist.

Having a disconnect between the model and the service is a giant red flag for errors on a team.  Your model can end up looking totally different than the objects you are passing over the wire, resulting in all sorts of fun errors.  There are workarounds for the issue, for example using a partial service class for each entity, or manually copying and pasting code from a temporary service into your actual service.  You can get over the con of not having tooling, but neither option is really great (IMHO).

No Eager Loading Support

I was most shocked to find this out, since the proxies for WCF Data Services and WCF RIA Services look similar.  With RIA, when you are in Silverlight (say a ViewModel or Repository) you cannot dictate what data you want.  Let’s say you have a Person object, and each Person has 1 to many Address objects.  On the client, you want to get and display a property found on the Address object (like City or something).  Well, the client can’t eager load the Person’s Addresses.  With WCF Data Services, you can add an .Expand(“Address”) to your query that you send in order to eagerly load the Address for a Person.  This doesn’t exist with RIA though.  The workaround is to perform an .Include(“Address”) in your service method that gets the list of People.  However, this really isn’t a workaround.  As a consumer of a service (Silverlight or otherwise), I want to be able to dictate what I need, not have the server force the “worst case scenario” down to me.  Of course you could have two methods, like GetPeople() and GetPeopleWithAddresses(), etc., but yuck.

Generated Code

This isn’t listed in Shawn’s list, but I’ve bumped into issues with the “Generated Code” folder in my Silverlight projects.  WCF RIA Services generates it’s client-side code when you build your solution.  This is super fragile.  What is wrong with Service References?  I’d like to have the option to break my client when I feel like it (Update Service Reference), but I don’t get the choice with RIA.  Build your solution, and boom all the changes are pulled down whether you are ready or not.

WCF Data Services Overview

Full disclosure, I LOVE WCF Data Services.  Does it have some shortcomings?  Sure, but it’s quite amazing.  I have been using WCF Data Services through all of it’s names (code-name Astoria, ADO.NET Data Services, and now WCF Data Services).  I’ve used it before the output was known as OData, etc.  In short, I’m a huge fan of the strategy.  My love of WCF Data Services comes from the fact that they are REST based and can be consumed by just about anything (shameless plug for ruby_odata; more info here).  I also like the simplicity of exposing your data model over HTTP.  IQueryable<T> collections, that I can shape on the client and I don’t have to code specific methods for, makes all the sense in the world to me.  As you know I’ve fallen in love with Ruby on Rails, but WCF Data Services is THE thing that I miss when writing a Rails app.  All I’m saying is that my views may be a little skewed.

Having used WCF Data Services for so long, I’m pretty familiar with the good and the bad.  The only two things that are lacking are the two “pros” found in the WCF RIA Services discussion found above.  Really though, WCF Data Services serve all spaces and isn’t specific to “Silverlight” or RIA Applications.  You can do validations with WCF Data Services just fine (e.g. QueryInterceptors and ChangeInterceptors), but these are limited to the server.  It makes perfect sense though.  How could the WCF Data Services team integrate client and server validation into one when the range of clients is so broad?  The wide reach of WCF Data Services is what makes them so useful.

Conclusions

After deliberating for hours, we decided to stick with WCF Data Services for the lion’s share of our development.  This decision was made simply because none of the WCF Data Services cons were deal-breakers for us, while the cons with WCF RIA Services were harder to swallow.  Again, that doesn’t mean we aren’t going to use pieces here and there (like RIA for roles and such), but we felt we needed a “default direction.”  What are your feelings on this?

OData is so powerful because it’s REST based and you can access the services from just about everywhere, including just a simple URL.  For example, using the Netflix OData service to access the best movie ever made by title: http://odata.netflix.com/Catalog/Titles?$filter=Name eq ‘Office Space’.  Pretty simple.  Of course accessing things solely based on URLs in code isn’t the best, and hence the reason for my post.

Client Libraries

When using OData, it’s convenient to utilize an SDK to access the services.  For example, in Silverlight you can access OData services using LINQ.  There’s also a fantastic AJAX Library (which I used in a previous post).  There are SDKs for PHP, Objective-C, and many others, but there was one missing that I wanted to use… Ruby.  I am assuming this comes as no surprise given my new found love for Ruby.

Introducing ruby_odata

I’ve been messing around with Ruby enough to start working on my first Ruby open-source project.  It’s always good to contribute to the open-source community.  While I’m not a seasoned Ruby developer, I figure this is a good project to start on.  Now I can code stuff in Ruby and consume WCF services I have written in the past and will continue to write in the future (that is until there is “OData on Rails,” perhaps an idea for a new project?).

The source code, like all good Ruby code, is hosted on GitHub.  The README will give you a good idea of how to use the library.  Currently (as of 06/12/2010) there are limitations, such as not being able to batch changes (like multiple Adds), but no worries, I’m working on adding them (actually, I cut three releases today, adding extra querying abilities).  That said, it is functional enough to use for most operations right now.  Once it’s been better tested in the real world and I’ve been able to incorporate most if not all of the OData functionality, I will be versioning more responsibly.  Right now, because I’m adding functionality quickly and I want others to be able to use it, you’ll be seeing lots of updates so the version number will be a bit jumpy for a while.

The Genesis of ruby_odata

I started writing ruby_odata in order to interface with my database via services so I could do testing in Ruby and create objects from within the tests that I could use in my ASP.NET MVC application.  I wrote about BDD testing in an earlier post where I fixed the speed of running the tests using Cucumber with Mechanize.  Another area missing in .NET is the ability to automatically generate objects to test against like you can with Ian White’s Pickle.   Pickle interacts nicely with factories and your database to create objects for tests.  For example, a step like: Given a user exists with name: "Damien" will automatically create a new user in the test database.  This works dandy in the Ruby world (with ActiveRecord for example), but against something like Entity Framework, not so much.  With ruby_odata however, this is something that could work in a similar way. (Yet another idea for a project, a Pickle adapter that utilizes ruby_odata.  Man, so many ideas, so little time.)

Usage Overview

The library is pretty straightforward to use.  At the heart is the OData::Service.  This is the root object that drives all of your operations against the services.   Once you instantiate the OData::Service, dynamic methods based on the OData service’s collections are available to call.  For example, using the Netflix OData service, we can see there is a collection called “Titles.”  Within ruby_odata, the OData::Service will respond to a “Titles” method:

svc = OData::Service.new "http://odata.netflix.com/Catalog/"
puts "Responds to Titles? #{svc.respond_to? :Titles}" # => Responds to Titles? true

So, just by looking at the collections on the main service page, or metadata page, you can see what you can query.  Here’s an example of querying for a movie (like we did earlier with a straight up URL):

svc.Titles.filter("Name eq 'Office Space'")
movie = svc.execute
# Now we can access properties of the Title (defined in the service metadata)
puts "Average Rating: #{movie.AverageRating}"
puts "Release Year: #{movie.ReleaseYear}"
puts "URL: #{movie.Url}"
# => Average Rating: 4.2
# => Release Year: 1999
# => URL: http://www.netflix.com/Movie/Office_Space/20358351

Pretty cool, huh?

The Basics

There is a simple pattern for using the library.  For queries, you call a collection on the service (like you saw with Titles in the Netflix example above), and that returns an OData::QueryBuilder object to you in which you can fluently add options like filter or expand.  If you use multiple calls to filter, it will perform an “AND” query against the service, and multiple expand calls will yield multiple items being expanded.  You can also mix the calls, like .filter(…).expand(…).  Once you are done building a query, you call the execute method on the service.  The result of the execute is either a single entity or a collection of the entities based on your query.

In order to add, update, or delete, you need to call the appropriate method on the OData::Service.  To add, you would use the dynamic method AddTo<Collection Name>, where the <Collection Name> is the name of the collection on the service (as defined by the metadata).  To update, you would use update_object, passing in the updated version of the object.  Finally, to delete, you would use delete_object, passing the object to delete.  Once you do one of these operations, you need to persist the change using the save_changes method on the OData::Service.  Currently, you need to call save_changes after each operation in order to persist the data.  In the future you will be able to batch operations instead of persisting them one at a time.

More Examples

For more examples, download the source code from GitHub and setup the testing environment (instructions for setting up the test environment are located in the README).  When you setup the test environment, you can follow along with the samples as shown in the README.  There are examples for all the CRUD operations.

Conclusion

There you have it, an OData library for Ruby.  I am very excited by the potential of OData, and having the ability to consume the services easily within Ruby is extremely useful.  I hope you find the library helpful.  The current version is a bit of a work in progress since everything isn’t fully supported yet, but I will continue to work on the project.  You can get involved by checking out the resources for the project:

• Source Code (hosted on GitHub): http://github.com/visoft/ruby_odata
• Documentation (hosted on rdoc.info): http://rdoc.info/projects/visoft/ruby_odata
• Issue tracking (hosted on GitHub): https://github.com/visoft/ruby_odata/issues
• Wiki (hosted on GitHub): http://wiki.github.com/visoft/ruby_odata/

If you just want to start using it without the source code, you can install ruby_odata as a gem from RubyGems.org.

First we’ll look at using the Preview 4 scripts within an ASP.NET 3.5 application (with the ScriptManager of course) as well as using client templates and ADO.NET Data Services with the ScriptManager in ASP.NET 4.0 (Beta 1).  After that, we’ll take a closer look at some of the new features of the ScriptManager in ASP.NET 4.0.

Preview 4 and the ASP.NET 3.5 ScriptManager

In my posts on ASP.NET AJAX 4.0 so far, I used standard HTML script references (as stated earlier).  However, what if you wanted to incorporate the new ASP.NET AJAX 4.0 scripts with a ScriptManager.  I tried this in a recent ASP.NET 3.5 SP1 project, and ran into some issues getting it all to work out.  Thanks to this blog (and Bertrand LeRoy), I found the solution.

<asp:scriptmanager id="sm" runat="server">
    <scripts>
        <asp:scriptreference scriptmode="Inherit" name="MicrosoftAjax.js" path="~/scripts/MicrosoftAjax.js" />
        <asp:scriptreference scriptmode="Inherit" path="~/scripts/MicrosoftAjaxAdoNet.js" />
        <asp:scriptreference scriptmode="Inherit" path="~/scripts/MicrosoftAjaxTemplates.js" />
    </scripts>
</asp:scriptmanager>

Client Templates and ASP.NET 4.0 ScriptManager

If you are using Visual Studio 2010 (currently in Beta 1) and you want to use client templates (e.g. DataView) or ADO.NET Data Services, you may think you can just add a ScriptManager to the page (at least I initially did) and everything will work.  This isn’t the case.  These are new features of ASP.NET AJAX , so you need to add them as ScriptReferences.  I’m not sure if this will change for the release, but in an effort to keep the size down, I’m thinking this may be the way it stays.  Not that big of a deal, just something to be aware of.

<asp:ScriptManager ID="sm" runat="server">
    <Scripts>
        <asp:ScriptReference Name="MicrosoftAjaxTemplates.js" />
        <asp:ScriptReference Name="MicrosoftAjaxAdoNet.js" />
    </Scripts>
</asp:ScriptManager>

ASP.NET 4.0 ScriptManager – Activating Elements Declaratively

In my previous posts, you’ve seen both declarative and imperative examples using ASP.NET AJAX components and controls.  To refresh your memory, let’s look at the “Simplest Live Binding Example” from my data binding post.  This snippet uses live binding and client templates (the DataView).  If you need a refresher on the basics of the DataView and using it declaratively, be sure to check out my client template post.

<body xmlns:sys="javascript:Sys"
      xmlns:dataview="javascript:Sys.UI.DataView"
      sys:activate="simpleForm">
    <div id="simpleForm" class="sys-template"
        sys:attach="dataview"
         dataview:data="{{ { name:'' } }}">
        Name: <input id="name" type="text" value="{binding name}" /><br />
        <span id="nameDisplay">{binding name}</span>
    </div>
</body>

One of the keys to getting this to work is to have it activate and bind when the page loads.  In the declarative syntax, this is achieved through the sys:activate attribute found on the body tag.  In some instances, such as working with a content page, you may not have access to the body tag.  In this case the new ClientElementsToActivate property of the ScriptManager and ScriptManagerProxy controls, helps to alleviate this problem.  The ClientElementsToActivate property accepts a comma-delimited list of elements to activate, just like the sys:activate attribute does.  Taking the previous snippet as an example, we can see how using this new property can be used with the ScriptManager (note I have included the ScriptReference since this sample requires the DataView, not because it is needed to use the ClientElementsToActivate property).

<asp:ScriptManager ID="sm"  runat="server"
       ClientElementsToActivate="simpleForm">
    <Scripts>
        <asp:ScriptReference  Name="MicrosoftAjaxTemplates.js" />
    </Scripts>
</asp:ScriptManager>
<div id="simpleForm" class="sys-template"
    sys:attach="dataview"
     dataview:data="{{ { name:'' } }}">
    ...
</div>

ASP.NET 4.0 ScriptManager – ASP.NET AJAX Enhancements

A new feature of the ScriptManager in ASP.NET 4.0 is the ability to use only parts of the ASP.NET AJAX Library.  In addition, you can also use the ScriptManager without using any of the ASP.NET AJAX framework.  You can now get the benefits from ScriptManager such as support for debug / release modes, localization, script combining, etc, without having to have ASP.NET AJAX scripts rendered by default (as it is now in 3.5).

In ASP.NET 4.0, the default behavior is the same as the current behavior in ASP.NET 3.5, meaning the complete ASP.NET AJAX library is included by default.  Remember from earlier that this does not include MicrosoftAjaxTemplates.js or MicrosoftAjaxAdoNet.js (at least in Beta 1).

The ScriptManager control has a new property, MicrosoftAjaxMode, which allows you to override the default behavior.  The settings available for the MicrosoftAjaxMode are:

• Enabled – The default value, all Microsoft AJAX script are included.  This is the same as the current behavior (e.g. ASP.NET 3.5).
• Explicit – This allows you to pick and choose what scripts are referenced.  You need to make sure that you include all scripts that have dependencies on one another.
• Disabled – All the the Microsoft ASP.NET AJAX scripts are disabled and no scripts are referenced automatically.

If you use Explicit mode, the following Microsoft AJAX scripts are available for reference:

• MicrosoftAjaxCore.js
• MicrosoftAjaxComponentModel.js
• MicrosoftAjaxSerialization.js
• MicrosoftAjaxGlobalization.js
• MicrosoftAjaxHistory.js
• MicrosoftAjaxNetwork.js
• MicrosoftAjaxWebServices.js
• MicrosoftAjaxApplicationServices.js
• MicrosoftAjaxTemplates.js (New for ASP.NET AJAX 4.0)
• MicrosoftAjaxAdoNet.js (New for ASP.NET AJAX 4.0)

For more information on the new functionality as well as the dependencies for the Microsoft AJAX Library scripts, refer to the ASP.NET 4.0 and Visual Studio 2010 Web Development Overview whitepaper.

More ASP.NET AJAX 4.0 Reading

If you are interested in ASP.NET AJAX 4.0, and have missed my past posts, be sure to check out:

• ASP.NET 4.0 AJAX – Preview 4 – Client Templates
• ASP.NET 4.0 AJAX – Preview 4 – JavaScript Observer Pattern
• ASP.NET 4.0 AJAX – Preview 4 – Data Binding

You may remember that we looked briefly at live bindings in the client templates post, but for those examples I used one-way / one-time bindings.  Today, we’ll take a closer look at live bindings and see how two-way live bindings removes the one-way / one-time binding restriction allowing us to update bound elements on our page automatically when the underlying data changes.

Again, in this post, I’ll be using Preview 4 of the ASP.NET AJAX Library, which can be downloaded from CodePlex.  The Preview 4 version can be used in your applications today (e.g. ASP 3.5, HTML).  Keep in mind that these components are still in “preview” mode (meaning no Microsoft support), though they are usable at your own risk.  For more information, you can check out the license on CodePlex.

Source Code

You can download and run all of the sample code that you find in this post.  The source code contains a Web Site project and uses .NET 3.5 SP1 for the server-side components (e.g. Entity Framework, ADO.NET Data Services) and SQL Server Express 2008.

The Simplest Live Binding Example

Let’s start with a very simple example of live binding in action.  In the first snippet, we’ll look at binding a very simple client template (the Sys.UI.DataView) using the declarative creation and binding syntax.

<body xmlns:sys="javascript:Sys"
      xmlns:dataview="javascript:Sys.UI.DataView"
      sys:activate="simpleForm">
    <div id="simpleForm" class="sys-template"
        sys:attach="dataview"
         dataview:data="{{ { name:'' } }}">
        Name: <input id="name" type="text" value="{binding name}" /><br />
        <span id="nameDisplay">{binding name}</span>
    </div>
</body>

If you read my client template post, most of this code should look familiar.  There are a couple of new things in this snippet however.  First, you probably noticed the {binding name}.  This is the live binding syntax.  We’ll look closer at this a bit later, but if you’ve used WPF or Silverlight the syntax should look familiar.  The one other thing that I’ve added to make this work is the dataview:data attribute.  The {{ }} syntax in this attribute simply defines an inline expression, and inside of that, I’ve created an inline JavaScript object, which contains one property ‘name’ and the value is just an empty string (I could have just as easily used null).  The reasoning behind this is that the DataView needs to initially bind data to something, so based on our binding expressions, both the input and span will be initially filled with the empty “name” property.

When you load this page, and enter your name in the textbox, the span will be updated with what you entered in the textbox after you tab away from it.  You can see this in action in the clip playing off to the right.

Using Sys.Binding Imperatively

In the last example, we used a DataView along with the binding markup.  The binding markup {binding propertyName} and {{ propertyName }} can only be used inside client templates (the DataView).  What if you didn’t want to use a DataView for something like that last example?  Well it’s possible, thanks to the way that binding is handled in ASP.NET AJAX.  The binding markup maps back to the component Sys.Binding, which in turn uses Sys.Observer.  We can harness the power of Sys.Binding directly if needed.  Let’s see how we would accomplish the same example as before, but this time using Sys.Binding directly.  We can do this declaratively (like the DataView example from above) or imperatively using JavaScript.  First, we’ll look at the imperative code:

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
        <!-- Script references removed for brevity -->
        <script type="text/javascript">
        Sys.Application.add_init(function() {
            $create(Sys.Binding,
            {
                source: $get('name'),
                path: "value",
                target: $get('nameDisplay'),
                targetProperty: "innerHTML"
            });
        });
    </script>
  </head>
<body>
    <div id="simpleForm">
        Name: <input id="name" type="text" /><br />
        <span id="nameDisplay"></span>
    </div>
</body>
</html>

You’ll notice there isn’t much going on in the HTML this time since this isn’t declaratively bound.

Looking at the JavaScript block, I’m using the $create shortcut in order to wire up the Sys.Binding component.  Since this is a component and not a control like the DataView, the only parameters that need to be passed to $create is the type (Sys.Binding) and properties for the Sys.Binding component (a JavaScript object).  The $create call is simply creating an association between the textbox (input) and the span.  Again, the results of this code are exactly the same as the initial example that we looked at.

Let’s take a closer look at the properties being set in the last example:

You can find a full list of the properties for Sys.Binding on MSDN.

Using Sys.Binding Declaratively

You just saw the imperative creation of Sys.Binding, but if you’d rather declarative syntax, then this is the example for you.  I’m working off the same example so that you can easily see the similarities and differences between the snippets.

<body xmlns:sys="javascript:Sys"
      xmlns:binding="javascript:Sys.Binding"
      sys:activate="simpleForm">
    <div id="simpleForm">
        Name:
         <input id="name" type="text"
             sys:attach="binding"
            binding:source="{{ $get('name') }}"
            binding:path="value"
            binding:target="{{ $get('nameDisplay') }}"
            binding:targetProperty="innerHTML"/>
        <br />
        <span id="nameDisplay"></span>
    </div>
</body>

Comparing this code to that of the imperative version, it should be pretty easy to pick out the similarities.  Instead of defining the properties for the Sys.Binding component in code, they are now added as attributes to the textbox.  Also, the sys:attach coupled with the xmlns:binding=”javascript:Sys.Binding” replaces the first parameter in the $create call from the imperative example.  Other than that, there shouldn’t be anything here that looks strange, if it does, refer back to my client template post.

Live Binding Syntax

Now that you’ve seen an example of live binding in action, let’s take a minute and look at the options available to us with live binding.

The first is the binding type defined in MSDN as an “inline expression evaluation.”  This is commonly referred to as one-way/one-time when talking about binding, but the double curly braces syntax is also used to evaluate expressions (for example the attribute binding:source=”{{ $get(‘name’) }}” from the last example).  When it used as a binding type, such as <span>{{ name }}</span>, this simply means that expression is only handled when the template is bound/re-bound.

Next up is one-way and two-way binding.  The syntax for these bindings is {binding propertyName}, as you’ve seen before.  The syntax is the same since the determination of using one-way or two-way is based on the element itself.  One-way binding is the default mode of binding for HTML properties and context.  For input controls however, two-way binding is the default.  You can see this in action in the first example we looked at, binding within the DataView.  As a refresher, here is the pertinent snippet again:

Name: <input id="name" type="text" value="{binding name}" /><br />
<span id="nameDisplay">{binding name}</span>

If the default behavior isn’t desired, for example if you only wanted one-way binding on a textbox, you can specify the mode of the binding.  This can be done within the inline markup as so:

Name: <input id="name" type="text" value="{binding name, mode=oneWay}" /><br />
<span id="nameDisplay">{binding name}</span>

We’ll look a bit closer at binding modes in the next section, but one thing to take away from the syntax here is that you can specify properties for Sys.Binding within the HTML markup.  Another common property that you may set would be the source. For example, in a master-detail type setup where you have a master DataView and a detail DataView, you may have something along the lines of:

<div id="detailView" class="sys-template"
    sys:attach="dataview"
    dataview:data="{binding selectedData, source={{master}} }">

You see that syntax a bit later in the Master/Detail example.  In addition to mode and source, another property that you’ll often see is the convert and convertBack properties.  These allow you to call functions when either updating the target (convert) or updating the source (convertBack).  For example:

<label>Inches: </label>
<input id="inches" type="text"
     value="{binding num, convert=toInches, convertBack=toFeet }" />
<br />
<label>Feet: </label>
<input id="feet" type="text" value="{binding num }" />

In this snippet the Inches textbox will call toFeet when updating the Feet textbox.  When the Feet textbox is updated and the binding happens on the Inches textbox, it will first be converted to inches using the toInches method.

Binding Modes

Sys.BindingMode.auto

This is the default binding mode that you’ve seen already.  Two-way binding on an input control, and one-way binding on a context-type elements such as spans.  If for some reason you want to manually set the mode to auto, you can do this as well, but it’s not required.

<div id="defaultBinding" class="sys-template"
    sys:attach="dataview"
     dataview:data="{{ { name:'' } }}">
    <label>Name: </label>
    <input id="name" type="text" value="{binding name, mode=auto}" /><br />
    <label>Echo: </label>
    <span id="nameDisplay">{binding name, mode=auto}</span>
</div>

Sys.BindingMode.twoWay

This is the default binding mode for input controls.  In this snippet, I’ve explicitly set both inputs to twoWay, although I could have left the mode specification off since it is the default.  In this snippet, when you update either textbox, the other one will be updated with the same value.

<div id="twoWayBinding" class="sys-template"
    sys:attach="dataview"
     dataview:data="{{ { name:'' } }}">
    <label>Name: </label>
    <input id="name1" type="text" value="{binding name, mode=twoWay}" /><br />
    <label>Echo: </label><input id="nameDisplay1" type="text" value="{binding name, mode=twoWay}" />
</div>

Sys.BindingMode.oneWay

Again, this is the default binding mode for properties and context-type HTML elements (e.g. span, div, etc).  You can specify this mode on an input control in order to override the default two-way binding.  In this snippet, when you update the Name textbox it will be displayed in the Echo textbox, but changing Echo won’t update Name since the Echo textbox is oneWay.

<div id="oneWayBinding" class="sys-template"
    sys:attach="dataview"
     dataview:data="{{ { name:'' } }}">
    <label>Name: </label>
    <input id="name2" type="text" value="{binding name}" /><br />
    <label>Echo: </label>
    <input id="nameDisplay2" type="text" value="{binding name, mode=oneWay}" />
</div>

Sys.BindingMode.oneWayToSource

This binding works opposite to the last oneWay binding example.  In this case, changes to the Echo textbox will update the Name textbox, but updating Name won’t change Echo.

<div id="oneWayBinding" class="sys-template"
    sys:attach="dataview"
     dataview:data="{{ { name:'' } }}">
    <label>Name: </label>
    <input id="name2" type="text" value="{binding name}" /><br />
    <label>Echo: </label>
    <input id="nameDisplay2" type="text" value="{binding name, mode=oneWay}" />
</div>

Sys.BindingMode.oneTime

In oneTime mode, the element will only be updated when the template is first instantiated.  For this snippet, the Name and Echo textboxes will be updated with my name and will be bound to both textboxes since it is defined in the object literal being passed to the DataView.  Changing the Name textbox in this case won’t update the Echo box.

<div id="oneTimeBinding" class="sys-template"
    sys:attach="dataview"
     dataview:data="{{ { name:'Damien' } }}">
    <label>Name: </label>
    <input id="name4" type="text" value="{binding name}" /><br />
    <label>Echo: </label>
    <input id="nameDisplay4" type="text" value="{binding name, mode=oneTime}" />
</div>

The “Classic” Example: Master/Detail

Typically when looking up live binding, you’ll come across some kind of master/detail sample.  To keep with the “tradition” we’ll work through an example using SQL 2008, the Entity Framework, and ADO.NET Data Services server-side, and the ASP.NET AJAX DataView client-side.  Again, keeping with the trend of seeing how ASP.NET AJAX can be used outside of ASP.NET, the hosting page will simply be a standard HTML page.  In this sample we will be keeping a list of blogs that we enjoy.  We’ll add the blogs to the page one at a time, and we will persist the changes back to the database all at once thanks to ADO.NET Data Services.

Server-Side Code

First, we’ll start with a simple SQL 2008 Express Database that contains a single table named “blog.”  The schema is shown in Figure 1.

Figure 1 – The Database Schema

Next up is the Entity Framework.  Simply add an ADO.NET Entity Data Model to the project.  I’ll name this BlogModel.edmx.  I’ll then use the “Generate from Database” option when prompted.  I’ve accepted the defaults for everything else.  We now have a single entity based on the blog table.  I’ve changed the EntitySet name to Blogs in order to make our service clearer when calling it, for example to get an item with an ID of 1, /BlogService.svc/Blogs(1) instead of /BlogService.svc/Blog(1) if I had left the default EntitySet name.

Figure 2 – The Blog Entity

Now that the database and the entity model are in place, the next step is to expose the entities via ADO.NET Data Services.  To do this, simply add an “ADO.NET Data Service.”   I’ve named my service “BlogService.svc.”  Then we need to configure the service, which involves specifying our entities to expose and configuring the rules for our service.  Since this is just a test service, I’ve opened all operations to all entities.  In addition I’ve configured the service to use verbose errors, and to include the exception details in an error.  In a production application, these settings should not be used, as we’re exposing everything to everyone.

[ServiceBehavior(IncludeExceptionDetailInFaults=true)]
public class BlogService : DataService<BlogsModel.BlogsEntities>{
    public static void InitializeService(IDataServiceConfiguration config)
    {
        config.UseVerboseErrors = true;
        config.SetEntitySetAccessRule("*", EntitySetRights.All);
        config.SetServiceOperationAccessRule("*", ServiceOperationRights.All);
    }
}

Now that the server side is configured, let’s test it out in the browser.  One thing you need to do before testing an ADO.NET Data Service is to make sure the “Feed View” is turned off in your browser.  For the XML representation of the data, ADO.NET Data Services uses ATOM, which RSS feeds use as well.  The browser, being helpful, will use the “Feed View” trying to “pretty” up the display of your service, when in fact we won’t see the raw XML data.  To turn off Feed View in Internet Explorer, simply go to Tools >> Internet Options >> Content Tab >> Feed Settings >> Uncheck “Turn on feed reading view.”  Now we can start browsing our service.

Calling the BlogService.svc directly, this will show us the collections available for us to use.  Simply browse to “/BlogService.svc” in the root of the application.  Next, let’s test the Blogs collection by browsing to “BlogService.svc/Blogs” and finally use “BlogService.svc/Blogs(1)” to access the entry with an ID of 1.

Figure 3 – Testing the ADO.NET Data Service

Client-Side Code

Now that the server work is done, let’s move on to the client code.  The user interface will allow us to perform the standard CRUD (Create, Read, Update, Delete) operations using ADO.NET Data Services.  We will list the blogs that are found in the database and add a snapshot of the site using a cool service I discovered called BitPixels.com.  This site serves thumbnails of web pages without requiring a registration, which is perfect for a demo since you can download my sample code and run this on your machine without having to worry about registering to get it to work.

Here’s an example of it fully working:

An important thing to note on the example, changes aren’t persisted until they are saved back to the server.  We’ll see how this is accomplished when we look at the JavaScript code.

The first difference with this example from the others that you have seen in my previous posts (Sys.Observer and Client Templates) is the JavaScript files being referenced.  We’re still using MicrosoftAjax.js and MicrosoftAjaxTemplates.js, but in addition we need to reference MicrosoftAjaxAdoNet.js.  This library allows us to work very easily with ADO.NET Data Services.  The script references should look like the following:

<script type="text/javascript" src="scripts/MicrosoftAjax.debug.js"></script>
<script type="text/javascript" src="scripts/MicrosoftAjaxTemplates.debug.js"></script>
<script type="text/javascript" src="scripts/MicrosoftAjaxAdoNet.debug.js"></script>

Now, onto the HTML markup.  There is a fair amount going on here, but some of it should look familiar to you.

<body   xmlns:sys="javascript:Sys"
        xmlns:dataview="javascript:Sys.UI.DataView"
        sys:activate="*">
    <div class="tools">
        <input type="button" value="Add" onclick="addBlog()" />
        <input type="button" value="Save" onclick="BlogService.dataContext.saveChanges()" />
        <input type="button" value="Reload"
            onclick="$find('blogList').fetchData(null, null, Sys.Data.MergeOption.overwriteChanges)" />
    </div>
    <div id="blogList" class="sys-template"
        sys:attach="dataview"
        dataview:dataprovider="{{ BlogService.dataContext }}"
        dataview:fetchoperation="Blogs"
        dataview:ondataloading="{{ dataLoading }}"
        dataview:autofetch="true"
        dataview:selecteditemclass="blogSelected"
        dataview:initialselectedindex="0"
        dataview:sys-key="master"
        dataview:oncommand="{{ dvCommand }}">
        <div class="blogBlock" sys:command="Select">
            <div class="blogTools">
                <div class="blogDelete" sys:command="Delete"
                    sys:commandargument="{{$index}}">X</div>
            </div>
            <img alt="{binding Name}" height="75" width="100"
                sys:src="{binding Url, convert=toSnapshot}" />
            <hr />
            <a href="{binding Url}">{binding Name}</a>
        </div>
    </div>
    <hr style="clear:left;" />
    <div id="detailView" class="sys-template detailsForm"
        sys:attach="dataview"
        dataview:data="{binding selectedData, source={{master}} }" >
        <label>Name: </label><input type="text" value="{binding Name}" /><br />
        <label>Url: </label><input type="text" value="{binding Url}" />
    </div>
</body>

Let’s go through the code in chunks

• Lines 1 – 3: This shouldn’t be anything new, you first saw this when working with the DataView declaratively.
• Lines 4 – 9: This section defines the buttons that allow us to Add, Save, and Reload.
  • Line 5: For adding, I’m calling a custom JavaScript function which you’ll see in a moment, addBlog().
  • Line 6: Using the ADO.NET Data Context, we can persist the changes back to the database.  Instead of simply defining a variable (e.g. dataContext), I created a simple JavaScript object (BlogService) to hold the properties that we need to work with (dataContext, which is a Sys.Data.AdoNetDataContext, and an observable array “data” that is made observable with Sys.Observer.makeObservable).  You’ll see this in the JavaScript code.
  • Line 7 & 8: This input button reloads the data.  This uses the method “fetchData” that is found on the DataView object.  The $find shortcut gets the DataView from the blogList DIV element, allowing us to call fetchData.  It takes four parameters, a success callback, failed callback, merge option, and a user context.  For the sake of reloading the DataView, the first two parameters (the callbacks) are null since the DataView handles those for us. The third is a type of Sys.Data.MergeOption and we want to reload everything from the server.  Finally, we don’t need to specify anything for the user context, so that parameter is excluded.
• Lines 10 – 19: This is the setup of our “master” div.  This displays the website thumbnails, contains a delete button, and allows us to select an item.
  • Line 10: Nothing new here, just an id and a class of “sys-template.”  Remember, this class needs to be on all of your DataViews and you should have a style defined as “display: none;” for this.  Doing this permits the AJAX library to show the content only after it has been bound.
  • Line 11: You’ve seen this many times before, we’re simply attaching the DataView “behavior” to the div.
  • Line 12: Now we begin setting the properties we need for the DataView.  Here we are telling the DataView to use a dataProvider.  The provider here is a Sys.Data.AdoNetDataContext and is defined in our JavaScript code. I’ve assigned it to a simple object, “BlogService” to keep the global variables in one place.
  • Line 13: The fetchOperation is used to define the entity set (from ADO.NET Data Services) that we want to display.  There is only one in this example and that is “Blogs.”  Recall we accessed this earlier using the browser (e.g. “BlogService.svc/Blogs”).
  • Line 14: This is an important event that is being wired up dataLoading via the onDataLoading method. This fires when, you guessed it, the data loads.  Here we’re calling a custom JavaScript function named “dataLoading” that I have defined in the page.  Within this function that you’ll see in the JavaScript code below, the data is put into an observable collection.  This collection is where our changes will take place and how the DataView and the live bindings actually do the automatic updates.  All thanks to the Sys.Observer object.
  • Line 15: You saw this back in my client templates post when using the WCF service.  Setting autoFetch to true is used when we have a dataProvider.  This tells the DataView to retrieve the data when the page loads.
  • Line 16 & 17: The DataView has built-in functionality for handling item selection.  In line 16, we can define a CSS class for the item when it is selected (selectedItemClass).  In line 17, we are telling the DataView to initially select the first item in the list when the page loads (initialSelectedIndex).
  • Line 18: The purpose of sys-key is to create a local variable that is a reference to the current component.  This allows us to refer to it (line 37), without needing to use $find.  (Thanks to Bertrand Le Roy for pointing this out)
  • Line 19: This may look familiar from server-side code that you have written (e.g. DataGrid).  The onCommand method allows us to handle commands that are raised from the component.  The reason for handling this is the custom “delete” command on Line 22.
• Lines 20 – 31: This is the master DataView’s content.
  • Line 20: The first of two commands that we need to handle. Select is a command that the DataView handles automatically for us.  When you click inside the div, the DataView handles this event by setting the selectedData property (which will be used in the edit form on Line 37), setting the selectedIndex property, and also setting the selectedItemClass.
  • Line 22 & 23: The second command that we need to handle is delete.  To do this, we set the sys:command to “Delete” on Line 22.  This command will be bubbled up to our custom handler since we set the onCommand method of the DataView on Line 19.  In addition to custom events, we can have custom event args.  {{ $index }} evaluates to the index of the item as generated by the underlying collection.
  • Line 27: This line is of interest since we are using the convert property of the binding.  Because of this, the src attribute needs to be prefixed with the sys namespace.  In some instances like this one, we need to prefix the attribute with sys in order to obtain the full functionality.  The convert function specified here is a custom one that will either set an empty image or change the src to the one that grabs the website snapshot.
• Lines 35 – 40: This is the “detail” DataView, or in our case the edit form.
  • Line 37: This is really the only item of interest in the edit form since everything else is pretty standard.  Here the binding is a bit special.  We are binding to the selectedData property of the “master” DataView.  The {{master}} refers to the sys-key defined in Line 18.

Now that you fully understand the HTML, let’s move onto the JavaScript.  For the JavaScript I have added all of the comments inline instead of a full discussion after the fact to make it easier.

// Create an empty object to store global variables
//   - dataContext: The AdoNetDataContext
//   - data: An observable "view" of the data
var BlogService = {};
 BlogService.dataContext = $create(
    Sys.Data.AdoNetDataContext,
    { serviceUri: "BlogService.svc" }
);
function dataLoading(sender, args) {
    // BlogService.data is where our changes will take place
    // You can think of this as a "ViewModel"
    // See http://forums.asp.net/p/1405579/3060650.aspx for more info
    BlogService.data = args.get_data();
    Sys.Observer.makeObservable(BlogService.data);
}
function addBlog() {
    // Create a new Blog entity
    var newBlog = { Name: 'Blog Name', Url: '' };
    // Add the blog to the DataContext
    BlogService.dataContext.insertEntity(newBlog, "Blogs");
    // Add the blog to our "ViewModel"
    BlogService.data.add(newBlog);
}
function toSnapshot(url) {
    // Either return a blank image
    if (url.substring(0, 7) !== 'http://')
        return 'nothumbnail.jpg';
    // Or use the bitpixels.com path to get a thumbnail
    return 'http://img.bitpixels.com/getthumbnail?url=' + url;
}
function dvCommand(sender, args) {
    // Test for our custom delete command
    if (args.get_commandName() === 'Delete') {
        // Get the index that we set on the delete button
        var index = args.get_commandArgument();
        // Get the entity from the local data
        var deletedBlog = BlogService.data[index];
        // Remove the entity from the ADO.NET Data Service
        BlogService.dataContext.removeEntity(deletedBlog);
        // Remove from the local collection
        BlogService.data.remove(deletedBlog);
        // Set the DataView's selected index
        if (index >= BlogService.data.length) index--;
        $find('blogList').set_selectedIndex(index);
    }
}

Conclusion

ASP.NET 4.0 is one exciting release.  The ASP.NET AJAX features shown here are incredibly cool.  The best thing about ASP.NET AJAX is that we can start using the scripts today in our ASP.NET 3.5 SP1 applications thanks to Preview 4.  No need to install anything on the server, just simply reference the scripts.  I’m excited to see documentation has been released for ASP.NET 4.0 Beta 1 and I would recommend checking out the ASP.NET AJAX Client Reference on MSDN.  I’ve also included many links to it throughout this post.  Another helpful reference is the ASP.NET 4.0 and VS 2010 whitepaper, where you can see all the features of ASP.NET 4.0 as well as the ASP.NET AJAX functionality.

For other blogs on ASP.NET AJAX 4.0, be sure to check out:

• Bertrand Le Roy’s blog – http://weblogs.asp.net/bleroy/
• Jim Wang’s blog: http://weblogs.asp.net/jimwang/default.aspx
• Politian’s blog: http://politian.wordpress.com/