README
AngularJS (1) UI Toolkit
This project aims to provide a set of tools for AngularJS (1) projects. Originally did to satisfy my oen needs but of course if anybody else can benefit from it as well, all the better.
The following items are currently in (new ones may come later as needed):
- heartbeat to keep and check connection to the server
How to use
npm or bower:
Install the package either withnpm install vbm-angular-toolkit
or
bower install vbm-angular-toolkit
Add the script or scripts to your HTML file
In case you are you use the entire bundle, add
<script src="npm_modules/vbm-angular-toolkit/dist/vbmAngularToolkit.min.js"></script>
but in case you need only parts of it you can minimize your load by adding any of the followings separately
<script src="npm_modules/vbm-angular-toolkit/dist/heartbeat.min.js"></script>
<script src="npm_modules/vbm-angular-toolkit/dist/logger.min.js"></script>
<script src="npm_modules/vbm-angular-toolkit/dist/login.min.js"></script>
only.
Use the service you need
heartbeat service
angular.module('myApp', ['vbm.heartbeat']);
angular
.module('myApp')
.run(init);
init.$inject = ['heartbeat'];
function init(heartbeat) {
heartbeat.init({
url: 'heartbeatUrl', // default is favicon.ico
interval: 60000, // default is 30 000ms = 30s
responseValidator: // default lets all pass
function (response) {
return response == 'OK';
}
});
// or
heartbeat.init();
// and anytime later anywhere
heartbeat.setUrl('heartbeatUrl');
heartbeat.setInterval(10000);
heartbeat.setResponseValidator(function (response) {
return response == 'OK';
});
// or any combination of the two above
}
For stopping or starting the service at any time only use:
heartbeat.stop();
and
heartbeat.start();
Be default, after initialization the service is on!
logger service
angular.module('myApp', ['vbm.logger']);
angular
.module('myApp')
.run(init);
init.$inject = ['logger'];
function init(logger) {
var extensions = new Object({});
extensions[instance.INFO] = function (message, data, title) {
// wreak all kind of havoc here
};
extensions[instance.FATAL] = [
function (message, data, title) {
// wreak all kind of havoc here
},
function (message, data, title) {
// wreak some other kind of havoc here
}
];
logger.init({
extensions: extensions
};
// OR you can use the values of the log level constants directly
// 0 - DEBUG
// 1 - INFO
// 2 - SUCCESS
// 3 - WARNING
// 4 - ERROR
// 5 - FATAL
logger.init({
extensions: {
1: function (message, data, title) {
// wreak all kind of havoc here
},
5: [
function (message, data, title) {
// wreak all kind of havoc here
},
function (message, data, title) {
// wreak some other kind of havoc here
}
]
}
};
}
//////////////////////////////////////////////////
angular
.module('myApp')
.controller('myController', myController);
myController.$inject = ['logger'];
function myController(logger) {
// ...
logger.setLogLevel(logger.ERROR);
// ...
logger.debug('message', problematicObject, 'title'); // by default this log message will not get through
logger.info('message', problematicObject, 'title');
logger.success('message', problematicObject, 'title');
logger.warning('message', problematicObject, 'title');
logger.error('message', problematicObject, 'title');
logger.fatal('message', problematicObject, 'title');
// ...
}
Logger extension demo - angular-toastr
The project contains a demonstration for 'logger extension'. One based on [angular-toastr][toastr]. This is located in folder
demo/logger
login service
Login service offers as of now 2 authentication methods (BASIC and FORM). Authentication also involves a user information gathering step where the success is measured of the existence of a special attribute.
angular.module('myApp', ['vbm.login']);
angular
.module('myApp')
.run(init);
init.$inject = ['login'];
function init(login) {
login.init({
interval: 60000, // default is -1ms (no iteration)
loginUrl: 'login-url', // default is 'login'
logoutUrl: 'logout-url', // default is 'logout'
userInfoUrl: 'user-info-url', // default is 'user'
authenticationMethod: login.authenticationMethods.FORM_BASED_AUTHENTICATION // default is 'login.authenticationMethods.BASIC_AUTHENTICATION'
});
// or
login.init();
// and anytime later anywhere
login.setInterval(10000);
login.setLoginUrl('loginUrl');
login.setLogoutUrl('logoutUrl');
login.setUserInfoUrl('user-info-url');
login.setAuthenticationMethod(login.authenticationMethods.FORM_BASED_AUTHENTICATION);
// or any combination of the two above
}
Use the service for login like this:
login.login(credentials)
.then(loginSuccessful)
.catch(loginFailed);
function loginSuccessful(response) {
...
}
function loginFailed(response) {
...
}
for logout like this:
login.logout()
.then(logoutSuccessful);
function logoutSuccessful(response) {
...
}
for querying if the session is authenticated like this:
login.isAuthenticated();
and for querying the user info sent by the server:
login.getUserInfo();
The result is undefined after an unsuccessful authentication attempt or after logout.
How to get and develop
There are basically three ways to get started:
- use the git project directly (unless you wish to clone and go on with the code or contribute this would be a bit of an overkill)
- use npm package manager
- use bower package manager
Prerequisites
The followings you will need:
- git if you are to aquire the project via git
- NodeJS for obtaining tool chain dependencies
- Bower for getting code related dependencies
git
Cloning viaClone the angular-seed repository using git:
git clone https://bitbucket.org/vbmate/ui-toolkit-angular.git
cd ui-toolkit-angular-seed
If you just want to start a new project without the commit history then you can do:
git clone --depth=1 https://bitbucket.org/vbmate/ui-toolkit-angular.git <your-project-name>
The depth=1
tells git to only pull down one commit worth of historical data.
npm
Getting withInstalling the package with npm is pretty straightforward
npm install vbm-angular-toolkit
bower
Getting withInstalling the package with bower is again fairly simple
bower install vbm-angular-toolkit
Install Dependencies
We have two kinds of dependencies in this project: tools and angular framework code. The tools help us manage and test the application.
- get the tools depended upon via
npm
, the node package manager. - get the angular code via
bower
, a client-side code package manager.
npm
is preconfigured to automatically run bower
so we can simply do:
npm install
Behind the scenes this will also call bower install
. You should find that you have two new folders in your project.
node_modules
- contains the npm packages for the tools we needsrc/bower_components
- contains the angular framework files
Note that the bower_components
folder would normally be installed in the root folder but this location is changed through the .bowerrc
file. Putting it in the src
folder makes it easier to serve the files by a webserver.
Directory Layout
dist/ --> all the latest distribution files
demo/ --> demo application sketches
logger/ --> logger demonstration application
loggerToastr.service.js --> logger service extension based on angular-toastr
loggerToastr.service.spec.js --> test specification code
loggerToastrDemo.module.js --> demo module
src/ --> all of the source files for the application
heartbeat/ --> all heartbeat related files
heartbeat.module.js --> module definition
heartbeat.service.js --> service code
heartbeat.service.spec.js --> test specification code
logger/ --> all logger related files
logger.module.js --> module definition
logger.service.js --> service code
logger.service.spec.js --> test specification code
logom/ --> all login related files
login.module.js --> module definition
login.service.js --> service code
login.service.spec.js --> test specification code
karma.conf.js --> config file for running unit tests with Karma
Testing
There are thorough unit tests there for all the services. End-to-end tests on the other hand make not much sense as this is not a stand alone application but a bunch of services.
Running Unit Tests
The package comes preconfigured with unit tests. These are written using mocha and chai which we run with the
Karma Test Runner. Karma configuration file is also provided as well as the npm scripts
to run them.
- the configuration is found at
karma.conf.js
- the unit tests are found next to the code they are testing and are named as
*.spec.js
.
The easiest way to run the unit tests is to use the supplied npm script:
npm test
This script will start the Karma test runner to execute the unit tests. Moreover, Karma will sit and watch the source and test files for changes and then re-run the tests whenever any of them change. This is the recommended strategy; if your unit tests are being run every time you save a file then you receive instant feedback on any changes that break the expected code functionality.
You can also ask Karma to do a single run of the tests and then exit. This is useful if you want to check that a particular version of the code is operating as expected. The project contains a predefined script to do this:
npm run test-single-run
Updating Angular
The angular framework library code and tools are acquired through package managers (npm
and bower
) you can use these tools instead to
update the dependencies.
You can update the tool dependencies by running:
npm update
This will find the latest versions that match the version ranges specified in the package.json
file.
You can update the Angular dependencies by running:
bower update
This will find the latest versions that match the version ranges specified in the bower.json
file.
Links
This will find the latest versions that match the version ranges specified in the bower.json
file.