Thanks for considering contributions to the ui-grid project. This doc will give you a jump start on the development standards we use.
Grunt task dev will run jshint, compile less, run fontella, run unit tests, run protractor tests, and start a local webserver on port 9003. A watch is started to rerun all the tasks if any source file changes.
``` grunt dev ```
http://localhost:9003/docs/#/tutorial to browse each tutorial.
options
no-e2e - eliminate protractor tests
angular=n.n.n - specify a specify angular version to run unit tests against
grunt dev --no-e2e --angular=1.2.16
The development goal of ui-grid (ng-grid 3.0) is a fast, testable, and extensible grid component.
The core angular module (ui.grid) provides the basics
- Virtualization
- Row Selection
Everything else should be added as new angular modules unless the grid team agrees that it's a core feature.
- We prefer no 3rd party dependencies other than angular. Contact grid team if you have a 3rd party need that can't be avoided.
- jQuery is only used in Unit Tests
- unit test your code! not that hard. see test/unit for examples. Features will be rejected if the test coverage isn't adequate.
- use ngDoc to document how to use your feature. see examples in existing code.
- New module should be named ui.grid.feature
- feature folder is added below src
- One js file per feature
- no global variables
- public methods and events are registered in grid.api (more on that later)
- design and code the angular way. What do we main by that? Dependency injection, small directives, emphasis the model, not the DOM, tests!
- feature.js contains an enclosure:
(function () {
'use strict';
var module = angular.module('ui.grid.feature', ['ui.grid']);
})();- Constants should be added to module.constants. Anytime a value is used in more than one place, consider a constant.
This folder layout is required to work with build tools
src/featureName
/js
/less
/test
All test files must be name.spec.js to get picked up by our grunt tasks
This pattern has been used in several features and seems to work well.
Any magic strings, etc.
module.constant('uiGridFeatureConstants', {
FEATURE_CONSTANT1: 'abc',
featureGroupConstant: {
GROUP_ONE: 'somevalue',
GROUP_TWO: 'a'
},
//available public events; listed here for convenience and IDE's use it for smart completion
publicEvents: {
featureName : {
event1 : function(scope, newRowCol, oldRowCol){},
event2 : function(scope){}
}
}
});Anything suited to an angular service. So much easier to unit test logic here than logic in a directive or controller.
module.service('uiGridFeatureService', ['uiGridFeatureConstants'
function (uiGridFeatureConstants) {
var service = {
somethingUseful: function () {}
}
return service;
}]);The main entry point for your feature.
module.directive('uiGridFeature', ['uiGridFeatureService', 'uiGridFeatureConstants',
function (uiGridEditService, uiGridFeatureConstants) {
return {
restrict: 'A',
replace: true,
priority: 0, // this could be tweaked to fire your directive before/after other features
require: 'uiGrid',
scope: false,
compile: function () {
return {
pre: function ($scope, $elm, $attrs, uiGridCtrl) {
//register your feature cols and row processors with uiGridCtrl.gri
//do anything else you can safely do here
//!! of course, don't stomp on core grid logic or data
}
};
}
};
}]);Extend a core directive
module.directive('uiGridCell', ['uiGridFeatureService',
function (uiGridCellNavService) {
return {
priority: -500, // run after default uiGridCell directive
restrict: 'A',
require: '^uiGrid',
scope: false,
link: function ($scope, $elm, $attrs, uiGridCtrl) {
//add whatever dom binding, manipulation,etc that is safe to do and performs well
}
};
}]);If necessary...
module.directive('uiGridFeatureDirective', ['uiGridFeatureService',
function (uiGridFeatureService) {
return {
link: function ($scope, $elm, $attrs) {
}
};
}]);Each feature should implement a directive that enables the feature for the ui-grid element. This is the main entry point
of your feature and allows a developer to use multiple grids on a page and include your feature on some grids and not on
others.
<div ui-grid='options' ui-grid-your-feature></div>
Require the uiGrid controller. In the preLink function, register your column and row builders (see below). See ui.grid.edit unit tests on how to easily test your directive
module.directive('uiGridFeature', ['uiGridFeatureService', 'uiGridFeatureConstants',
function (uiGridEditService, uiGridFeatureConstants) {
return {
replace: true,
priority: 0, // this could be tweaked to fire your directive before/after other features
require: 'uiGrid',
scope: false,
compile: function () {
return {
pre: function ($scope, $elm, $attrs, uiGridCtrl) {
uiGridCtrl.grid.api.registerEventsFromObject(uiGridFeatureConstants.publicEvents);
uiGridCtrl.grid.registerColumnBuilder(uiGridFeatureService.featureColumnBuilder);
uiGridCtrl.grid.registerRowBuilder(uiGridFeatureService.featureRowBuilder);
uiGridCtrl.grid.RowsProcessor(uiGridFeatureService.featureRowsProcessor);
//do anything else you can safely do here
//!! of course, don't stomp on core grid logic or data
}
};
}
};
}]);The grid provides calls different processors for rows and cols that you can implement for your feature.
ColumnBuilder functions allow you to add your own properties / functions to each GridCol object. for testing ease, it's best to create a service that returns the function. See ui.grid.edit unit tests on how to easily test your function
module.service('uiGridFeatureService', ['$log', '$q', '$templateCache',
function ($log, $q, $templateCache) {
var service = {
featureColumnBuilder: function (colDef, col, gridOptions) {
//add any promises to an array
var promises = [];
//do something with col
col.featureProp = colDef.featureProp || 'default';
//return all promises (works even if the array is empty)
return $q.all(promises);
}
}
return service;
}]);
//from feature directive pre-link
uiGridCtrl.grid.registerColumnBuilder(uiGridFeatureService.featureColumnBuilder);RowBuilder functions allow you to add your own properties / functions to each GridRow object. Again, it's best to implement function in a service. See ui.grid.edit unit tests on how to easily test your function
....
featureRowBuilder: function (row, gridOptions) {
//add any promises to an array
var promises = [];
//do something with col
row.featureProp = gridOptions.featureProp || 'default';
//return all promises (works even if the array is empty)
return $q.all(promises);
}
....
//from feature directive pre-link
uiGridCtrl.grid.registerRowBuilder(uiGridFeatureService.featureRowBuilder);RowsProcessor allows your feature to affect the entire rows collections. Gives you the ability to sort, group, etc. the row.
....
function featureRowsProcessor(renderableRows) {
return rowSorter.sort(this, renderableRows, this.columns);
....
//from feature directive pre-link
uiGridCtrl.grid.RowsProcessor(uiGridFeatureService.featureRowsProcessor);The grid provides public api via the GridApi object. This object allows you to register your feature's public api methods and events. It guarantees that your events are specific to a grid instance. Internally, angular scope $broadcast and $on are used.
//preferred method is to use a map so ide's can pick up on the signatures
var publicEvents = {
featureName : {
event1 : function(scope, function(newRowCol, oldRowCol)){},
event2 : function(scope, function(){}){}
}
}
});
//from feature directive pre-link
uiGridCtrl.grid.api.registerEventsFromObject(publicEvents);
//more stringy registration
uiGridCtrl.grid.api.registerEvents('featureName', 'eventName');
//raise event
uiGridCtrl.grid.api.featureName.raise.event1(newRowCol, oldRowCol);
//subscribe to event. You must provide a scope object so the listener will be destroyed when scope is destroyed
//function's this variable will be grid.api
uiGridCtrl.grid.api.featureName.on.event1($scope, function(newRowCol, oldRowCol){});
//register methods
var methods = {
featureName : {
methodName1 : function(yourVar1, yourVar2){
//whatever you method needs to do
},
methodName2 : function(var2){
//do something else
}
}
}
uiGridCtrl.grid.api.registerMethodsFromObject(uiGridFeatureConstants.publicEvents);
//way of the string
uiGridCtrl.grid.api.registerMethod('featureName', 'methodName', function(yourVar){//do something});
//external use
$scope.gridOptions.onRegisterApi = function(gridApi){
//subscribe to event
gridApi.feature.on.event1($scope,function(scope, function(newRowCol, oldRowCol)){
var self = this; //grid.api
var msg = 'row selected ' + row.isSelected;
$log.log(msg);
});
//call method
gridApi.featureName.methodName1('abc','123');
};The next extension point requires some knowledge of the core grid directives. Thanks to a little known feature in angular, you can stack your feature directives before or after one of the core grid directives. Simply use the same directive name and change the priority to a negative number (to execute after) or a positive number (to execute before)
Here's an example of augmenting the uiGridCell directive to add some element to a grid cell
module.directive('uiGridCell', ['uiGridFeatureService',
function (uiGridCellNavService) {
return {
priority: -500, // run after default uiGridCell directive
restrict: 'A',
require: '^uiGrid',
scope: false,
link: function ($scope, $elm, $attrs, uiGridCtrl) {
if ($scope.col.featureProp === 'somevalue' && $scope.row.featureProp === 'somevalue') {
$elm.find('div').attr("someattrib", 0);
}
//add whatever dom binding, manipulation,etc that is safe to do and performs well
}
};
}]);At the very least, document your main feature directive using jsDoc comment so it's visible in the api docs. Specify all options available to the feature. See other features for jsdocs examples.
Add a tutorial showing how to use your feature. Copy one of the existing misc/tutorial files, change the name at the top and configure it for your feature. 'grunt dev' and your tutorial is available on http://localhost:9003/docs/#/tutorial. Deployment to http://ui-grid.info/ is done automatically when pushed to ui-grid github.
- No tabs
- Indentions are 2 spaces
- Spaces are preferred between args, keywords, blocks function (uiGridCellNavService, $log){ instead of function(uiGridCellNavService,$log){
- jshint rules are enforced. run 'grunt dev --no-e2e' to see if your code passes (the --no-e2e switch turns off end-to-end testing, which can making development slow. You should still run e2e tests before you push commits!)
- Module names should follow Angular's camelcase format, e.g. "resizeColumns", not "resize-columns".