|
1 | | -# angular-seed — the seed for <angular/> apps |
| 1 | +# angular-requirejs-html5boilerplate-seed |
2 | 2 |
|
3 | | -This project is an application skeleton for a typical [angular](http://angularjs.org/) web app. You |
4 | | -can use it to quickly bootstrap your angular webapp projects and dev environment for these projects. |
| 3 | +This project combines the application skeleton for a typical [Angular](http://angularjs.org/) web |
| 4 | +app with [RequireJs](http://requirejs.org/) for modularized components. It also makes use of |
| 5 | +[Html5Boilerplate](http://html5boilerplate.com/) for a nice starting point, and utilizes |
| 6 | +[Sass](http://sass-lang.com/) so that css development can be fun! |
5 | 7 |
|
6 | | -The seed contains angular libraries, test libraries and a bunch of scripts all preconfigured for |
7 | | -instant web development gratification. Just clone the repo (or download the zip/tarball), start up |
8 | | -our (or yours) webserver and you are ready to develop and test your application. |
| 8 | +For a detailed explanation of the majority of the files in this project, checkout the original |
| 9 | +[angular-seed](https://github.com/angular/angular-seed) project. This will explain all the details |
| 10 | +so you can get running fast! |
9 | 11 |
|
10 | 12 | The seed app doesn't do much, just shows how to wire two controllers and views together. You can |
11 | | -check it out by opening app/index.html in your browser (might not work file `file://` scheme in |
12 | | -certain browsers, see note below). |
| 13 | +check it out by opening app/index.html in your browser. |
13 | 14 |
|
14 | | -_Note: While angular is client-side-only technology and it's possible to create angular webapps that |
15 | | -don't require a backend server at all, we recommend hosting the project files using a local |
16 | | -webserver during development to avoid issues with security restrictions (sandbox) in browsers. The |
17 | | -sandbox implementation varies between browsers, but quite often prevents things like cookies, xhr, |
18 | | -etc to function properly when an html page is opened via `file://` scheme instead of `http://`._ |
19 | 15 |
|
20 | | - |
21 | | -## How to use angular-seed |
| 16 | +## How to use angular-requirejs-html5boilerplate-seed |
22 | 17 |
|
23 | 18 | Clone the angular-seed repository and start hacking... |
24 | 19 |
|
25 | 20 |
|
26 | | -### Running the app during development |
27 | | - |
28 | | -You can pick one of these options: |
29 | | - |
30 | | -* serve this repository with your webserver |
31 | | -* install node.js and run `scripts/web-server.js` |
32 | | - |
33 | | -Then navigate your browser to `http://localhost:<port>/app/index.html` to see the app running in |
34 | | -your browser. |
35 | | - |
36 | | - |
37 | | -### Running the app in production |
38 | | - |
39 | | -This really depends on how complex is your app and the overall infrastructure of your system, but |
40 | | -the general rule is that all you need in production are all the files under the `app/` directory. |
41 | | -Everything else should be omitted. |
42 | | - |
43 | | -angular apps are really just a bunch of static html, css and js files that just need to be hosted |
44 | | -somewhere, where they can be accessed by browsers. |
45 | | - |
46 | | -If your angular app is talking to the backend server via xhr or other means, you need to figure |
47 | | -out what is the best way to host the static files to comply with the same origin policy if |
48 | | -applicable. Usually this is done by hosting the files by the backend server or through |
49 | | -reverse-proxying the backend server(s) and a webserver(s). |
50 | | - |
51 | | - |
52 | | -### Running unit tests |
53 | | - |
54 | | -We recommend using [jasmine](http://pivotal.github.com/jasmine/) and |
55 | | -[JsTestDriver](http://code.google.com/p/js-test-driver/) for your unit tests/specs, but you are free |
56 | | -to use whatever works for you. |
57 | | - |
58 | | -Requires java and a local or remote browser. |
59 | | - |
60 | | -* start `scripts/test-server.sh` (on windows: `scripts\test-server.bat`) |
61 | | -* navigate your browser to `http://localhost:9876/` |
62 | | -* click on one of the capture links (preferably the "strict" one) |
63 | | -* run `scripts/test.sh` (on windows: `scripts\test.bat`) |
64 | | - |
65 | | - |
66 | | -### Continuous unit testing |
67 | | - |
68 | | -Requires ruby and [watchr](https://github.com/mynyml/watchr) gem. |
69 | | - |
70 | | -* start JSTD server and capture a browser as described above |
71 | | -* start watchr with `watchr scripts/watchr.rb` |
72 | | -* in a different window/tab/editor `tail -f logs/jstd.log` |
73 | | -* edit files in `app/` or `src/` and save them |
74 | | -* watch the log to see updates |
75 | | - |
76 | | -There are many other ways to achieve the same effect. Feel free to use them if you prefer them over |
77 | | -watchr. |
78 | | - |
79 | | - |
80 | | -### End to end testing |
81 | | - |
82 | | -angular ships with a baked-in end-to-end test runner that understands angular, your app and allows |
83 | | -you to write your tests with jasmine-like BDD syntax. |
84 | | - |
85 | | -Requires a webserver, node.js or your backend server that hosts the angular static files. |
86 | | - |
87 | | -Check out the [end-to-end runner's documentation](http://goo.gl/e8n06) for more info. |
88 | | - |
89 | | -* create your end-to-end tests in `test/e2e/scenarios.js` |
90 | | -* serve your project directory with your http/backend server or node.js + `scripts/web-server.js` |
91 | | -* open `http://localhost:port/test/e2e/runner.html` in your browser |
92 | | - |
93 | | - |
94 | | -### Receiving updates from upstream |
95 | | - |
96 | | -When we upgrade angular-seed's repo with newer angular or testing library code, you can just |
97 | | -fetch the changes and merge them into your project with git. |
98 | | - |
99 | | - |
100 | 21 | ## Directory Layout |
101 | 22 |
|
102 | 23 | app/ --> all of the files to be used in production |
103 | | - css/ --> css files |
| 24 | + compass/ --> sass files |
| 25 | + css/ --> compiled css files |
104 | 26 | app.css --> default stylesheet |
105 | 27 | img/ --> image files |
106 | 28 | index.html --> app layout file (the main html template file of the app) |
107 | 29 | js/ --> javascript files |
108 | | - controllers.js --> application controllers |
109 | | - filters.js --> custom angular filters |
110 | | - services.js --> custom angular services |
111 | | - widgets.js --> custom angular widgets |
112 | | - lib/ --> angular and 3rd party javascript libraries |
113 | | - angular/ |
114 | | - angular.js --> the latest angular js |
115 | | - angular.min.js --> the latest minified angular js |
116 | | - angular-ie-compat.js --> angular patch for IE 6&7 compatibility |
117 | | - version.txt --> version number |
118 | | - partials/ --> angular view partials (partial html templates) |
119 | | - partial1.html |
120 | | - partial2.html |
| 30 | + controllers/ |
| 31 | + controllers.js --> root controller file for requirejs |
| 32 | + AppController.js --> root application controller - handles all routing |
| 33 | + HomeController.js --> the controller for the _home_ view |
| 34 | + DataController.js --> the controller for the _data_ view |
| 35 | + filters/ |
| 36 | + filters.js --> root filter file for requirejs |
| 37 | + services/ |
| 38 | + services.js --> root services file for requirejs |
| 39 | + DataService.js --> a sample $Resource service that fetchs data for the _data_ view |
| 40 | + widgets/ |
| 41 | + widgets.js --> root widgets file for requirejs |
| 42 | + lib/ --> angular and 3rd party javascript libraries |
| 43 | + angular/ |
| 44 | + angular.js --> wraps angularjs in a requirejs module |
| 45 | + angular.min.js --> the latest minified angular js |
| 46 | + angular-ie-compat.js --> angular patch for IE 6&7 compatibility |
| 47 | + console/ |
| 48 | + console.js --> wraps console in a requirejs module |
| 49 | + console.min.js --> the minified source for our console logger |
| 50 | + jquery/ |
| 51 | + jquery.js --> wraps jquery in a requirejs module |
| 52 | + jquery.min.js --> the latest minified source for jquery |
| 53 | + underscore/ |
| 54 | + underscore.js --> wraps underscore in a requirejs module |
| 55 | + underscore-min.js --> the latest minified source for underscore |
| 56 | + modernizer-2.0.6.min.js --> modernizer so that out html5 elements load in <ie9 |
| 57 | + _boilerplate.js --> a starting file for any module you create |
| 58 | + app.js --> root application load logic - this is where angularjs is initialized |
| 59 | + bootstrap.js --> the bootstrap of our application - handles loading initial dependancies |
| 60 | + order.js --> plugin for requirejs to allow specifying script load order |
| 61 | + require.js --> requirejs source |
| 62 | + |
| 63 | + mock/ --> mocked RESTful server calls |
| 64 | + data/ |
| 65 | + list.json |
| 66 | + |
| 67 | + templates/ --> angular view partials (partial html templates) |
| 68 | + Data.xhtml |
| 69 | + Home.xhtml |
121 | 70 |
|
122 | 71 | config/jsTestDriver.conf --> config file for JsTestDriver |
123 | 72 |
|
@@ -145,7 +94,3 @@ fetch the changes and merge them into your project with git. |
145 | 94 | jstestdriver/ --> JSTD - JavaScript test runner |
146 | 95 | unit/ --> unit level specs/tests |
147 | 96 | controllersSpec.js --> specs for controllers |
148 | | - |
149 | | -## Contact |
150 | | - |
151 | | -For more information on angular please check out http://angularjs.org/ |
0 commit comments