From a791bf9dde475671f6b64c91bafb2a441d2e6c96 Mon Sep 17 00:00:00 2001 From: Yiling Lu Date: Wed, 20 May 2015 02:40:24 -0700 Subject: [PATCH 1/3] docs($resourceProvider): provide info and example for configuring $resourceProvider --- src/ngResource/resource.js | 64 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) diff --git a/src/ngResource/resource.js b/src/ngResource/resource.js index 1a157b481872..d29139d3c743 100644 --- a/src/ngResource/resource.js +++ b/src/ngResource/resource.js @@ -57,6 +57,24 @@ function shallowClearAndCopy(src, dst) { *
* * See {@link ngResource.$resource `$resource`} for usage. + * + * See {@link ngResource.$resourceProvider `$resourceProvider`} for usage. + */ + +/** + * @ngdoc provider + * @name $resourceProvider + * + * @description + * + * Use for configuring {@link ngResource.$resource `$resource`} in module configuration phase. + * + * ## Example + * See {@link ngResource.$resourceProvider#defaults `Properties`} for configuring `ngResource`. + * + * ## Dependencies + * Requires {@link ngResource `ngResource`} module to be installed. + * */ /** @@ -402,6 +420,52 @@ angular.module('ngResource', ['ng']). var PROTOCOL_AND_DOMAIN_REGEX = /^https?:\/\/[^\/]*/; var provider = this; + /** + * @ngdoc property + * @name $resourceProvider#defaults + * @description + * A configuration object for `$resource` instances. + * + * Properties of this object are initialized with a set of values that satisfies a wide range of use cases. + * User can also choose to override these properties in application configuration phase. + * + * Property `stripTrailingSlashes`, default to true, strips trailing slashes from + * calculated URLs. + * + * Property `actions` is an object that sets up high level methods/aliases on `$resource` object + * based on standard HTTP methods. Users can supply an "actions" object with method aliases that + * comply with alternative conventions. + * + * To add your own set of configurations, set it up like so: + * ``` + * angular.module('myApp').config(['resourceProvider', function ($resourceProvider){ + * + * // Provide your own set of actions on $resource factory. + * // The following comments are Angular's default actions, which are being + * // replaced by an object that includes a PUT method as shown. + * // { 'get': {method:'GET'}, + * // 'save': {method:'POST'}, + * // 'query': {method:'GET', isArray:true}, + * // 'remove': {method:'DELETE'}, + * // 'delete': {method:'DELETE'} }; + * + * $resourceProvider.defaults.actions = { + * create:{method: 'POST'}, + * save: {method: 'POST'}, + * update:{method: 'PUT'}, + * get: {method: 'GET'}, + * query: {method: 'GET', isArray:true}, + * remove: {method: 'DELETE'}, + * delete: {method: 'DELETE'} + * }; + * + * // Don't strip trailing slashes from calculated URLs. + * // Consult your application server's configuration to work in concert with this setting. + * $resourceProvider.defaults.stripTrailingSlashes = false; + * }]); + * ``` + * + */ this.defaults = { // Strip slashes by default stripTrailingSlashes: true, From dcbbe22c029877f5c7a11cc89d29b6cec1df11aa Mon Sep 17 00:00:00 2001 From: Georgios Kalpakas Date: Fri, 3 Jun 2016 15:21:08 +0300 Subject: [PATCH 2/3] docs($resourceProvider): improve wording and formatting Closes #11910 --- src/ngResource/resource.js | 95 ++++++++++++++++++++++---------------- 1 file changed, 55 insertions(+), 40 deletions(-) diff --git a/src/ngResource/resource.js b/src/ngResource/resource.js index d29139d3c743..414f54241cba 100644 --- a/src/ngResource/resource.js +++ b/src/ngResource/resource.js @@ -56,9 +56,7 @@ function shallowClearAndCopy(src, dst) { * *
* - * See {@link ngResource.$resource `$resource`} for usage. - * - * See {@link ngResource.$resourceProvider `$resourceProvider`} for usage. + * See {@link ngResource.$resourceProvider} and {@link ngResource.$resource} for usage. */ /** @@ -67,13 +65,11 @@ function shallowClearAndCopy(src, dst) { * * @description * - * Use for configuring {@link ngResource.$resource `$resource`} in module configuration phase. - * - * ## Example - * See {@link ngResource.$resourceProvider#defaults `Properties`} for configuring `ngResource`. + * Use `$resourceProvider` to change the default behavior of the {@link ngResource.$resource} + * service. * * ## Dependencies - * Requires {@link ngResource `ngResource`} module to be installed. + * Requires the {@link ngResource } module to be installed. * */ @@ -424,45 +420,64 @@ angular.module('ngResource', ['ng']). * @ngdoc property * @name $resourceProvider#defaults * @description - * A configuration object for `$resource` instances. + * Object containing default options used when creating `$resource` instances. * - * Properties of this object are initialized with a set of values that satisfies a wide range of use cases. - * User can also choose to override these properties in application configuration phase. + * The default values satisfy a wide range of usecases, but you may choose to overwrite any of + * them to further customize your instances. The available properties are: * - * Property `stripTrailingSlashes`, default to true, strips trailing slashes from - * calculated URLs. + * - **stripTrailingSlashes** – `{boolean}` – If true, then the trailing slashes from any + * calculated URL will be stripped.
+ * (Defaults to true.) + * - **cancellable** – `{boolean}` – If true, the request made by a "non-instance" call will be + * cancelled (if not already completed) by calling `$cancelRequest()` on the call's return + * value. For more details, see {@link ngResource.$resource}. This can be overwritten per + * resource class or action.
+ * (Defaults to false.) + * - **actions** - `{Object.}` - A hash with default actions declarations. Actions are + * high-level methods corresponding to RESTful actions/methods on resources. An action may + * specify what HTTP method to use, what URL to hit, if the return value will be a single + * object or a collection (array) of objects etc. For more details, see + * {@link ngResource.$resource}. The actions can also be enhanced or overwritten per resource + * class.
+ * The default actions are: + * ```js + * { + * get: {method: 'GET'}, + * save: {method: 'POST'}, + * query: {method: 'GET', isArray: true}, + * remove: {method: 'DELETE'}, + * delete: {method: 'DELETE'} + * } + * ``` * - * Property `actions` is an object that sets up high level methods/aliases on `$resource` object - * based on standard HTTP methods. Users can supply an "actions" object with method aliases that - * comply with alternative conventions. + * #### Example * - * To add your own set of configurations, set it up like so: - * ``` - * angular.module('myApp').config(['resourceProvider', function ($resourceProvider){ + * For example, you can specify a new `update` action that uses the `PUT` HTTP verb: * - * // Provide your own set of actions on $resource factory. - * // The following comments are Angular's default actions, which are being - * // replaced by an object that includes a PUT method as shown. - * // { 'get': {method:'GET'}, - * // 'save': {method:'POST'}, - * // 'query': {method:'GET', isArray:true}, - * // 'remove': {method:'DELETE'}, - * // 'delete': {method:'DELETE'} }; + * ```js + * angular. + * module('myApp'). + * config(['resourceProvider', function ($resourceProvider) { + * $resourceProvider.defaults.actions.update = { + * method: 'PUT' + * }; + * }); + * ``` * - * $resourceProvider.defaults.actions = { - * create:{method: 'POST'}, - * save: {method: 'POST'}, - * update:{method: 'PUT'}, - * get: {method: 'GET'}, - * query: {method: 'GET', isArray:true}, - * remove: {method: 'DELETE'}, - * delete: {method: 'DELETE'} - * }; + * Or you can even overwrite the whole `actions` list and specify your own: * - * // Don't strip trailing slashes from calculated URLs. - * // Consult your application server's configuration to work in concert with this setting. - * $resourceProvider.defaults.stripTrailingSlashes = false; - * }]); + * ```js + * angular. + * module('myApp'). + * config(['resourceProvider', function ($resourceProvider) { + * $resourceProvider.defaults.actions = { + * create: {method: 'POST'} + * get: {method: 'GET'}, + * getAll: {method: 'GET', isArray:true}, + * update: {method: 'PUT'}, + * delete: {method: 'DELETE'} + * }; + * }); * ``` * */ From 2da56945db5442a49bdc8ec379ce31438c7f7c40 Mon Sep 17 00:00:00 2001 From: Georgios Kalpakas Date: Fri, 3 Jun 2016 15:22:19 +0300 Subject: [PATCH 3/3] refactor($resource): explicitly set `$resourceProvider.defaults.cancellable` to false Previously, it was just `undefined` and had the same behavior (since we only check for falsy-ness). Just making it explicit, that this property is also available on `defaults` and is "not true" by default. --- src/ngResource/resource.js | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/ngResource/resource.js b/src/ngResource/resource.js index 414f54241cba..77ef274be0c6 100644 --- a/src/ngResource/resource.js +++ b/src/ngResource/resource.js @@ -485,6 +485,9 @@ angular.module('ngResource', ['ng']). // Strip slashes by default stripTrailingSlashes: true, + // Make non-instance requests cancellable (via `$cancelRequest()`) + cancellable: false, + // Default actions configuration actions: { 'get': {method: 'GET'},