Merge pull request angular-ui#1 from angular-ui/master

Merge to update with master

3.0_UPGRADE.md

@@ -1,7 +1,10 @@
 Upgrading from ng-grid 2.0.x to ui-grid 3.0
 
-1. Module name has changed from nggrid to ui.grid
-   directive name has changed from ng-grid to ui-grid. Before:
+## Module name has changed from nggrid to ui.grid
+
+Directive name has changed from ng-grid to ui-grid. 
+
+Before:
 ```html
 <div ng-grid="{ data: data }"></div>
 ```
@@ -17,15 +20,90 @@ After:
 angular.module('yourModule', ['ui.grid'];
 ```
 
-2. A string value in options.columnDefs is no longer supported.  ColumnDefs are now always watched via $watchCollection. Before:
+## A string value in options.columnDefs is no longer supported.  
+
+ColumnDefs are now always watched via $watchCollection. 
+
+Before:
 ```javascript
 $scope.myColDefs = {[...]};
 $scope.gridOptions.columnDefs = 'myColDefs'
 ```
 
 After:
 ```javascript
-$scope.gridOptions.columnDefs = $scope.myColDefs = {[...]};
+$scope.gridOptions.columnDefs = $scope.myColDefs = [...];
 or 
-$scope.gridOptions.columnDefs = {[...]};
+$scope.gridOptions.columnDefs = [...];
+```
+
+## All columns within columnDefs must have a name or a field.
+
+Before:
+```javascript
+$scope.gridOptions = {
+  columnDefs: [
+    { displayName: 'Edit' }
+  ],
+  data: myData
+};
+```
+
+After:
+```javascript
+$scope.gridOptions = {
+  columnDefs: [
+    { name: 'edit', displayName: 'Edit' }
+  ],
+  data: myData
+};
+```
+
+## ui-grid uses an isolate scope
+You can no longer access data or functions directly on the parent scope.  You can access a pre-defined scope by using getExternalScopes(), and set this scope using the external-scopes directive.
+
+Before:
+```javascript
+$scope.gridOptions = {
+  columnDefs = [
+    { name: 'edit', displayName: 'Edit', cellTemplate: '<button ng-click="edit(row.entity)" >Edit</button>' }
+  ],
+  data: myData
+};
+
+$scope.edit = function( entity ) {
+  ...some custom function using entity...
+};
+```
+
+```html
+<div ng-grid="gridOptions" ></div>
+```
+
+After:
+```javascript
+$scope.gridScope = $scope;
+$scope.gridOptions = {
+  columnDefs = [
+    { name: 'edit', displayName: 'Edit', cellTemplate: '<button ng-click="getExternalScopes().edit(row.entity)" >Edit</button>' }
+  ],
+  data: myData
+};
+
+$scope.edit = function( entity ) {
+  ...some custom function using entity...
+};
+```
+
+```html
+<div ui-grid="gridOptions" external-scopes="gridScope" ></div>
+```
+
+## Some features previously included in the base are now plugins.
+
+Refer to the tutorials and API documentation at http://ui-grid.info/docs/ for more detail, an example provided below is column resizing.  The plugins are available in the base javascript, using them requires only including the appropriate directive in the grid declaration:
+
+After:
+```html
+<div ui-grid="gridOptions" external-scopes="gridScope" ui-grid-resize-columns ></div>
 ```

misc/tutorial/103_filtering.ngdoc

@@ -6,6 +6,8 @@ UI-Grid allows you to filter rows. Just set the `enableFiltering` flag in your g
 
 Filtering can be disabled at the column level by setting `enableFiltering: false` in the column def. See the last column below for an example.
 
+Default filters can be set programmatically by setting `filter: { term: 'xxx' }` in the column def.  See the second column below.
+
 @example
 <example module="app">
   <file name="app.js">
@@ -16,7 +18,7 @@ Filtering can be disabled at the column level by setting `enableFiltering: false
         enableFiltering: true,
         columnDefs: [
           { field: 'name' },
-          { field: 'gender' },
+          { field: 'gender', filter: { term: 'male' } },
           { field: 'company', enableFiltering: false  }
         ]
       };

src/features/cellnav/js/cellnav.js

@@ -278,7 +278,9 @@
            *  @ngdoc object
            *  @name allowCellFocus
            *  @propertyOf  ui.grid.cellNav.api:ColDef
-           *  @description Enable focus on a cell.<br/>Defaults to true
+           *  @propertyOf  ui.grid.class:GridOptions.columnDef
+           *  @description Enable focus on a cell.  Requires the cell nav feature to be enabled.
+           *  <br/>Defaults to true
            */
           colDef.allowCellFocus = colDef.allowCellFocus === undefined ? true : colDef.allowCellFocus ;
 

src/features/edit/js/gridEdit.js

@@ -102,15 +102,18 @@
            *  @ngdoc object
            *  @name enableCellEdit
            *  @propertyOf  ui.grid.edit.api:GridOptions
+           *  @propertyOf  ui.grid.class:GridOptions
            *  @description If defined, it will be the default value that colDefs will take if their enableCellEdit is
-           *  not defined. Defaults to undefined.
+           *  not defined. Defaults to undefined.  Requires the edit feature to be enabled
            */
 
           /**
            *  @ngdoc object
            *  @name cellEditableCondition
            *  @propertyOf  ui.grid.edit.api:GridOptions
-           *  @description If specified, either a value or function to be used by all columns before editing.  If falsy, then editing of cell is not allowed
+           *  @propertyOf  ui.grid.class:GridOptions
+           *  @description If specified, either a value or function to be used by all columns before editing.  If falsy, then editing of cell is not allowed.
+           *  Requires the edit feature to be enabled
            *  <pre>
            *  function($scope){
            *    //use $scope.row.entity and $scope.col.colDef to determine if editing is allowed
@@ -124,15 +127,17 @@
            *  @ngdoc object
            *  @name editableCellTemplate
            *  @propertyOf  ui.grid.edit.api:GridOptions
-           *  @description If specified, cellTemplate to use as the editor for all columns.
+           *  @propertyOf  ui.grid.class:GridOptions
+           *  @description If specified, cellTemplate to use as the editor for all columns.  Requires the edit feature to be enabled
            *  <br/> default to 'ui-grid/cellTextEditor'
            */
 
           /**
            *  @ngdoc object
            *  @name enableCellEditOnFocus
            *  @propertyOf  ui.grid.edit.api:GridOptions
-           *  @description If true, then editor is invoked as soon as cell receives focus. Default false
+           *  @propertyOf  ui.grid.class:GridOptions
+           *  @description If true, then editor is invoked as soon as cell receives focus. Default false.  Requires the edit feature to be enabled
            *  <br>!! requires cellNav feature !!
            */
             //enableCellEditOnFocus can only be used if cellnav module is used
@@ -162,7 +167,8 @@
            *  @ngdoc object
            *  @name enableCellEdit
            *  @propertyOf  ui.grid.edit.api:ColDef
-           *  @description enable editing on column
+           *  @propertyOf  ui.grid.class:GridOptions.columnDef
+           *  @description enable editing on column, requires the edit feature to be enabled.
            */
           colDef.enableCellEdit = colDef.enableCellEdit === undefined ? (gridOptions.enableCellEdit === undefined ?
             (colDef.type !== 'object'):gridOptions.enableCellEdit) : colDef.enableCellEdit;
@@ -171,7 +177,9 @@
            *  @ngdoc object
            *  @name cellEditableCondition
            *  @propertyOf  ui.grid.edit.api:ColDef
-           *  @description If specified, either a value or function evaluated before editing cell.  If falsy, then editing of cell is not allowed
+           *  @propertyOf  ui.grid.class:GridOptions.columnDef
+           *  @description If specified, either a value or function evaluated before editing cell.  If falsy, then editing of cell is not allowed.
+           *  Requires the edit feature to be enabled. 
            *  <pre>
            *  function($scope){
            *    //use $scope.row.entity and $scope.col.colDef to determine if editing is allowed
@@ -185,8 +193,10 @@
            *  @ngdoc object
            *  @name editableCellTemplate
            *  @propertyOf  ui.grid.edit.api:ColDef
+           *  @propertyOf  ui.grid.class:GridOptions.columnDef
            *  @description cell template to used when editing this column. can be Url or text template
            *  <br/>Defaults to gridOptions.editableCellTemplate
+           *  Requires the edit feature to be enabled
            */
           if (colDef.enableCellEdit) {
             colDef.editableCellTemplate = colDef.editableCellTemplate || gridOptions.editableCellTemplate ||
@@ -217,8 +227,9 @@
            *  @ngdoc object
            *  @name enableCellEditOnFocus
            *  @propertyOf  ui.grid.edit.api:ColDef
+           *  @propertyOf  ui.grid.class:GridOptions.columnDef
            *  @requires ui.grid.cellNav
-           *  @description If true, then editor is invoked as soon as cell receives focus. Default false
+           *  @description If true, then editor is invoked as soon as cell receives focus. Default false.  Requires the edit feature to be enabled.
            *  <br>!! requires cellNav feature !!
            */
             //enableCellEditOnFocus can only be used if cellnav module is used

src/features/pinning/js/pinning.js

@@ -58,7 +58,9 @@
          *  @ngdoc object
          *  @name enableRowSelection
          *  @propertyOf  ui.grid.pinning.api:GridOptions
-         *  @description Enable pinning. <br/>Defaults to true
+         *  @propertyOf  ui.grid.class:GridOptions
+         *  @description Enable pinning for the entire grid. Requires the pinning feature to be enabled. 
+         *  <br/>Defaults to true
          */
         gridOptions.enablePinning = gridOptions.enablePinning !== false;
 
@@ -78,7 +80,9 @@
          *  @ngdoc object
          *  @name enablePinning
          *  @propertyOf  ui.grid.pinning.api:ColDef
-         *  @description Enable pinning. <br/>Defaults to true
+         *  @propertyOf  ui.grid.class:GridOptions.columnDef
+         *  @description Enable pinning for the individual column. Requires the pinning feature to be enabled. 
+         *  <br/>Defaults to true
          */
         colDef.enablePinning = colDef.enablePinning === undefined ? gridOptions.enablePinning : colDef.enablePinning;
 

src/features/resize-columns/js/ui-grid-column-resizer.js

@@ -25,7 +25,9 @@
            *  @ngdoc object
            *  @name enableColumnResizing
            *  @propertyOf  ui.grid.resizeColumns.api:GridOptions
-           *  @description Enable column resizing <br/>Defaults to true
+           *  @propertyOf  ui.grid.class:GridOptions
+           *  @description Enable column resizing on the entire grid.  Requires the column resizing feature to be enabled. 
+           *  <br/>Defaults to true
            */
           gridOptions.enableColumnResizing = gridOptions.enableColumnResizing !== false;
 
@@ -50,7 +52,9 @@
            *  @ngdoc object
            *  @name enableColumnResizing
            *  @propertyOf  ui.grid.resizeColumns.api:ColDef
-           *  @description Enable column resizing <br/>Defaults to GridOptions.enableColumnResizing
+           *  @propertyOf  ui.grid.class:GridOptions.columnDef
+           *  @description Enable column resizing on an individual column.  Requires column resizing feature to be enabled.
+           *  <br/>Defaults to GridOptions.enableColumnResizing
            */
           //default to true unless gridOptions or colDef is explicitly false
           colDef.enableColumnResizing = colDef.enableColumnResizing === undefined ? gridOptions.enableColumnResizing : colDef.enableColumnResizing;

src/features/selection/js/selection.js

@@ -174,14 +174,18 @@
            *  @ngdoc object
            *  @name enableRowSelection
            *  @propertyOf  ui.grid.selection.api:GridOptions
-           *  @description Enable row selection. <br/>Defaults to true
+           *  @propertyOf  ui.grid.class:GridOptions
+           *  @description Enable row selection for entire grid.  Requires row selection feature to be enabled.
+           *  <br/>Defaults to true
            */
           gridOptions.enableRowSelection = gridOptions.enableRowSelection !== false;
           /**
            *  @ngdoc object
            *  @name multiSelect
            *  @propertyOf  ui.grid.selection.api:GridOptions
-           *  @description Enable multiple row selection. <br/>Defaults to true
+           *  @propertyOf  ui.grid.class:GridOptions
+           *  @description Enable multiple row selection for entire grid.  Requires row selection feature to be enabled.
+           *  <br/>Defaults to true
            */
           gridOptions.multiSelect = gridOptions.multiSelect !== false;
         },

src/js/core/directives/ui-grid-column-menu.js

@@ -33,6 +33,13 @@ angular.module('ui.grid').directive('uiGridColumnMenu', ['$log', '$timeout', '$w
       // Get the inner menu part. It's what slides up/down
       var inner = $elm[0].querySelectorAll('.ui-grid-menu-inner');
 
+      /**
+       * @ngdoc boolean
+       * @name ui.grid.class:GridOptions.columnDef.enableSorting
+       * @propertyOf ui.grid.class:GridOptions.columnDef
+       * @description (optional) True by default. When enabled, this setting adds sort
+       * widgets to the column header, allowing sorting of the data in the individual column.
+       */
       function sortable() {
         if (uiGridCtrl.grid.options.enableSorting && typeof($scope.col) !== 'undefined' && $scope.col && $scope.col.enableSorting) {
           return true;
@@ -42,6 +49,13 @@ angular.module('ui.grid').directive('uiGridColumnMenu', ['$log', '$timeout', '$w
         }
       }
 
+      /**
+       * @ngdoc boolean
+       * @name ui.grid.class:GridOptions.columnDef.enableFiltering
+       * @propertyOf ui.grid.class:GridOptions.columnDef
+       * @description (optional) True by default. When enabled, this setting adds filter
+       * widgets to the column header, allowing filtering of the data in the individual column.
+       */
       function filterable() {
         if (uiGridCtrl.grid.options.enableFiltering && typeof($scope.col) !== 'undefined' && $scope.col && $scope.col.enableFiltering) {
           return true;

src/js/core/factories/Grid.js

@@ -1089,6 +1089,17 @@ angular.module('ui.grid')
    *   by this column only
    * @returns {Promise} A resolved promise that supplies the column.
    */
+
+  /**
+   * @ngdoc constant
+   * @name ui.grid.class:GridOptions.columnDef.sort
+   * @propertyOf ui.grid.class:GridOptions.columnDef
+   * @description (optional) Can be used to set the sort direction for the column, values are
+   * uiGridConstants.ASC or uiGridConstants.DESC
+   * @example
+   * <pre>  $scope.gridOptions.columnDefs = [ { field: 'field1', sort: { direction: uiGridConstants.ASC }}]
+   */
+
   Grid.prototype.sortColumn = function sortColumn(column, directionOrAdd, add) {
     var self = this,
         direction = null;