From 8ef99ec984deb21998c5ce56b669c710caa70714 Mon Sep 17 00:00:00 2001 From: Yiling Lu Date: Wed, 20 May 2015 02:40:24 -0700 Subject: [PATCH] docs($resourceProvider): provide info and example for configuring $resourceProvider --- src/ngResource/resource.js | 80 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 80 insertions(+) diff --git a/src/ngResource/resource.js b/src/ngResource/resource.js index 2e8aee50a77a..fb0975c4665e 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. + * */ /** @@ -349,6 +367,52 @@ angular.module('ngResource', ['ng']). provider('$resource', function() { 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, @@ -363,6 +427,22 @@ angular.module('ngResource', ['ng']). } }; + /** + * @ngdoc method + * @name $resourceProvider#$get + * @description Method used by angular DI system to create a `$resourceProvider` instance. + * + * User applications shouldn't need to call this method directly. + * This shows the fact that {@link ngResource.$resource $resource} + * is a high level service built by leveraging {@link ng.$http $http} service. + * + * @param {Object} $http An instance of {@link ng.$http $http} service. + * + * @param {Object} $q An instance {@link ng.$q $q}, Angular's implementation of deferred API. + * + * + * @returns {Function} A factory function, when invoked, returns a $resource object. + */ this.$get = ['$http', '$q', function($http, $q) { var noop = angular.noop,