## Prerequisites * Create [IBM Bluemix](http://www.ibm.com/cloud-computing/bluemix/) account * Install [yeoman](http://yeoman.io), [nodeJS](https://nodejs.org/), [npm](https://www.npmjs.com/), [bower](bower.io), and optionally [sass](http://sass-lang.com/install) * Create an app, with starter pack - nodeJS + Cloudant; remember app name & Cloudant service name/credentials in VCAP environment variable. ## Install * Install `generator-angular-bluemix`: ``` npm install -g generator-angular-bluemix ``` * Make a new directory, and `cd` into it ``` mkdir app-name && cd $_ ``` * Run `yo angular-bluemix`, optionally passing an app name ``` yo angular-bluemix ``` * Answer the installation checklist with default options. * Make sure `manifest.yml`, to have correct Cloudant service name, and app-name ``` applications: - services: - [app-name]-cloudantNoSQLDB host: [app-name] name: [app-name] ``` p.s. You must have correct service-name; or otherwise, the application won't start. * Modify `./server/config/environment/development.js`; input Cloudant credentials for local development ## Project Structure Generated folder structure ├── client │   ├── app - All of our app specific components go in here │   ├── assets - Custom assets: fonts, images, etc… │   ├── components - Our reusable components, non-specific to to our app │ ├── e2e - Our protractor end to end tests │ └── server ├── api - Our apps server api ├── auth - For handling authentication with different auth strategies ├── components - Our reusable or app-wide components ├── config - Where we do the bulk of our apps configuration │ └── local.env.js - Keep our environment variables out of source control │   └── environment - Configuration specific to the node environment └── views - Server rendered views An example client component in `client/app` main ├── main.js - Routes ├── main.controller.js - Controller for our main route ├── main.controller.spec.js - Test ├── main.html - View └── main.less - Styles An example server component in `server/api` thing ├── index.js - Routes ├── thing.controller.js - Controller for our `thing` endpoint ├── thing.model.js - Database model ├── thing.socket.js - Register socket events └── thing.spec.js - Test ## Example Project Generated [http://generated001.mybluemix.net](http://generated001.mybluemix.net) ## Build Use below cli for livereload, build, and deploy * Run live-reload, for local development ``` grunt serve ``` * Build the project, optimize it; create a distribution folder `./dist` ``` grunt ``` * Run live-reload from `./dist` ``` grunt serve:dist ``` ## Testing * Running `grunt test` will run the client and server unit tests with karma and mocha. ``` grunt test ``` * Use `grunt test:server` to only run server tests. ``` grunt test:serve ``` * Use `grunt test:client` to only run client tests. ``` grunt test:client ``` **Protractor tests** * To setup protractor e2e tests, you must first run ``` npm run update-webdriver ``` * Use `grunt test:e2e` to have protractor go through tests located in the `e2e` folder. ## Bluemix Deploy * Deploy to bluemix, (assuming you have already log-on, with cf-login). Don't push development folder (>300MB) ``` cf push [app-name] -p ./dist -m 256M ``` * Alternatively, to make your deployment process easier consider using [IBM DevOps service](https://hub.jazz.net/). ## Supported Configurations **Client** * Scripts: `JavaScript` * Markup: `HTML` * Stylesheets: `CSS`, `Sass`(tbc) * Angular Routers: `ngRoute` **Server** * Database: `None`, `Cloudant`, `CouchDB` * (Working in progress) Authentication boilerplate: `Yes`, `No` * (Working in progress) oAuth integrations: `Facebook` `Twitter` `Google` * (Working in progress) Socket.io integration: `Yes`, `No` ## Injection A grunt task looks for new files in your `client/app` and `client/components` folder and automatically injects them in the appropriate places based on an injection block. * `scss` files into `client/app.scss` * `css` files into `client/index.html` * `js` files into `client/index.html` ## Generators Available generators: * App - angular-bluemix (aka angular-bluemix:app) * Server Side - angular-bluemix:endpoint * Client Side - angular-bluemix:route - angular-bluemix:controller - angular-bluemix:filter - angular-bluemix:directive - angular-bluemix:service - angular-bluemix:provider - angular-bluemix:factory - angular-bluemix:decorator ### App Sets up a new AngularJS + Express app, generating the boilerplate. Example: ```bash yo angular-bluemix ``` ### Endpoint Generates a new API endpoint. Example: ```bash yo angular-bluemix:endpoint message [?] What will the url of your endpoint be? /api/messages ``` Produces: server/api/message/index.js server/api/message/message.spec.js server/api/message/message.controller.js server/api/message/message.model.js (optional) server/api/message/message.socket.js (optional) This is not fully functional. You need to implement `message.controller.js`, connecting to cloudant, via cradle library. ### Route Generates a new route. Example: ```bash yo angular-bluemix:route myroute [?] Where would you like to create this route? client/app/ [?] What will the url of your route be? /myroute ``` Produces: client/app/myroute/myroute.js client/app/myroute/myroute.controller.js client/app/myroute/myroute.controller.spec.js client/app/myroute/myroute.html client/app/myroute/myroute.scss ### Controller Generates a controller. Example: ```bash yo angular-bluemix:controller user [?] Where would you like to create this controller? client/app/ ``` Produces: client/app/user/user.controller.js client/app/user/user.controller.spec.js ### Directive Generates a directive. Example: ```bash yo angular-bluemix:directive myDirective [?] Where would you like to create this directive? client/app/ [?] Does this directive need an external html file? Yes ``` Produces: client/app/myDirective/myDirective.directive.js client/app/myDirective/myDirective.directive.spec.js client/app/myDirective/myDirective.html client/app/myDirective/myDirective.scss **Simple directive without an html file** Example: ```bash yo angular-bluemix:directive simple [?] Where would you like to create this directive? client/app/ [?] Does this directive need an external html file? No ``` Produces: client/app/simple/simple.directive.js client/app/simple/simple.directive.spec.js ### Filter Generates a filter. Example: ```bash yo angular-bluemix:filter myFilter [?] Where would you like to create this filter? client/app/ ``` Produces: client/app/myFilter/myFilter.filter.js client/app/myFilter/myFilter.filter.spec.js ### Service Generates an AngularJS service. Example: ```bash yo angular-bluemix:service myService [?] Where would you like to create this service? client/app/ ``` Produces: client/app/myService/myService.service.js client/app/myService/myService.service.spec.js You can also do `yo angular-fullstack:factory` and `yo angular-fullstack:provider` for other types of services. ### Decorator Generates an AngularJS service decorator. Example: ```bash yo angular-bluemix:decorator serviceName [?] Where would you like to create this decorator? client/app/ ``` Produces client/app/serviceName/serviceName.decorator.js ## Bower Components The following packages are always installed by the app generator: * angular * angular-cookies * angular-mocks * angular-resource * angular-sanitize * angular-scenario * es5-shim * font-awesome * json3 * jquery * lodash * angular-route * angular-Material * angular-bootstrap All of these can be updated with `bower update` as new versions are released.