REQUEST FOR COMMENT: $resource rewrite

[Misko Hevery]

Hello Angular Users,

WARNING: WORK IN PROGRESS

The last piece which is missing to call angular 1.0 are the $resources. They have been rewritten from scratch and should be a lot more flexible. I was hopping to get some feedback from you to see if we have answered all of your concerns, and if the documentation makes sense.

Please read:

• http://ci.angularjs.org/job/angular.js-misko/449/artifact/build/pkg/1.0.0rc2-ef6f25ca/docs-1.0.0rc2-ef6f25ca/api/angular.module.ng.$resource
• http://ci.angularjs.org/job/angular.js-misko/449/artifact/build/pkg/1.0.0rc2-ef6f25ca/docs-1.0.0rc2-ef6f25ca/api/angular.module.ng.$resource.Option

See the code:

• https://github.com/mhevery/angular.js/commit/ef6f25ca0045b3ee05d626288a456c15eafa72f0
• https://github.com/mhevery/angular.js/blob/ef6f25ca0045b3ee05d626288a456c15eafa72f0/src/service/resource.js

Take it for a spin:

• http://jsfiddle.net/7HcFZ/

Then tell us what you think:

• DOCS: Then point out mistakes and what is not making any sense, what needs more explanation (still very much work in progress)
• API: Do names make sense? Suggestions?

[Dan Doyon]

Misko,

 

A lot to take in, here is a smattering of questions/comments

 

1. In the example you are not using token replace for ‘name’, I think it would be good to have in example.

 

1b. It appears that ‘:foo’ is gone in favor of ‘{{foo}}’

 

2. I like the- response: ‘response.data.results’ but am wondering if maybe named something different.  If I’m correct in my understanding,  it’s a way of targeting the response object. So, If you return

{"results":[{"author":"misk","title":"AngularJS"},

        {"author":"ferdo3","title":"ferdo's adventures"}],

"counter": "2" }

then you would have as a response

[{"author":"misk","title":"AngularJS},{"author":"ferdo3","title":"ferdo's adventures”}]

 

How about something like responseTarget?

 

3. It’s going to take a bit to fully digest the internalize/externalize stuff. It seems that you are giving the ability to have a formalized approach to applying “transforms” (or not) to the returned data. Since you are able to declare these functions, it makes it very testable and of course that’s always a good thing.

 

4. The doc on Task has confusing elements, I’m going to have to read and reread. I’ll post questions later.

 

That’s all I have for now, I’m sure I’ll have more

 

--dan

--
You received this message because you are subscribed to the Google Groups "AngularJS" group.
To post to this group, send email to ang...@googlegroups.com.
To unsubscribe from this group, send email to angular+u...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/angular?hl=en.

---

No virus found in this message.
Checked by AVG - www.avg.com
Version: 10.0.1424 / Virus Database: 2113/4886 - Release Date: 03/22/12

[oluckyman]

Thanks Misko.

I owe you guys one because I got a T-shirt with the least effort :-)

So here's some feedback on the new $resource, and more generally.

It's all well-intentioned.

I have a simple spike with a RESTful JSON backend. It fetches all "partner" objects, and the user can select one, and update it.

The backend isn't fully RESTful: a bulk query returns an array embedded in some extra JSON, and an update requires the object to be embedded in extra JSON.

I previously resorted to some lower-level code, and requested that the update to $resource be able to handle my situation.

My previous code:

/* service */

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

var myUrl = 'http://json.site.com/Partner/';

myApp.factory('Partners', function($resource) {

  return $resource(myUrl+':partner_id', {});

});

/* controller */

function PartnersCtrl($scope, $http, Partners) {

  $scope.refreshPartners = function() {

    // more complex code since get produces a decorated array:

    var ret = Partners.get({}, function(){

      ret.$get(); 

      $scope.partners = ret.response.data;

    });

  }

  $scope.selectPartner = function(p) {

    $scope.partner = p;

  }

  $scope.savePartner = function() {

    // lower-level code since original get doesn't produce an array:

    $http.post(myUrl+$scope.partner.id, {data:$scope.partner});

    $scope.partner = null;

  }

}

This is not pretty, but it's not hard to follow.

The new code :

/* service */

var myUrl = 'http://json.site.com/Partner/';

angular.module('myApp', [], function($provide) {

  $provide.factory('partnersFactory', function($resource) {

    return $resource(

      { url: myUrl },

      function(Resource, rsrcMethod) {

        angular.extend(Resource, {

          externalize:

            function(self) {

              var myself = angular.copy(self);

              return {data: myself};

            },

          query: rsrcMethod('', { response: 'response.data.response.data' })

        });

        angular.extend(Resource.prototype, {

          $save: rsrcMethod('self', { method: 'PUT', request: true, url: '{{url}}{{self.id}}' })

        });

      }

    );

  });

  $provide.factory('Partners', function(partnersFactory) {

    return partnersFactory.create();

  });

});

/* controller */

function PartnersCtrl($scope, Partners) {

  $scope.refreshPartners = function() {

    Partners.query().then(function(partners) {

      $scope.partners = partners;

    });

  }

  $scope.selectPartner = function(p) {

    $scope.partner = p;

  }

  $scope.savePartner = function() {

    $scope.partner.$save($scope.partner);

    $scope.partner = null;

  }

}

The new code works, and the controller is better: clean and simple.

The service code does as little as necessary.

All of which is excellent.

But it is considerably harder to grok, because there are a lot of layers of abstraction.

I think this change usefully illustrates the strength and weakness of AngularJS.

The strength is its power and conceptual rigor (and its testing story, which derives from these qualities).

The weakness is a practical rather than intellectual matter: the heavy use of DI and functional OO will be hard for many to grasp.

Web developers with a Java EE background won't feel out of place. A factory is a factory is a factory.

But the PHP crowd will be lost. [Insert joke]

OK, they are extremes.

But I think even many RoR developers will find AngularJS's conceptual universe a challenge.

There is anecdotal evidence of this: the word on the street is that AngularJS has a steeper learning curve than competitors.

Of course, your response is that the extra investment to understand it will pay big long-term dividends.

I agree, but I'm afraid that many won't make the effort.

People make firm judgements after minimal investigation. I'm sure you've seen this with AngularJS.

My 2c: For widespread adoption, AngularJS should aim to require minimal code for the easy cases.

Talking to a fully compliant RESTful JSON service is one of these.

The developer should not need to supply much more than a URL with parameter placeholders.

I.e., the developer should not need to be fully aware of all the behind the scenes machinery.

(Maybe this is already the case with the new $resource. Hard for me to tell, since of course that wasn't your aim with the demo)

A practical issue might be that much of your direct feedback comes from internal Google users.

They are (in my experience) both very smart & well-educated, and not typical web devs.

There are also plenty of talented people on this newsgroup.

Their feedback is invaluable for the more challenging use cases.

But I would recommend as much attention be paid to the inexperienced developers, on this group, and with case studies and documentation.

Cheers,

Paul

[Peter Bacon Darwin]

Hi Paul

Can you not implement your service in fewer lines  something like this?

Partners = function() {};

Partners.externalize = function(self) {

   var myself = angular.copy(self);

   return {data: myself};

};

angular.module('myApp', []).factory('Partners', function($resource) {

  return $resource({ url:myUrl }, function(Partners, rsrcMethod){

    Partners.query = rsrcMethod('', {response: 'response.data'});

    Partners.$save: rsrcMethod('self', { method: 'PUT', request: true, url: '{{url}}{{self.id}}' })

  }).create(Partners);

}

--

You received this message because you are subscribed to the Google Groups "AngularJS" group.

To view this discussion on the web visit https://groups.google.com/d/msg/angular/-/LfzyegAo3Y8J.

[Misko Hevery]

Hi Paul,

Thanks for your feedback and concreet real world experience. It is just what we are looking for.

First I see that I need to do more work with docs since your code can be rewritten much simpler. Could you give it a try and let me know if it works?

angular.module('paul', []).

  factory('paulRestResource', function($resource){

    // this will be used to stamp out lots of resources

    return function(name) {

      return $resource({

         url:'someUrl/' + name + '/', 

         request: '{data: data}', // wrap the data in data object

         response: 'response.data.response.data'}, // when response comes look here for data

         function(Rsrc, method){

            Rsrc.query = method('params');

            Rsrc.save = method('self', {method: 'PUT'});

            Rsrc.delete = method('', {method: 'DELETE', url: '{{url}}{{self.id}}'});

            // and so on 

         }

      );

    }

  }).

  // Then just stamp out the instances...

  factory('Partners', function(paulRestResource) {

    return paulRestResource('Partners').create();

  })

  factory('Customers', function(paulRestResource) {

    return paulRestResource('Customers').create();

  })

 

The new code works, and the controller is better: clean and simple.

The service code does as little as necessary.

All of which is excellent.

But it is considerably harder to grok, because there are a lot of layers of abstraction.

There is no need to use internalize/externalize, since you are not change the structure of the object. The request/response deal with where the object should be placed in request and where we should look for it in response.

 

I think this change usefully illustrates the strength and weakness of AngularJS.

The strength is its power and conceptual rigor (and its testing story, which derives from these qualities).

The weakness is a practical rather than intellectual matter: the heavy use of DI and functional OO will be hard for many to grasp.

Could you suggest what would your ideal syntax look like, and we will see if we could use it...

 

Web developers with a Java EE background won't feel out of place. A factory is a factory is a factory.

But the PHP crowd will be lost. [Insert joke]

OK, they are extremes.

But I think even many RoR developers will find AngularJS's conceptual universe a challenge.

So we are thinking of providing modules for common technologies such as RoR so that they can hook up the resources to their RoR backend supper easy. Which remains me, do you know of any RoR folks who could help us work on it?

 

There is anecdotal evidence of this: the word on the street is that AngularJS has a steeper learning curve than competitors.

Of course, your response is that the extra investment to understand it will pay big long-term dividends.

I agree, but I'm afraid that many won't make the effort.

People make firm judgements after minimal investigation. I'm sure you've seen this with AngularJS.

Really, we were hoping that we would be easier. I think more tutorials/videos would solve that.

 

My 2c: For widespread adoption, AngularJS should aim to require minimal code for the easy cases. 

Talking to a fully compliant RESTful JSON service is one of these.

The developer should not need to supply much more than a URL with parameter placeholders.

I.e., the developer should not need to be fully aware of all the behind the scenes machinery.

(Maybe this is already the case with the new $resource. Hard for me to tell, since of course that wasn't your aim with the demo)

+1 as I said the backend technology modules should help here.

 

A practical issue might be that much of your direct feedback comes from internal Google users.

They are (in my experience) both very smart & well-educated, and not typical web devs.

There are also plenty of talented people on this newsgroup.

Their feedback is invaluable for the more challenging use cases.

But I would recommend as much attention be paid to the inexperienced developers, on this group, and with case studies and documentation.

+1 concerete suggestions would be awesome. 

[Misko Hevery]

Hi Dan,

On Thu, Mar 22, 2012 at 8:29 PM, Dan Doyon <dand...@yahoo.com> wrote:

Misko,

 

A lot to take in, here is a smattering of questions/comments

 

1. In the example you are not using token replace for ‘name’, I think it would be good to have in example.

 

1b. It appears that ‘:foo’ is gone in favor of ‘{{foo}}’

 

Yes, there were a lot of issues with :foo, and people already understand {{foo}} so we thought it would be better

 

2. I like the- response: ‘response.data.results’ but am wondering if maybe named something different.  If I’m correct in my understanding,  it’s a way of targeting the response object. So, If you return


{"results":[{"author":"misk","title":"AngularJS"},

        {"author":"ferdo3","title":"ferdo's adventures"}],

"counter": "2" }

then you would have as a response

[{"author":"misk","title":"AngularJS},{"author":"ferdo3","title":"ferdo's adventures”}]

almost. The response is the response from the $http service. it hase properties such as headers, as well as data. So response.data points to what the server sent back. So in your case you would need to do 'response.data.results' to get at the actual data.

 

 

How about something like responseTarget?

Can you explain your thinking?

[Dan Doyon]

Hi Misko,

 

So when I look at this snippet, the ‘url’ and ‘headers’ params make total sense. What doesn’t make 100% sense immediately is ‘response’.  I know I’m going to get a response back but there is a param called ‘response’ with ‘response’ inside the literal.  I pretty much got it at first glance, but it may be confusing for others.  I was thinking that a different param name may be more clear. Instead of responseTarget use responseExpression or responseExpr? I don’t think it’s a real big deal if it’s well documented

 

Also, your doc says it’s a method not an expression.

 

One other question, could you have url: 'https://api.parse.com/1/classes/{{name}}/' instead?

 

return $resource(
        {
          url: 'https://api.parse.com/1/classes/' + name  + '/',
          headers: {
            'X-Parse-Application-Id': parseAppId,
            'X-Parse-REST-API-Key': parseApiKey,
            'X-Requested-With': undefined
          },
          response: 'response.data.results'
        }

 

thanks

Version: 10.0.1424 / Virus Database: 2113/4889 - Release Date: 03/23/12

[Adam Pohorecki]

Hi Misko,

On Fri, Mar 23, 2012 at 6:24 PM, Misko Hevery <mi...@hevery.com> wrote:
> On Fri, Mar 23, 2012 at 6:50 AM, Peter Bacon Darwin <pe...@bacondarwin.com>
> wrote:
>>>
>>> Web developers with a Java EE background won't feel out of place. A
>>> factory is a factory is a factory.
>>> But the PHP crowd will be lost. [Insert joke]
>>> OK, they are extremes.
>>> But I think even many RoR developers will find AngularJS's conceptual
>>> universe a challenge.
>
>
> So we are thinking of providing modules for common technologies such as RoR
> so that they can hook up the resources to their RoR backend supper easy.
> Which remains me, do you know of any RoR folks who could help us work on it?
>

I would gladly do it. Just let me know what do you have in mind.

Best regards,
Adam Pohorecki

[Misko Hevery]

On Fri, Mar 23, 2012 at 11:03 AM, Dan Doyon <dand...@yahoo.com> wrote:

Hi Misko,

 

So when I look at this snippet, the ‘url’ and ‘headers’ params make total sense. What doesn’t make 100% sense immediately is ‘response’.  I know I’m going to get a response back but there is a param called ‘response’ with ‘response’ inside the literal.  I pretty much got it at first glance, but it may be confusing for others.  I was thinking that a different param name may be more clear. Instead of responseTarget use responseExpression or responseExpr? I don’t think it’s a real big deal if it’s well documented

So perhaps dataExtract, dataLocation???

 

 

Also, your doc says it’s a method not an expression.

 

One other question, could you have url: 'https://api.parse.com/1/classes/{{name}}/' instead?

I was thinking about that as well, but have not been able to put it together in a consistent API

[Misko Hevery]

I would gladly do it. Just let me know what do you have in mind.

So RoR has the ability to do JSON REST, what I am looking for is a module which angular would optionally provide which would make life for anyone wanting to talk to RoR backend supper easy. Here is what I have in mind. I need help with the '????' portion

================ Angular Provides ====================== 

angular.module('ng.resource.rails', []).

  factory('$railsResource', function($resource){

    return $resource({

      url: '/{{name}}/'

    }, function(Rsrc, method) {

      Rsrc.index = method(????);

      Rsrc.get = method(????);

      Rsrc.create = method(????);

      Rsrc.update = method(????);

      Rsrc.destroy = method(????);

      Rsrc.prototype.$create = method(????); 

      Rsrc.prototype.$update = method(????); 

      Rsrc.prototype.$destroy = method(????); 

    });

  });

================ Angular Provides ====================== 

================ Developer Uses ====================== 

angular.module('myApp', ['ng.resource.rails']).

  factory('Book', function($railsResource) {

    return $railsResource({name:'Book'}).create();

  }).

  factory('Chapter', function($railsResource) {

    return $railsResource({name:'Chapter'}).create();

  }).

  factory('Author', function($railsResource) {

    return $railsResource({name:'Author'}).create();

  }).

================ Developer Uses ====================== 

[Dan Doyon]

I was actually thinking about something “dataXXX” instead of response, I kinda like dataLocation. I don’t know, I’d be interested for someone else to chime in. Maybe I’m overthinking things.

[oluckyman]

Thanks Misko!

Your MUCH simpler code worked fine, after I added the url to the definition of save.

I don't think your documentation is likely to be at fault.

I was in a rush and just worked from your sample code after realizing I'd have to spend more time to grok the documentation.

I get the function(name) wrapper, and will of course use that in practice; I just dropped it for simplicity originally.

So now I think this is as simple and clear as can be expected.

However, it seems that with the new $resource, the methods get, query, delete, create, save have to be explicitly defined, whereas previously they were predefined.

Since their definitions in your code are now completely conventional, is there a way to provide them automatically?

Ironically, I realize I am one of those who judged AngularJS too quickly without a thorough read of the documentation.

Sort of proving my own point!

I think the documentation is wonderful (and educational), but perhaps looks scary to those without an OO background.

In such cases people will try to work from existing examples.

So I think it's super important to have a bunch of easy to find examples for the common cases, such as RESTful JSON.

The more I learn the more impressed I am.

Cheers,

Paul

To unsubscribe from this group, send email to angular+unsubscribe@​googlegroups.com.

For more options, visit this group at http://groups.google.com/​group/angular?hl=en.

--
You received this message because you are subscribed to the Google Groups "AngularJS" group.
To post to this group, send email to ang...@googlegroups.com.

To unsubscribe from this group, send email to angular+unsubscribe@​googlegroups.com.

To unsubscribe from this group, send email to angular+unsubscribe@​googlegroups.com.

For more options, visit this group at http://groups.google.com/​group/angular?hl=en.

--
You received this message because you are subscribed to the Google Groups "AngularJS" group.
To post to this group, send email to ang...@googlegroups.com.

To unsubscribe from this group, send email to angular+unsubscribe@​googlegroups.com.

[zdam]

Hi Misko,

Could you together a module like this for backward compatibility so that the new resource design matches the old resource design - that way when upgrading from rc2 we just need to make very minor changes to our code.

eg.

angule.module('ng.resource.backwardCompatibleResource', []).

factory('$oldResource', function($resource){

// todo configures so behaviour is same as old resource

}) 

Cheers, Adam.

[Vojta Jína]

Hey Adam,

you can do this very simply, just copy the $resource code from current
angular (https://github.com/angular/angular.js/blob/master/src/service/resource.js)
and override the new implementation... (or add it with $resourceBC
name or whatever you like).

V.

> --
> You received this message because you are subscribed to the Google Groups
> "AngularJS" group.
> To view this discussion on the web visit

> https://groups.google.com/d/msg/angular/-/Cq3G3gtobx8J.

[zdam]

Hi,

Yeah I was really treating this as a way for you guys to show us how you might create a custom resource for a custom backend technology, like the ROR example Misko asked for above.

What better way to show off how the new resource design can be used to create factories suited to particular server technologies than to use that same power to build a backwards compatible resource module.

Simply copying the existing code is going to work, but doesn't demonstrate the features of the new resource design.

Cheers, Adam

> angular+unsubscribe@​googlegroups.com.

[Vojta Jína]

Thanks Adam, that's interesting point, I didn't realized that before...
We might try to do that, depending on how far the design gonna be :-D

V.

>> > angular+u...@googlegroups.com.

>> > For more options, visit this group at
>> > http://groups.google.com/group/angular?hl=en.
>

> --
> You received this message because you are subscribed to the Google Groups
> "AngularJS" group.
> To view this discussion on the web visit

> https://groups.google.com/d/msg/angular/-/96-pf7UKPi0J.

>
> To post to this group, send email to ang...@googlegroups.com.
> To unsubscribe from this group, send email to

> angular+u...@googlegroups.com.

[Misko Hevery]

Hi All,

I spent a lot of time thinking about this over the weekend, and realized that the new design while better, does not address many of the real world issues, namely, the ability to have nested resources, and uniform ways of dealing with the ids. 

So after thinking about it some more, we decided to take the resources out of angular core and put them in a separate module. That way we can release angular v1.0.0 and have the resources have its own life, as i don't think we are going to get something we like in the next week or two, and there is no reason to stall the core of angular. It also means that you will be able to chose different resource implementations for yourself.

-- misko

[Dan Doyon]

Misko,

What would be great is if you could make the original $resource functionality in a module that could coincide with 1.0?? Maybe have an ng-contrib namespace?

That would help a lot

--dan

[Robert B. Weeks]

> Misko,
>
> What would be great is if you could make the original $resource functionality in a module that could coincide with 1.0?? Maybe have an ng-contrib namespace?
>
> That would help a lot

Yes - that would help *tremendously*. I was just thinking of trying to do that since this isn't going to be in 1.0.0 and one of our apps that is being converted relies on it quite a bit.

Thanks.

> --dan
>
>
> On Mar 26, 2012, at 10:34 AM, Misko Hevery wrote:
>
>> Hi All,
>>
>> I spent a lot of time thinking about this over the weekend, and realized that the new design while better, does not address many of the real world issues, namely, the ability to have nested resources, and uniform ways of dealing with the ids.
>>
>> So after thinking about it some more, we decided to take the resources out of angular core and put them in a separate module. That way we can release angular v1.0.0 and have the resources have its own life, as i don't think we are going to get something we like in the next week or two, and there is no reason to stall the core of angular. It also means that you will be able to chose different resource implementations for yourself.
>>
>> -- misko

--
Robert B. Weeks

[Tobias Bosch]

Hi Misko,

right now I am working with Dojo and their stores. They use json references (like {$reference: 'someUrl/123'}) for references to other resources. Maybe also something for the id/reference handling of $resource?

Maybe it's out of scope for $resource, but lazy loading and automatic dirty checking / saving only the changed object instances would also be very nice, especially for the CRUD parts of an application. Some kind of "persistence context" or so... 

Dojo implements this with their stores, and it gives use a good speed in the development of forms with master-detail lists.

Would be awesome to see something like this in angular too!

I like your decision to make a separate module for $resource, and am looking forward to the 1.0 release!

Tobias

-- misko

>> > angular+unsubscribe@googlegroups.com.

>> > For more options, visit this group at
>> > http://groups.google.com/group/angular?hl=en.
>
> --
> You received this message because you are subscribed to the Google Groups
> "AngularJS" group.
> To view this discussion on the web visit
> https://groups.google.com/d/msg/angular/-/96-pf7UKPi0J.
>
> To post to this group, send email to ang...@googlegroups.com.
> To unsubscribe from this group, send email to

> angular+unsubscribe@googlegroups.com.

> For more options, visit this group at
> http://groups.google.com/group/angular?hl=en.

--
You received this message because you are subscribed to the Google Groups "AngularJS" group.

To post to this group, send email to ang...@googlegroups.com.

To unsubscribe from this group, send email to angular+unsubscribe@googlegroups.com.

[Max Martinsson]

Often when you do remote calls, you want the UI to show the user that a request is in progress. I see that in your jsfiddle, you for example use  $scope.form.working for disabling the buttons when a request is being made. But it's a bit cumbersome to manually have to set that variable to true and then back to false at the right moments.

Wouldn't it be easiest if the mock object that is immediately returned by the resource contained a field with the current status of the request? For example, there could be a boolean "$working" field, maybe and also a "$status" field that contains the name of the current method (e.g. "save" or "delete"). 

Then it would be a simple matter of having 

 <span ng-show="tasks.$working">Loading tasks .... </span>

to inform the user about what's going on.

Since I haven't found anything like this in Angular at the moment, I've done this myself by wrapping the $resource, but it would be nice to have it "vanilla" :)

What do you think?