Merge pull request #11517 from jayphelps/deprecate-router-map-resource

[BUGFIX beta] deprecate this.resource() in Router.map()

packages/ember-application/lib/ext/controller.js

@@ -97,7 +97,7 @@ ControllerMixin.reopen({
     this.get('controllers.post'); // instance of App.PostController
     ```
 
-    Given that you have a nested controller (nested resource):
+    Given that you have a nested controller (nested routes):
 
     ```javascript
     App.CommentsNewController = Ember.ObjectController.extend({

packages/ember-application/tests/system/logging_test.js

@@ -36,7 +36,7 @@ QUnit.module('Ember.Application – logging of generated classes', {
       });
 
       App.Router.map(function() {
-        this.resource('posts');
+        this.route('posts', { resetNamespace: true });
       });
 
       App.deferReadiness();
@@ -161,7 +161,7 @@ QUnit.module('Ember.Application – logging of view lookups', {
       });
 
       App.Router.map(function() {
-        this.resource('posts');
+        this.route('posts', { resetNamespace: true });
       });
 
       App.deferReadiness();

packages/ember-routing-htmlbars/lib/keywords/link-to.js

@@ -147,7 +147,7 @@ import merge from 'ember-metal/merge';
 
   ```javascript
   App.Router.map(function() {
-    this.resource("photoGallery", {path: "hamster-photos/:photo_id"});
+    this.route("photoGallery", {path: "hamster-photos/:photo_id"});
   });
   ```
 
@@ -172,7 +172,7 @@ import merge from 'ember-metal/merge';
 
   ```javascript
   App.Router.map(function() {
-    this.resource("photoGallery", {path: "hamster-photos/:photo_id"}, function() {
+    this.route("photoGallery", { path: "hamster-photos/:photo_id" }, function() {
       this.route("comment", {path: "comments/:comment_id"});
     });
   });
@@ -199,7 +199,7 @@ import merge from 'ember-metal/merge';
 
   ```javascript
   App.Router.map(function() {
-    this.resource("photoGallery", {path: "hamster-photos/:photo_id"});
+    this.route("photoGallery", { path: "hamster-photos/:photo_id" });
   });
   ```
 

packages/ember-routing/lib/ext/controller.js

@@ -65,12 +65,12 @@ ControllerMixin.reopen({
     ```
 
     Multiple models will be applied last to first recursively up the
-    resource tree.
+    route tree.
 
     ```javascript
     App.Router.map(function() {
-      this.resource('blogPost', {path:':blogPostId'}, function() {
-        this.resource('blogComment', {path: ':blogCommentId'});
+      this.route('blogPost', { path: ':blogPostId' }, function() {
+        this.route('blogComment', { path: ':blogCommentId', resetNamespace: true });
       });
     });
 
@@ -156,12 +156,12 @@ ControllerMixin.reopen({
     ```
 
     Multiple models will be applied last to first recursively up the
-    resource tree.
+    route tree.
 
     ```javascript
     App.Router.map(function() {
-      this.resource('blogPost', {path:':blogPostId'}, function() {
-        this.resource('blogComment', {path: ':blogCommentId'});
+      this.route('blogPost', { path: ':blogPostId' }, function() {
+        this.route('blogComment', { path: ':blogCommentId', resetNamespace: true });
       });
     });
 

packages/ember-routing/lib/location/api.js

@@ -26,7 +26,7 @@ import { getHash } from 'ember-routing/location/util';
 
   ```javascript
   App.Router.map(function() {
-    this.resource('posts', function() {
+    this.route('posts', function() {
       this.route('new');
     });
   });
@@ -47,7 +47,7 @@ import { getHash } from 'ember-routing/location/util';
 
   ```javascript
   App.Router.map(function() {
-    this.resource('posts', function() {
+    this.route('posts', function() {
       this.route('new');
     });
   });
@@ -75,7 +75,7 @@ import { getHash } from 'ember-routing/location/util';
 
   ```javascript
   App.Router.map(function() {
-    this.resource('posts', function() {
+    this.route('posts', function() {
       this.route('new');
     });
   });

packages/ember-routing/lib/system/dsl.js

@@ -25,9 +25,8 @@ DSL.prototype = {
       options = {};
     }
 
-    var type = options.resetNamespace === true ? 'resource' : 'route';
     Ember.assert(
-      `'${name}' cannot be used as a ${type} name.`,
+      `'${name}' cannot be used as a route name.`,
       (function() {
         if (options.overrideNameAssertion === true) { return true; }
 
@@ -77,6 +76,7 @@ DSL.prototype = {
     }
 
     options.resetNamespace = true;
+    Ember.deprecate('this.resource() is deprecated. Use this.route(\'name\', { resetNamespace: true }, function () {}) instead.');
     this.route(name, options, callback);
   },
 

packages/ember-routing/lib/system/route.js

@@ -886,12 +886,12 @@ var Route = EmberObject.extend(ActionHandler, Evented, {
     ```
 
     Multiple models will be applied last to first recursively up the
-    resource tree.
+    route tree.
 
     ```javascript
     App.Router.map(function() {
-      this.resource('blogPost', { path:':blogPostId' }, function() {
-        this.resource('blogComment', { path: ':blogCommentId' });
+      this.route('blogPost', { path:':blogPostId' }, function() {
+        this.route('blogComment', { path: ':blogCommentId', resetNamespace: true });
       });
     });
 
@@ -949,7 +949,7 @@ var Route = EmberObject.extend(ActionHandler, Evented, {
 
     ```javascript
     App.Router.map(function() {
-      this.resource('articles', { path: '/articles' }, function() {
+      this.route('articles', { path: '/articles' }, function() {
         this.route('new');
       });
     });
@@ -969,8 +969,8 @@ var Route = EmberObject.extend(ActionHandler, Evented, {
     App.Router.map(function() {
       this.route('index');
 
-      this.resource('breakfast', { path: ':breakfastId' }, function() {
-        this.resource('cereal', { path: ':cerealId' });
+      this.route('breakfast', { path: ':breakfastId' }, function() {
+        this.route('cereal', { path: ':cerealId', resetNamespace: true });
       });
     });
 
@@ -990,7 +990,7 @@ var Route = EmberObject.extend(ActionHandler, Evented, {
 
     ```javascript
     App.Router.map(function() {
-      this.resource('fruits', function() {
+      this.route('fruits', function() {
         this.route('apples');
       });
     });
@@ -1395,7 +1395,7 @@ var Route = EmberObject.extend(ActionHandler, Evented, {
 
     ```javascript
     App.Router.map(function() {
-      this.resource('post', { path: '/posts/:post_id' });
+      this.route('post', { path: '/posts/:post_id' });
     });
     ```
 
@@ -1551,7 +1551,7 @@ var Route = EmberObject.extend(ActionHandler, Evented, {
 
     ```javascript
     App.Router.map(function() {
-      this.resource('post', { path: '/posts/:post_id' });
+      this.route('post', { path: '/posts/:post_id' });
     });
 
     App.PostRoute = Ember.Route.extend({
@@ -1648,7 +1648,7 @@ var Route = EmberObject.extend(ActionHandler, Evented, {
 
     ```javascript
     App.Router.map(function() {
-      this.resource('post', { path: '/posts/:post_id' });
+      this.route('post', { path: '/posts/:post_id' });
     });
     ```
 
@@ -1759,14 +1759,14 @@ var Route = EmberObject.extend(ActionHandler, Evented, {
 
     ```javascript
     App.Router.map(function() {
-        this.resource('post', { path: '/post/:post_id' }, function() {
-            this.resource('comments');
+        this.route('post', { path: '/post/:post_id' }, function() {
+          this.route('comments', { resetNamespace: true });
         });
     });
 
     App.CommentsRoute = Ember.Route.extend({
         afterModel: function() {
-            this.set('post', this.modelFor('post'));
+          this.set('post', this.modelFor('post'));
         }
     });
     ```
@@ -1837,7 +1837,7 @@ var Route = EmberObject.extend(ActionHandler, Evented, {
 
     ```javascript
     Router.map(function() {
-      this.resource('photos');
+      this.route('photos');
     });
     ```
 
@@ -1902,7 +1902,7 @@ var Route = EmberObject.extend(ActionHandler, Evented, {
     // router
     Router.map(function() {
       this.route('index');
-      this.resource('post', { path: '/posts/:post_id' });
+      this.route('post', { path: '/posts/:post_id' });
     });
     ```
 

packages/ember-routing/lib/system/router.js

@@ -84,7 +84,7 @@ var EmberRouter = EmberObject.extend(Evented, {
     });
 
     function generateDSL() {
-      this.resource('application', { path: '/', overrideNameAssertion: true }, function() {
+      this.route('application', { path: '/', resetNamespace: true, overrideNameAssertion: true }, function() {
         for (var i=0; i < dslCallbacks.length; i++) {
           dslCallbacks[i].call(this);
         }
@@ -918,17 +918,39 @@ EmberRouter.reopenClass({
 
   /**
     The `Router.map` function allows you to define mappings from URLs to routes
-    and resources in your application. These mappings are defined within the
-    supplied callback function using `this.resource` and `this.route`.
+    in your application. These mappings are defined within the
+    supplied callback function using `this.route`.
+
+    The first parameter is the name of the route which is used by default as the
+    path name as well.
+
+    The second parameter is the optional options hash. Available options are:
+      * `path`: allows you to provide your own path as well as mark dynamic
+        segments.
+      * `resetNamespace`: false by default; when nesting routes, ember will
+        combine the route names to form the fully-qualified route name, which is
+        used with `{{link-to}}` or manually transitioning to routes. Setting
+        `resetNamespace: true` will cause the route not to inherit from its
+        parent route's names. This is handy for resources which can be accessed
+        in multiple places as well as preventing extremely long route names.
+        Keep in mind that the actual URL path behavior is still retained.
+
+    The third parameter is a function, which can be used to nest routes.
+    Nested routes, by default, will have the parent route tree's route name and
+    path prepended to it's own.
 
     ```javascript
     App.Router.map(function(){
-      this.route('about');
-      this.resource('article');
+      this.route('post', { path: '/post/:post_id' }, function() {
+        this.route('edit');
+        this.route('comments', { resetNamespace: true }, function() {
+          this.route('new');
+        });
+      });
     });
     ```
 
-    For more detailed examples please see
+    For more detailed documentation and examples please see
     [the guides](http://emberjs.com/guides/routing/defining-your-routes/).
 
     @method map

packages/ember-routing/tests/system/dsl_test.js

@@ -13,9 +13,10 @@ QUnit.module('Ember Router DSL', {
 });
 
 QUnit.test('should fail when using a reserved route name', function() {
+  expectDeprecation('this.resource() is deprecated. Use this.route(\'name\', { resetNamespace: true }, function () {}) instead.');
   var reservedNames = ['array', 'basic', 'object', 'application'];
 
-  expect(reservedNames.length * 2);
+  expect((reservedNames.length * 2) + 1);
 
   reservedNames.forEach(function(reservedName) {
     expectAssertion(function() {
@@ -38,12 +39,14 @@ QUnit.test('should fail when using a reserved route name', function() {
 
       var router = Router.create();
       router._initRouterJs();
-    }, '\'' + reservedName + '\' cannot be used as a resource name.');
+    }, `'${reservedName}' cannot be used as a route name.`);
 
   });
 });
 
 QUnit.test('should reset namespace if nested with resource', function() {
+  expectDeprecation('this.resource() is deprecated. Use this.route(\'name\', { resetNamespace: true }, function () {}) instead.');
+
   Router = Router.map(function() {
     this.resource('bleep', function() {
       this.resource('bloop', function() {

packages/ember-runtime/lib/mixins/action_handler.js

@@ -116,7 +116,7 @@ var ActionHandler = Mixin.create({
 
     ```js
     App.Router.map(function() {
-      this.resource("album", function() {
+      this.route("album", function() {
         this.route("song");
       });
     });

packages/ember-testing/tests/helpers_test.js

@@ -741,7 +741,7 @@ QUnit.module('ember-testing routing helpers', {
       });
 
       App.Router.map(function() {
-        this.resource('posts', function() {
+        this.route('posts', { resetNamespace: true }, function() {
           this.route('new');
         });
       });
@@ -842,7 +842,7 @@ QUnit.module('ember-testing async router', {
       });
 
       App.Router.map(function() {
-        this.resource('user', function() {
+        this.route('user', { resetNamespace: true }, function() {
           this.route('profile');
           this.route('edit');
         });

packages/ember-testing/tests/integration_test.js

@@ -23,7 +23,7 @@ QUnit.module('ember-testing Integration', {
       });
 
       App.Router.map(function() {
-        this.resource('people', { path: '/' });
+        this.route('people', { path: '/' });
       });
 
       App.PeopleRoute = EmberRoute.extend({

packages/ember-views/lib/views/view.js

@@ -371,7 +371,7 @@ Ember.TEMPLATES = {};
   });
   ```
 
-  If you have nested resources, your Handlebars template will look like this:
+  If you have nested routes, your Handlebars template will look like this:
 
   ```html
   <script type='text/x-handlebars' data-template-name='posts/new'>