ODataAngularResources

ODataAngularResources is a fork of Angular's $resource that allows to make OData queries in a fluent way. It does everything Angular Resources does but add some features:

• Fluent API
• Generate proper OData queries without worrying about escaping the right characters
• Allows filtering, skipping, ordering, expanding, and selecting only N elements (with top)
• Able to generate complex queries with OR, AND and method calls

Simple JSFiddle Demo

Table of Contents

• How to install
• How to use
• Simple query
• Retrieving a single element
• Query with top, orderBy and skip
• Count and InlineCount
• Including related models (Expanding)
• Pick a subset of the properties (Selecting)
• Specifying a custom url and method
• Specifying the response format
• Advanced queries
• Predicates
• Overriding default Predicate or Filter behavior
• Specifying the type of the data
• Function calls
• Function calls definition
• List of available functions
• Lambda Operators
• OData V4 support
• Updating entries with OData v4
• Expand and Odata v4
• InlineCount with OData v4
• Transform the final query url
• The Promise Chain
• Interceptors
• Callbacks
• Error Correction
• Refreshing Responses & Odata Query Persistence
• Persistence
• $refresh
• Build from the source
• Run the tests
• Contribute

How to install

1. Download the repository or install the bower package :

bower install angular-odata-resources --save

or

npm install angular-odata-resources --save

1. Include the file build/odataresources.js into your project
2. Be sure to register the module "ODataResources" in your module definition :

var myModule = angular.module('myModule',['ODataResources']);

1. Then replace your dependency to "$resource" by "$odataresource"

myModule.controller('MyController', ['$scope','$odataresource',function($scope,$odataresource){}]);

How to use

Simple query

• Call the odata() method on your resource.

var User = $odataresource('/user/:userId', {userId:'@id'});
var myUsers =   User.odata()
                    .filter("Name","John")
                    .query(); 
//Queries /user?$filter=Name eq 'John'

• The first parameter of the filter method is assumed to be the property and the second to be the value. But that behavior can be overriden by passing special parameters. See advanced queries for more informations.

• Returned objects from the query() method are regular Resource object which can be used for saving, updating etc...

myUsers[0].$save();

• Like regular Resource requests you can pass callback that will be called on success and on error

var myUsers =   User.odata()
                    .query(function(){
                        console.log("Everything went ok!")
                    },function(){
                        console.log("Oops, something wrong happened!")
                    }); 

Retrieving a single element

• Simply call the get method with the entity key

var userId = 10;
var myUsers =   User.odata().get(userId);
//Queries /user(10)

• You can also provide callbacks

var userId = 10;
var myUsers =   User.odata().get(userId,
                          function(){
                            console.log("Everything went ok!")
                        },function(){
                            console.log("Oops, something wrong happened!")
                        });

If you want to retrieve a single element after a query you can use the single() method which will take the first elements of the response. This method will throw if the reponse returns an empty array.

var User = $odataresource('/user/:userId', {userId:'@id'});
var myUser =   User.odata()
                    .filter("Name","John")
                    .single(); 
//Queries /user?$filter=Name eq 'John' and put the first element into myUser

Query with top, orderBy and skip

var User = $odataresource('/user/:userId', {userId:'@id'});
var myUsers =   User.odata()
                    .filter("Name", "John")
                    .filter("Age",">",20)
                    .skip(10)
                    .take(20)
                    .orderBy("Name","desc")
                    .query();

//Queries /user?$filter=(Name eq 'John') and (Age gt 20)&$orderby=Name desc&$top=20&$skip=10

• Multiple chained filters are executed with and between.
• orderBy assumes the order to be asc if the second parameter is not specified.

Count and InlineCount

• It's possible to query the number of elements

                var data = User.odata().filter('name','bob').count();

//Queries /user/$count/?$filter=name eq 'bob'
// data.result == 25

• You can also ask for an inline count to have the count aside with the data

                var users = User.odata().withInlineCount().query();

//Queries /user?$inlinecount=allpages
// users is an array but also contains the count property
// The server may reply by
// {
//     "@odata.context": "http://host/service/$metadata#Collection(Edm.String)",
//     "value": [{
//         name: 'Test',
//         id: 1,
//     }, {
//         name: 'Foo',
//         id: 2,
//     }],
//     'count': 10
// }
// And then, the count will be defined as followed
// users.count == 10

Including related models (Expanding)

• You can easily include related models by calling the expand method

var User = $odataresource('/user/:userId', {userId:'@id'});
var myUsers =   User.odata()
                    .expand("City")
                    .query();

//Queries /user?$expand=City

• You can also expand nested related models like the Country of the City of the User

var User = $odataresource('/user/:userId', {userId:'@id'});
var myUsers =   User.odata()
                    .expand("City","Country")
                    .query();

//Queries /user?$expand=City/Country

• You can also include multiple related models into your query

var myUsers =   User.odata()
                    .expand("City")
                    .expand("Orders")
                    .query();

//Queries /user?$expand=City,Orders

Pick a subset of the properties (Selecting)

• You can use the select method to retrieve only some properties of the entities.

var User = $odataresource('/user/:userId', {
        userId: '@id'
    });

    var users = User.odata().select(['name','userId']).query();
    //OR
    var users = User.odata().select('name','userId').query();                    

//Queries /user?$select=userId,name

Specifying a custom url and method

• Want a custom url for your odata queries? easy! It works just like angular resources:

User = $odataresource('/user/:userId',
                     { userId: '@id'},
                     {
                        odata: {
                            method: 'POST',
                            url: '/myCustomUrl'
                        }
                     }
    );

Specifying the response format

var myUsers =   User.odata()
                    .format("json")
                    .expand("City")
                    .expand("Orders")
                    .query();

//Queries /user?$format=json&$expand=City,Orders

Advanced queries

Predicates

• If you need to write or statements in your queries, you need to use the Predicate class. First, be sure to reference the $odata dependency.

myModule.controller('MyController', ['$scope','$odataresource','$odata',function($scope,$odataresource,$odata){}]);

• Now you can use the $odata.Predicate class wich allow advanced filtering.

var predicate1 = new $odata.Predicate("FirstName", "John");
var predicate2 = new $odata.Predicate("LastName", '!=', "Doe");
//
combination = $odata.Predicate.or([predicate1,predicate2]);
User.odata().filter(combination).query();
//Queries /user?$filter=(FirstName eq 'John') or (LastName ne 'Doe');

• You can even combine predicates with predicates

var predicate1 = new $odata.Predicate("FirstName", "John");
var predicate2 = new $odata.Predicate("LastName", '!=', "Doe");
var predicate3 = new $odata.Predicate("Age", '>', 10);
//
combination1 = $odata.Predicate.or([predicate1,predicate2]);
combination2 = $odata.Predicate.and([combination1,predicate2]);
User.odata().filter(combination).query();
//Queries /user?$filter=((FirstName eq 'John') or (LastName ne 'Doe')) and Age gt 10

• You can also achieve the same results with the fluent api

var predicate = new $odata.Predicate("FirstName", "John")
                            .or(new $odata.Predicate("LastName", '!=', "Doe"))
                            .and(new $odata.Predicate("Age", '>', 10));
//
User.odata().filter(predicate).query();
//Queries /user?$filter=((FirstName eq 'John') or (LastName ne 'Doe')) and Age gt 10

Overriding default Predicate or Filter behavior

It is sometime necessary to compare two properties or two values in a query. To do so, you can use the $odata.Value or $odata.Property classes

var predicate = new $odata.Predicate(
                            new $odata.Value('Foo'),
                            new $odata.Value('Bar')
                            );
//
User.odata().filter(predicate).query();
//Queries /user?$filter='Foo' eq 'Bar'

Or with two properties :

User.odata().filter(
                    new $odata.Property('Name'),
                    new $odata.Property('Surname')
                    ).query();
//Queries /user?$filter=Name eq Surname

Specifying the type of the data

This library is clever enough to figure out the types from the data passed and format them accordingly. But sometimes you may need to have a specific output type. In this case you can pass a second argument to the $odata.Value() constructor :

User.odata().filter(
                    'Latitude',
                    new $odata.Value(40.765150,"Decimal")
                    ).query();
//Queries /user?$filter=Latitude eq 40.765150M

User.odata().filter(
                    'Latitude',
                    new $odata.Value("75.42","Int32")
                    ).query();
//Queries /user?$filter=Latitude eq 75


User.odata().filter(
                    'Latitude',
                    new $odata.Value("true","Boolean")
                    ).query();
//Queries /user?$filter=Latitude eq true


User.odata().filter(
                    'Latitude',
                    new $odata.Value(10,"Boolean")
                    ).query();
//Queries /user?$filter=Latitude eq true

Here is the complete list of supported types :

Type Name	Output example
Boolean	true
Byte	FE
DateTime	datetime'2000-12-12T12:00'
Decimal	2.345M
Double	2.0d
Single	2.0f
Guid	guid'12345678-aaaa-bbbb-cccc-ddddeeeeffff'
Int32	51358
String	'Hello OData'

Function calls

• You can call functions like endswith or length on an OData query. To do so, use the $odata.Func class.

var users = User.odata()
              .filter(new $odata.Func("endswith","FullName","Doe"), true)
              .query();
//Queries /user?$filter=endswith(FullName, 'Doe') eq true

Definition

new $odata.Func(MethodName, PropertyName, Value1, Value2,...)

The parameters are assumed to be first, a property and then a value. This behavior can be overriden by specifying explicit values or properties :

new $odata.Func('substringof',
                  new $odata.Value('Alfreds'),
                  new $odata.Property('CompanyName'));

List of available functions

Function	Example	Example value
String Functions
bool substringof(string po, string p1)	new $odata.Func('substringof',new $odata.Value('Alfreds'), new $odata.Property(CompanyName))