|
| 1 | +[](https://app.wercker.com/project/byKey/28d30a7502dfe52c4b1610aef1c34a5f) |
| 2 | + |
1 | 3 | # Generala |
2 | 4 |
|
3 | 5 | For information about the project please head to [the wiki](https://github.com/HackYourFuture/generala/wiki) |
4 | 6 |
|
5 | | -# Workflow |
| 7 | +Based on `angular-seed` — the seed for AngularJS apps |
| 8 | + |
| 9 | +This project is an application skeleton for a typical [AngularJS][angularjs] web app. You can use it |
| 10 | +to quickly bootstrap your angular webapp projects and dev environment for these projects. |
| 11 | + |
| 12 | +The seed contains a sample AngularJS application and is preconfigured to install the Angular |
| 13 | +framework and a bunch of development and testing tools for instant web development gratification. |
| 14 | + |
| 15 | +The seed app doesn't do much, just shows how to wire two controllers and views together. |
| 16 | + |
| 17 | + |
| 18 | +## Getting Started |
| 19 | + |
| 20 | +To get you started you can simply clone the `angular-seed` repository and install the dependencies: |
| 21 | + |
| 22 | +### Prerequisites |
| 23 | + |
| 24 | +You need git to clone the `angular-seed` repository. You can get git from [here][git]. |
| 25 | + |
| 26 | +We also use a number of Node.js tools to initialize and test `angular-seed`. You must have Node.js |
| 27 | +and its package manager (npm) installed. You can get them from [here][node]. |
| 28 | + |
| 29 | +### Clone `angular-seed` |
| 30 | + |
| 31 | +Clone the `angular-seed` repository using git: |
| 32 | + |
| 33 | +``` |
| 34 | +git clone https://github.com/angular/angular-seed.git |
| 35 | +cd angular-seed |
| 36 | +``` |
| 37 | + |
| 38 | +If you just want to start a new project without the `angular-seed` commit history then you can do: |
| 39 | + |
| 40 | +``` |
| 41 | +git clone --depth=1 https://github.com/angular/angular-seed.git <your-project-name> |
| 42 | +``` |
| 43 | + |
| 44 | +The `depth=1` tells git to only pull down one commit worth of historical data. |
| 45 | + |
| 46 | +### Install Dependencies |
| 47 | + |
| 48 | +We have two kinds of dependencies in this project: tools and Angular framework code. The tools help |
| 49 | +us manage and test the application. |
| 50 | + |
| 51 | +* We get the tools we depend upon via `npm`, the [Node package manager][npm]. |
| 52 | +* We get the Angular code via `bower`, a [client-side code package manager][bower]. |
| 53 | +* In order to run the end-to-end tests, you will also need to have the |
| 54 | + [Java Development Kit (JDK)][jdk] installed on your machine. Check out the section on |
| 55 | + [end-to-end testing](#e2e-testing) for more info. |
| 56 | + |
| 57 | +We have preconfigured `npm` to automatically run `bower` so we can simply do: |
| 58 | + |
| 59 | +``` |
| 60 | +npm install |
| 61 | +``` |
| 62 | + |
| 63 | +Behind the scenes this will also call `bower install`. After that, you should find out that you have |
| 64 | +two new folders in your project. |
| 65 | + |
| 66 | +* `node_modules` - contains the npm packages for the tools we need |
| 67 | +* `app/bower_components` - contains the Angular framework files |
| 68 | + |
| 69 | +*Note that the `bower_components` folder would normally be installed in the root folder but |
| 70 | +`angular-seed` changes this location through the `.bowerrc` file. Putting it in the `app` folder |
| 71 | +makes it easier to serve the files by a web server.* |
| 72 | + |
| 73 | +### Run the Application |
| 74 | + |
| 75 | +We have preconfigured the project with a simple development web server. The simplest way to start |
| 76 | +this server is: |
| 77 | + |
| 78 | +``` |
| 79 | +npm start |
| 80 | +``` |
| 81 | + |
| 82 | +Now browse to the app at [`localhost:8000/index.html`][local-app-url]. |
| 83 | + |
| 84 | + |
| 85 | +## Directory Layout |
| 86 | + |
| 87 | +``` |
| 88 | +app/ --> all of the source files for the application |
| 89 | + app.css --> default stylesheet |
| 90 | + components/ --> all app specific modules |
| 91 | + version/ --> version related components |
| 92 | + version.js --> version module declaration and basic "version" value service |
| 93 | + version_test.js --> "version" value service tests |
| 94 | + version-directive.js --> custom directive that returns the current app version |
| 95 | + version-directive_test.js --> version directive tests |
| 96 | + interpolate-filter.js --> custom interpolation filter |
| 97 | + interpolate-filter_test.js --> interpolate filter tests |
| 98 | + view1/ --> the view1 view template and logic |
| 99 | + view1.html --> the partial template |
| 100 | + view1.js --> the controller logic |
| 101 | + view1_test.js --> tests of the controller |
| 102 | + view2/ --> the view2 view template and logic |
| 103 | + view2.html --> the partial template |
| 104 | + view2.js --> the controller logic |
| 105 | + view2_test.js --> tests of the controller |
| 106 | + app.js --> main application module |
| 107 | + index.html --> app layout file (the main html template file of the app) |
| 108 | + index-async.html --> just like index.html, but loads js files asynchronously |
| 109 | +karma.conf.js --> config file for running unit tests with Karma |
| 110 | +e2e-tests/ --> end-to-end tests |
| 111 | + protractor-conf.js --> Protractor config file |
| 112 | + scenarios.js --> end-to-end scenarios to be run by Protractor |
| 113 | +``` |
| 114 | + |
| 115 | + |
| 116 | +## Testing |
| 117 | + |
| 118 | +There are two kinds of tests in the `angular-seed` application: Unit tests and end-to-end tests. |
| 119 | + |
| 120 | +### Running Unit Tests |
| 121 | + |
| 122 | +The `angular-seed` app comes preconfigured with unit tests. These are written in [Jasmine][jasmine], |
| 123 | +which we run with the [Karma][karma] test runner. We provide a Karma configuration file to run them. |
| 124 | + |
| 125 | +* The configuration is found at `karma.conf.js`. |
| 126 | +* The unit tests are found next to the code they are testing and have an `_test.js` suffix (e.g. |
| 127 | + `view1_test.js`). |
| 128 | + |
| 129 | +The easiest way to run the unit tests is to use the supplied npm script: |
| 130 | + |
| 131 | +``` |
| 132 | +npm test |
| 133 | +``` |
| 134 | + |
| 135 | +This script will start the Karma test runner to execute the unit tests. Moreover, Karma will start |
| 136 | +watching the source and test files for changes and then re-run the tests whenever any of them |
| 137 | +changes. |
| 138 | +This is the recommended strategy; if your unit tests are being run every time you save a file then |
| 139 | +you receive instant feedback on any changes that break the expected code functionality. |
| 140 | + |
| 141 | +You can also ask Karma to do a single run of the tests and then exit. This is useful if you want to |
| 142 | +check that a particular version of the code is operating as expected. The project contains a |
| 143 | +predefined script to do this: |
| 144 | + |
| 145 | +``` |
| 146 | +npm run test-single-run |
| 147 | +``` |
| 148 | + |
| 149 | + |
| 150 | +<a name="e2e-testing"></a> |
| 151 | +### Running End-to-End Tests |
| 152 | + |
| 153 | +The `angular-seed` app comes with end-to-end tests, again written in [Jasmine][jasmine]. These tests |
| 154 | +are run with the [Protractor][protractor] End-to-End test runner. It uses native events and has |
| 155 | +special features for Angular applications. |
| 156 | + |
| 157 | +* The configuration is found at `e2e-tests/protractor-conf.js`. |
| 158 | +* The end-to-end tests are found in `e2e-tests/scenarios.js`. |
| 159 | + |
| 160 | +Protractor simulates interaction with our web app and verifies that the application responds |
| 161 | +correctly. Therefore, our web server needs to be serving up the application, so that Protractor can |
| 162 | +interact with it. |
| 163 | + |
| 164 | +**Before starting Protractor, open a separate terminal window and run:** |
| 165 | + |
| 166 | +``` |
| 167 | +npm start |
| 168 | +``` |
| 169 | + |
| 170 | +In addition, since Protractor is built upon WebDriver, we need to ensure that it is installed and |
| 171 | +up-to-date. The `angular-seed` project is configured to do this automatically before running the |
| 172 | +end-to-end tests, so you don't need to worry about it. If you want to manually update the WebDriver, |
| 173 | +you can run: |
| 174 | + |
| 175 | +``` |
| 176 | +npm run update-webdriver |
| 177 | +``` |
| 178 | + |
| 179 | +Once you have ensured that the development web server hosting our application is up and running, you |
| 180 | +can run the end-to-end tests using the supplied npm script: |
| 181 | + |
| 182 | +``` |
| 183 | +npm run protractor |
| 184 | +``` |
| 185 | + |
| 186 | +This script will execute the end-to-end tests against the application being hosted on the |
| 187 | +development server. |
| 188 | + |
| 189 | +**Note:** |
| 190 | +Under the hood, Protractor uses the [Selenium Standalone Server][selenium], which in turn requires |
| 191 | +the [Java Development Kit (JDK)][jdk] to be installed on your local machine. Check this by running |
| 192 | +`java -version` from the command line. |
| 193 | + |
| 194 | +If JDK is not already installed, you can download it [here][jdk-download]. |
| 195 | + |
| 196 | + |
| 197 | +## Updating Angular |
| 198 | + |
| 199 | +Since the Angular framework library code and tools are acquired through package managers (npm and |
| 200 | +bower) you can use these tools to easily update the dependencies. Simply run the preconfigured |
| 201 | +script: |
| 202 | + |
| 203 | +``` |
| 204 | +npm run update-deps |
| 205 | +``` |
| 206 | + |
| 207 | +This will call `npm update` and `bower update`, which in turn will find and install the latest |
| 208 | +versions that match the version ranges specified in the `package.json` and `bower.json` files |
| 209 | +respectively. |
| 210 | + |
| 211 | + |
| 212 | +## Loading Angular Asynchronously |
| 213 | + |
| 214 | +The `angular-seed` project supports loading the framework and application scripts asynchronously. |
| 215 | +The special `index-async.html` is designed to support this style of loading. For it to work you must |
| 216 | +inject a piece of Angular JavaScript into the HTML page. The project has a predefined script to help |
| 217 | +do this: |
| 218 | + |
| 219 | +``` |
| 220 | +npm run update-index-async |
| 221 | +``` |
| 222 | + |
| 223 | +This will copy the contents of the `angular-loader.js` library file into the `index-async.html` |
| 224 | +page. You can run this every time you update the version of Angular that you are using. |
| 225 | + |
| 226 | + |
| 227 | +## Serving the Application Files |
| 228 | + |
| 229 | +While Angular is client-side-only technology and it is possible to create Angular web apps that |
| 230 | +do not require a backend server at all, we recommend serving the project files using a local |
| 231 | +web server during development to avoid issues with security restrictions (sandbox) in browsers. The |
| 232 | +sandbox implementation varies between browsers, but quite often prevents things like cookies, XHR, |
| 233 | +etc to function properly when an HTML page is opened via the `file://` scheme instead of `http://`. |
| 234 | + |
| 235 | +### Running the App during Development |
| 236 | + |
| 237 | +The `angular-seed` project comes preconfigured with a local development web server. It is a Node.js |
| 238 | +tool called [http-server][http-server]. You can start this web server with `npm start`, but you may |
| 239 | +choose to install the tool globally: |
| 240 | + |
| 241 | +``` |
| 242 | +sudo npm install -g http-server |
| 243 | +``` |
| 244 | + |
| 245 | +Then you can start your own development web server to serve static files from a folder by running: |
| 246 | + |
| 247 | +``` |
| 248 | +http-server -a localhost -p 8000 |
| 249 | +``` |
| 250 | + |
| 251 | +Alternatively, you can choose to configure your own web server, such as Apache or Nginx. Just |
| 252 | +configure your server to serve the files under the `app/` directory. |
| 253 | + |
| 254 | +### Running the App in Production |
| 255 | + |
| 256 | +This really depends on how complex your app is and the overall infrastructure of your system, but |
| 257 | +the general rule is that all you need in production are the files under the `app/` directory. |
| 258 | +Everything else should be omitted. |
| 259 | + |
| 260 | +Angular apps are really just a bunch of static HTML, CSS and JavaScript files that need to be hosted |
| 261 | +somewhere they can be accessed by browsers. |
| 262 | + |
| 263 | +If your Angular app is talking to the backend server via XHR or other means, you need to figure out |
| 264 | +what is the best way to host the static files to comply with the same origin policy if applicable. |
| 265 | +Usually this is done by hosting the files by the backend server or through reverse-proxying the |
| 266 | +backend server(s) and web server(s). |
6 | 267 |
|
7 | | -## Develop |
8 | 268 |
|
9 | | -### Build |
| 269 | +## Continuous Integration |
10 | 270 |
|
11 | | -...TBD... |
| 271 | +### Travis CI |
12 | 272 |
|
13 | | -### Test |
| 273 | +[Travis CI][travis] is a continuous integration service, which can monitor GitHub for new commits to |
| 274 | +your repository and execute scripts such as building the app or running tests. The `angular-seed` |
| 275 | +project contains a Travis configuration file, `.travis.yml`, which will cause Travis to run your |
| 276 | +tests when you push to GitHub. |
14 | 277 |
|
15 | | -...TBD... |
| 278 | +You will need to enable the integration between Travis and GitHub. See the |
| 279 | +[Travis website][travis-docs] for instructions on how to do this. |
16 | 280 |
|
17 | | -### Deploy |
18 | 281 |
|
19 | | -...TBD... |
| 282 | +## Contact |
20 | 283 |
|
| 284 | +For more information on AngularJS please check out [angularjs.org][angularjs]. |
21 | 285 |
|
22 | | -## How to collaborate |
23 | 286 |
|
24 | | -...TBD... |
| 287 | +[angularjs]: https://angularjs.org/ |
| 288 | +[bower]: http://bower.io/ |
| 289 | +[git]: https://git-scm.com/ |
| 290 | +[http-server]: https://github.com/indexzero/http-server |
| 291 | +[jasmine]: https://jasmine.github.io/ |
| 292 | +[jdk]: https://wikipedia.org/wiki/Java_Development_Kit |
| 293 | +[jdk-download]: http://www.oracle.com/technetwork/java/javase/downloads |
| 294 | +[karma]: https://karma-runner.github.io/ |
| 295 | +[local-app-url]: http://localhost:8000/index.html |
| 296 | +[node]: https://nodejs.org/ |
| 297 | +[npm]: https://www.npmjs.org/ |
| 298 | +[protractor]: http://www.protractortest.org/ |
| 299 | +[selenium]: http://docs.seleniumhq.org/ |
| 300 | +[travis]: https://travis-ci.org/ |
| 301 | +[travis-docs]: https://docs.travis-ci.com/user/getting-started |
| 302 | +>>>>>>> origin/angularclient |
0 commit comments