angularjs-rails-resource 0.2.5 → 1.0.0.pre.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3af2e27b94554d7c76725e83fbafe496f428dba6
-  data.tar.gz: 49b9c83300358da0e4aa970949ee48c1b0d7671f
+  metadata.gz: 6949c58b7d5354dcb4b311248088c8f831c958c6
+  data.tar.gz: da054ff28d6285541d7f0e5a1deb23b3b83fb91c
 SHA512:
-  metadata.gz: 138e28efba7ce29cc39fbdfbfa07435b8709237664219ea5169c2fbe390fb47f074afd45fb3d9603f2860014b1ceba3c7332b12630cba2f66368e0af610da732
-  data.tar.gz: abb4c0ced83000383d828540957cf2cefe769ff25dc507e5d1be7a7b9a3ac105437188b4ca1121d72a4aff2f602e4d48d4b70f732423924b31971c94ffe75187
+  metadata.gz: 8e2c661c2fcd2df398eeeb071c607f39e258f53e28bd5e9c9670616182a7a984ecb786ba91b2a680fc71299479f6e3a97e6449a6a8bd759743c59e36452bdee3
+  data.tar.gz: f63c1513e65a2254390bc3205eaeb0541b2f35f6c24669f8d52b140f2a4ff9f5fc8ea9b6bd641781d5f66fdc9ba1e09497adc73148163b7f056766136c32f69b

data/CHANGELOG.md

@@ -1,3 +1,19 @@
+<a name="1.0.0"></a>
+# 1.0.0
+## Bug Fixes
+
+## Features
+- Added <code>configure</code> to allow changing configuration options after the resource has been initially configured.
+
+## Breaking Changes
+- <code>railsResourceFactoryProvider</code> settings have been moved to <code>RailsResourceProvider</code>
+- <code>wrapData</code> config option has been renamed <code>rootWrapping</code>
+- All resource settings are now stored under the <code>config</code> property on the resource and should be modified using the <code>configure</code> function.
+- The following resource settings have been renamed:
+    - <code>enableRootWrapping</code> was renamed <code>rootWrapping</code>
+    - <code>rootName</code> was renamed <code>name</code>
+    - <code>rootPluralName</code> was renamed <code>pluralName</code>
+
 <a name="0.2.3"></a>
 # 0.2.3
 ## Bug Fixes
@@ -25,14 +41,14 @@
 - Removed default transformers and interceptors
     - railsFieldRenamingTransformer and railsFieldRenamingInterceptor have been removed completely and replaced by the serializers
     - railsRootWrappingTransformer/Interceptor are no longer configured by the transformers/interceptors configuration option and is instead
-      configured by the <code>enableRootWrapping</code> option.
+      configured by the <code>wrapData</code> option.
 - Interceptors added using <code>beforeRequest</code> are run before any deserialization so the fields names have not been camelized.
 
 ## Bug Fixes
 
 ## Features
 - Added serializers to replace old field renaming logic and to give users a lot more flexibility in customizing the (de)serialization process
-- Added <code>enableRootWrapping</code> configuration option to be able to turn off root wrapping instead
+- Added <code>rootWrapping</code> configuration option to be able to turn off root wrapping instead
 - Added path option to <code>$url</code> methods to make it easier to construct a nested url.
 
 <a name="0.1.7"></a>

data/EXAMPLES.md

@@ -7,74 +7,74 @@ For example, suppose we have an Author that serializes all of the books that aut
 are a nested resource that allows us to more easily perform updates against those books without having to worry about creating
 a resource instance for the book.
 
-	angular.module('book.services', ['rails']);
-
-	angular.module('book.services').factory('Book', ['railsResourceFactory', function (railsResourceFactory) {
-		return railsResourceFactory({url: '/books', name: 'book'});
-	}]);
-
-	angular.module('book.services').factory('Author', ['railsResourceFactory', 'railsSerializer', function (railsResourceFactory, railsSerializer) {
-		return railsResourceFactory({
-			url: '/authors',
-			name: 'author',
-			serializer: railsSerializer(function () {
-				this.resource('books', 'Book');
-			})
-		});
-	}]);
-
-	angular.module('book.controllers').controller('AuthorCtrl', ['$scope', 'Author', function ($scope, Author) {
-		$scope.author = Author.get(123);
-
-		// allow the view to trigger an update to a book from $scope.author.books
-		$scope.updateBook = function (book) {
-			book.update();
-		}
-	}]);
+    angular.module('book.services', ['rails']);
+
+    angular.module('book.services').factory('Book', ['railsResourceFactory', function (railsResourceFactory) {
+        return railsResourceFactory({url: '/books', name: 'book'});
+    }]);
+
+    angular.module('book.services').factory('Author', ['railsResourceFactory', 'railsSerializer', function (railsResourceFactory, railsSerializer) {
+        return railsResourceFactory({
+            url: '/authors',
+            name: 'author',
+            serializer: railsSerializer(function () {
+                this.resource('books', 'Book');
+            });
+         });
+    }]);
+
+    angular.module('book.controllers').controller('AuthorCtrl', ['$scope', 'Author', function ($scope, Author) {
+        $scope.author = Author.get(123);
+
+        // allow the view to trigger an update to a book from $scope.author.books
+        $scope.updateBook = function (book) {
+            book.update();
+        }
+    }]);
 
 # Nested attributes
 While we don't have logic for full nested attributes support, the new serializer does allow you to specify which fields
 should be passed with the <code>_attributes</code> suffix.
 
-	angular.module('book.services').factory('Book', ['railsResourceFactory', 'railsSerializer', function (railsResourceFactory, railsSerializer) {
-		return railsResourceFactory({
-			url: '/books',
-			name: 'book',
-			serializer: railsSerializer(function () {
-				this.nestedAttribute('author');
-			})
-		});
-	}]);
+    angular.module('book.services').factory('Book', ['railsResourceFactory', 'railsSerializer', function (railsResourceFactory, railsSerializer) {
+        return railsResourceFactory({
+            url: '/books',
+            name: 'book',
+            serializer: railsSerializer(function () {
+                this.nestedAttribute('author');
+            });
+         });
+    }]);
 
 # Excluding attributes from serialization
 Sometimes you don't want to serialize certain fields when updating an object.  Take for instance the case of the author on a book.
 We know that we don't accept nested attributes for the author on the server so we want to exclude it from the JSON to reduce
 the amount of data being sent to the server.
 
-	angular.module('book.services').factory('Book', ['railsResourceFactory', 'railsSerializer', function (railsResourceFactory railsSerializer) {
-		return railsResourceFactory({
-			url: '/books',
-			name: 'book',
-			serializer: railsSerializer(function () {
-				this.exclude('author');
-			})
-		});
-	}]);
+    angular.module('book.services').factory('Book', ['railsResourceFactory', 'railsSerializer', function (railsResourceFactory railsSerializer) {
+        return railsResourceFactory({
+            url: '/books',
+            name: 'book',
+            serializer: railsSerializer(function () {
+                this.exclude('author');
+            });
+         });
+    }]);
 
 
 # Only allowing specific attributes for serialization
 You can also be very restrictive and only include specific attributes that you want to send to the server.  All other attribtues
 would be excluded by default.
 
-	angular.module('book.services').factory('Book', ['railsResourceFactory', 'railsSerializer', function (railsResourceFactory. railsSerializer) {
-		return railsResourceFactory({
-			url: '/books',
-			name: 'book',
-			serializer: railsSerializer(function () {
-				this.only('id', 'isbn', 'publicationDate');
-			})
-		});
-	}]);
+    angular.module('book.services').factory('Book', ['railsResourceFactory', 'railsSerializer', function (railsResourceFactory. railsSerializer) {
+        return railsResourceFactory({
+            url: '/books',
+            name: 'book',
+            serializer: railsSerializer(function () {
+                this.only('id', 'isbn', 'publicationDate');
+            });
+         });
+    }]);
 
 
 # Adding custom methods to a resource
@@ -84,61 +84,61 @@ You can add additional "class" or "instance" methods by modifying the resource r
 For instance, if you wanted to add a method that would search for Books by the title without having to construct the query params
 each time you could add a new <code>findByTitle</code> class function.
 
-	angular.module('book.services', ['rails']);
-	angular.module('book.services').factory('Book', ['railsResourceFactory', function (railsResourceFactory) {
-		var resource = railsResourceFactory({url: '/books', name: 'book'});
-		resource.findByTitle = function (title) {
-			return resource.query({title: title});
-		};
-		return resource;
-	}]);
-
-	angular.module('book.controllers').controller('BookShelfCtrl', ['$scope', 'Book', function ($scope, Book) {
-		$scope.searching = true;
-		// Find all books matching the title
-		$scope.books = Book.findByTitle({title: title});
-		$scope.books.then(function(results) {
-			$scope.searching = false;
-		}, function (error) {
-			$scope.searching = false;
-		});
-	}]);
+    angular.module('book.services', ['rails']);
+    angular.module('book.services').factory('Book', ['railsResourceFactory', function (railsResourceFactory) {
+        var resource = railsResourceFactory({url: '/books', name: 'book'});
+        resource.findByTitle = function (title) {
+            return resource.query({title: title});
+        };
+        return resource;
+    }]);
+
+    angular.module('book.controllers').controller('BookShelfCtrl', ['$scope', 'Book', function ($scope, Book) {
+        $scope.searching = true;
+        // Find all books matching the title
+        $scope.books = Book.findByTitle({title: title});
+        $scope.books.then(function(results) {
+            $scope.searching = false;
+        }, function (error) {
+            $scope.searching = false;
+        });
+    }]);
 
 ## Get related object
 You can also add additional methods on the object prototype chain so all instances of the resource have that function available.
 The following example exposes a <code>getAuthor</code> instance method that would be accessible on all Book instances.
 
-	angular.module('book.services', ['rails']);
-	angular.module('book.services').factory('Author', ['railsResourceFactory', function (railsResourceFactory) {
-		return railsResourceFactory({url: '/authors', name: 'author'});
-	}]);
-	angular.module('book.services').factory('Book', ['railsResourceFactory', 'Author', function (railsResourceFactory, Author) {
-		var resource = railsResourceFactory({url: '/books', name: 'book'});
-		resource.prototype.getAuthor = function () {
-			return Author.get(this.authorId);
-		};
-	}]);
-	angular.module('book.controllers').controller('BookShelfCtrl', ['$scope', 'Book', function ($scope, Book) {
-		$scope.getAuthorDetails = function (book) {
-			$scope.author = book.getAuthor();
-		};
-	}]);
+    angular.module('book.services', ['rails']);
+    angular.module('book.services').factory('Author', ['railsResourceFactory', function (railsResourceFactory) {
+        return railsResourceFactory({url: '/authors', name: 'author'});
+    }]);
+    angular.module('book.services').factory('Book', ['railsResourceFactory', 'Author', function (railsResourceFactory, Author) {
+        var resource = railsResourceFactory({url: '/books', name: 'book'});
+        resource.prototype.getAuthor = function () {
+            return Author.get(this.authorId);
+        };
+    }]);
+    angular.module('book.controllers').controller('BookShelfCtrl', ['$scope', 'Book', function ($scope, Book) {
+        $scope.getAuthorDetails = function (book) {
+            $scope.author = book.getAuthor();
+        };
+    }]);
 
 ## Nested URL
 Or say you instead had a nested "references" service call that returned a list of referenced books for a given book instance.  In that case you can add your own addition method that calls $http.get and then
 passes the resulting promise to the processResponse method which will perform the same transformations and handling that the get or query would use.
 
-	angular.module('book.services', ['rails']);
-	angular.module('book.services').factory('Book', ['railsResourceFactory', '$http', function (railsResourceFactory, $http) {
-		var resource = railsResourceFactory({url: '/books', name: 'book'});
-		resource.prototype.getReferences = function () {
-			var self = this;
-			return resource.$get(self.$url('references'))).then(function (references) {
-				self.references = references;
-				return self.references;
-			});
-		};
-	}]);
+    angular.module('book.services', ['rails']);
+    angular.module('book.services').factory('Book', ['railsResourceFactory', '$http', function (railsResourceFactory, $http) {
+        var resource = railsResourceFactory({url: '/books', name: 'book'});
+        resource.prototype.getReferences = function () {
+            var self = this;
+            return resource.$get(self.$url('references'))).then(function (references) {
+                self.references = references;
+                return self.references;
+            });
+        };
+    }]);
 
 # Specifying Transformer
 Transformers can be specified by an array of transformers in the configuration options passed to railsResourceFactory.
@@ -147,25 +147,25 @@ a function returned by a factory if you want to share a transformer across multi
 
 Both of these examples can be accomplished using the serializers now.
 
-	angular.module('test').factory('excludePrivateKeysTransformer', function () {
-		return function (data) {
-			angular.forEach(data, function (value, key) {
-				if (key[0] === '_') {
-					delete data[key];
-				}
-			});
-		});
-	});
-
-	angular.module('test').factory('Book', function (railsResourceFactory, excludePrivateKeysTransformer) {
-		var Book = railsResourceFactory({url: '/books', name: 'book'});
-		Book.beforeRequest(excludePrivateKeysTransformer);
-		Book.beforeRequest(function (data) {
-			data['release_date'] = data['publicationDate'];
-			delete data['publicationDate'];
-		});
-
-		return Book;
-	});
+    angular.module('test').factory('excludePrivateKeysTransformer', function () {
+        return function (data) {
+            angular.forEach(data, function (value, key) {
+                if (key[0] === '_') {
+                    delete data[key];
+                }
+            });
+        });
+    });
+
+    angular.module('test').factory('Book', function (railsResourceFactory, excludePrivateKeysTransformer) {
+        var Book = railsResourceFactory({url: '/books', name: 'book'});
+        Book.beforeRequest(excludePrivateKeysTransformer);
+        Book.beforeRequest(function (data) {
+            data['release_date'] = data['publicationDate'];
+            delete data['publicationDate'];
+        });
+
+        return Book;
+    });
 
 

data/README.md

@@ -3,35 +3,59 @@
 
 A resource factory inspired by $resource from AngularJS and [Misko's recommendation](http://stackoverflow.com/questions/11850025/recommended-way-of-getting-data-from-the-server).
 
-When starting out with AngularJS and Rails we initially were using $resource but there were three things we didn't like that this gem sets out to provide:
+## Differences from $resource
+This library is not a drop in replacement for $resource.  There are significant differences that you should be aware of and
 
- 1.  $resource didn't return promises
- 2.  Rails prefers JSON be root wrapped
- 3.  Our JSON contained snake case (underscored) keys coming from our database but we didn't want to mix snake case and camel case in our UI
+1.  <code>get</code> and <code>query</code> return [$q promises](http://docs.angularjs.org/api/ng.$q), not an instance or array that will be populated.  To gain access to the results you
+should use the promise <code>then</code> function.
+2.  By default we perform root wrapping and unwrapping (if wrapped) when communicating with the server.
+3.  By default we convert attribute names between underscore and camel case.
 
-In case you are unfamiliar, the intent of the resource is to behave a bit like a remote model object.  One of the nice things about AngularJS
- is that it does not require you to create specific models for all of your data which gives you a lot of freedom for treating model data as basic
- javascript objects.  However, on the Rails side when exposing models to a javascript application you are likely going to follow the same pattern for multiple
- models where you will have a controller that has your basic index (query), get, create, update, delete functionality.
+## FAQs
+### How come I can't iterate the array returned from query?
+We don't return an array.  We return promises not arrays or objects that get filled in later.
 
-The resource object created by this factory simplifies access to those models by exposing a mix of "class" methods (query, get) and
- "instance" methods (create, update, delete/remove).
-
-This module is being used for applications we are writing and we expect that over time that we will be adding additional functionality but we welcome contributions and suggestions.
+If you need access to the array in your JS code you can use the promise <code>then</code> function:
+````javascript
+Book.query({title: 'Moby Dick'}).then(function (books) {
+    $scope.books = books;
+});
+````
 
-## Changes
-Make sure to check the [CHANGELOG](CHANGELOG.md) for any breaking changes between releases.
+### I like underscores, how can I turn off the name conversion?
+You can inject the <code>railsSerializerProvider</code> into your application config function and override the <code>underscore</code>
+and <code>camelize</code> functions:
+````javascript
+angular.module('app').config(function (railsSerializerFactory) {
+    railsSerializerProvider.
+        underscore(function (name) {
+            return name;
+        }).
+        camelize(function (name) {
+            return name;
+        });
+});
+````
 
 ## Installation
-
-Add this line to your application's Gemfile:
+Add this line to your application's Gemfile to use the latest stable version:
 ```ruby
-gem 'angularjs-rails-resource', '~> 0.2.0'
+gem 'angularjs-rails-resource', '~> 0.2.3'
 ```
+
 Include the javascript somewhere in your asset pipeline:
 ```javascript
 //= require angularjs/rails/resource
 ```
+## Branching and Versioning
+As much as possible we will try to adhere to the [SemVer](http://semver.org/) guidelines on release numbering.
+
+The master branch may contain work in progress and should not be considered stable.
+
+Release branches should remain stable but it is always best to rely on the ruby gem release versions as the most stable versions.
+
+## Changes
+Make sure to check the [CHANGELOG](CHANGELOG.md) for any breaking changes between releases.
 
 ## Dependencies
 Since this is an [AngularJS](http://angularjs.org) module it of course depends on that but more specifically the it depends on the following AngularJS services:
@@ -44,8 +68,7 @@ Since this is an [AngularJS](http://angularjs.org) module it of course depends o
 ## Usage
 There are a lot of different ways that you can use the resources and we try not to force you into any specific pattern
 
-There are more examples available in [EXAMPLES.md](EXAMPLES.md). We also published a complete working example (including the rails side)
-at [Employee Training Tracker](https://github.com/FineLinePrototyping/employee-training-tracker) application.
+There are more examples available in [EXAMPLES.md](EXAMPLES.md).
 
 
 ### Basic Example
@@ -78,6 +101,7 @@ angular.module('book.controllers').controller('BookShelfCtrl', ['$scope', 'Book'
     new Book({title: 'Gardens of the Moon', author: 'Steven Erikson', isbn: '0-553-81957-7'}).create();
 }]);
 ```
+
 ### Serializer
 When defining a resource, you can pass a custom [serializer](#serializers) using the <code>serializer</code> configuration option.
 ```javascript
@@ -113,17 +137,47 @@ Book = railsResourceFactory({
 
 ```
 ## Resource Creation
-Creating a resource using this factory is similar to using $resource, you just call <code>railsResourceFactory</code> with the config options and it returns a new resource function.
-The resource function serves two purposes.  First is that you can use (or define new) "class" methods directly accessible such as query and get to retrieve
-instances from the backend rails service.  The second is that it allows you to use it as a constructor to create new instances of that resource giving you access
-to create, update, and delete instance methods (or any others you add).
+There are multiple ways that you can set up new resources in your application.
+
+### railsResourceFactory
+Similar to $resource, we provide a <code>railsResourceFactory(config)</code> function that takes a config object with the configuration
+settings for the new resource.  The factory function returns a new class that is extended from RailsResource.
+
+### RailsResource extension
+We also expose the RailsResource as base class that you can extend to create your own resource classes.  Extending the RailsResource class
+directly gives you a bit more flexibility to add custom constructor code.  There are probably ten different ways to extend the class but
+the two that we intend to be used are through CoffeeScript or through the same logic that the factory function uses.
 
+#### CoffeeScript
+````coffeescript
+class Book extends RailsResource
+  @configure url: '/books', name: 'book'
+
+class Encyclopedia extends Book
+  @configure url: '/encyclopedias', name: 'encyclopedia'
+````
+
+#### JavaScript
+Since the purpose of exposing the RailsResource was to allow for CoffeeScript users to create classes from it the JavaScript way
+is basically just the same as the generated CoffeeScript code.  The <code>RailsResource.extend</code> function is a modification
+of the <code>__extends</code> function that CoffeeScript generates.
+
+````javascript
+function Resource() {
+    Resource.__super__.constructor.apply(this, arguments);
+}
+
+RailsResource.extend(Resource);
+Resource.configure(config);
+````
 
 ### Config Options
-The following options are available for the config object passed to the factory function.
+
+The following configuration options are available for customizing resources.  Each of the configuration options can be passed as part of an object
+to the <code>railsResourceFactory</code> function or to the resource's <code>configure</code> function.
 
  * **url** - This is the url of the service.  See [Resource URLs](#resource-urls) below for more information.
- * **enableRootWrapping** - (Default: true) Turns on/off root wrapping on JSON (de)serialization.
+ * **rootWrapping** - (Default: true) Turns on/off root wrapping on JSON (de)serialization.
  * **name** - This is the name used for root wrapping when dealing with singular instances.
  * **pluralName** *(optional)* - If specified this name will be used for unwrapping array results.  If not specified then the serializer's [pluralize](#serializers) method is used to calculate
         the plural name from the singular name.
@@ -133,6 +187,7 @@ The following options are available for the config object passed to the factory
          * **Content-Type** - application/json
  * **defaultParams** *(optional)* - If the resource expects a default set of query params on every call you can specify them here.
  * **updateMethod** *(optional)* - Allows overriding the default HTTP method (PUT) used for update.  Valid values are "post", "put", or "patch".
+ * **serializer** *(optional)* - Allows specifying a custom [serializer](#serializers) allow configuring custom serialization options.
  * **requestTransformers** *(optional) - See [Transformers / Interceptors](#transformers--interceptors)
  * **responseInterceptors** *(optional)* - See [Transformers / Interceptors](#transformers--interceptors)
  * **afterResponseInterceptors** *(optional)* - See [Transformers / Interceptors](#transformers--interceptors)
@@ -141,11 +196,11 @@ The following options are available for the config object passed to the factory
 For example, you should specify "publishingCompany" and "publishingCompanies" instead of "publishing_company" and "publishing_companies".
 
 ### Provider Configuration
-<code>railsResourceFactory</code> can be injected as <code>railsResourceFactoryProvider</code> into your app's config method to configure defaults for all the resources application-wide.
+<code>RailsResource</code> can be injected as <code>RailsResourceProvider</code> into your app's config method to configure defaults for all the resources application-wide.
 The individual resource configuration takes precedence over application-wide default configuration values.
 Each configuration option listed is exposed as a method on the provider that takes the configuration value as the parameter and returns the provider to allow method chaining.
 
-* enableRootWrapping - {function(boolean):railsSerializerProvider}
+* rootWrapping - {function(boolean):railsSerializerProvider}
 * httpConfig - {function(object):railsSerializerProvider}
 * defaultParams - {function(object):railsSerializerProvider}
 * updateMethod - {function(boolean):railsSerializerProvider}
@@ -153,8 +208,8 @@ Each configuration option listed is exposed as a method on the provider that tak
 For example, to turn off the root wrapping application-wide and set the update method to PATCH:
 
 ````javascript
-app.config(function (railsResourceFactoryProvider) {
-    railsResourceFactoryProvider.enableRootWrapping(false).updateMethod('patch');
+app.config(function (RailsResourceProvider) {
+    RailsResourceProvider.rootWrapping(false).updateMethod('patch');
 );
 ````
 
@@ -184,12 +239,16 @@ that if response.data is reassigned that there's still a pointer to the original
 
 
 ## Resource Methods
-Resources created using <code>railsResourceFactory</code> have the following class and instance methods available.
+RailsResources have the following class methods available.
 
 ### Class Methods
 * Constructor(data) - The Resource object can act as a constructor function for use with the JavaScript <code>new</code> keyword.
     * **data** {object} (optional) - Optional data to set on the new instance
 
+* configure(options) - Change one or more configuration option for a resource.
+
+* setUrl(url) - Updates the url for the resource, same as calling <code>configure({url: url})</code>
+
 * $url(context, path) - Returns the resource URL using the given context with the optional path appended if provided.
     * **context** {*} - The context to use when building the url.  See [Resource URLs](#resource-urls) above for more information.
     * **path** {string} (optional) - A path to append to the resource's URL.
@@ -314,14 +373,6 @@ Each configuration option listed is exposed as a method on the provider that tak
 * pluralize - {function(fn):railsSerializerProvider}
 * exclusionMatchers - {function(matchers):railsSerializerProvider}
 
-For example, to turn off the key renaming from underscore to camel case and vice versa you would do:
-
-````javascript
-app.config(function (railsSerializerProvider) {
-    railsSerializerProvider.underscore(function (value) { return value; })
-        .camelize(function (value) { return value; });
-);
-````
 
 #### Customization API
 The customizer function passed to the railsSerializer has available to it the following methods for altering the serialization of an object.  None of these methods support nested attribute names (e.g. <code>'books.publicationDate'</code>), in order to customize the serialization of the <code>books</code> objects you would need to specify a custom serializer for the <code>books</code> attribute.