Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 191 lines (125 sloc) 7.019 kb
f154f5d @chetan51 First commit
authored
1 Ni - a minimalistic Node framework that makes setting up an MVC project a breeze
2 ================================================================================
3
4 Ni helps you set up a well-organized project, with a file structure separated into models, views, controllers, libraries and helpers. It's intuitive and simple to use, and doesn't get in the way of using other modules and Node plugins in your project.
5
d917a1f @chetan51 Fixed spelling error
authored
6 Ni is inspired by [CodeIgniter](http://codeigniter.com/), and its name is an abbreviation of NodeIgniter.
f154f5d @chetan51 First commit
authored
7
8 What's awesome about Ni?
9 ---------------------------
10
18f6b8a @chetan51 Fixed small formatting error
authored
11 * It's packaged as a regular Node module, so you just `require` it and you're ready to go
788ed9d @chetan51 Minor change to README
authored
12 * You can use other Node modules and Connect middle-ware as you usually would; Ni doesn't get in the way
f154f5d @chetan51 First commit
authored
13 * It's easy to use and loads your models, views, controllers, libraries and helpers automatically so you can just start using them everywhere
14
15 How do I use Ni?
16 -------------------
17
18 It's as simple as telling Ni where to look for your files, and then asking it to boot:
19
d03cf0a @chetan51 Replaced all tabs with spaces and fixed some alignment
authored
20 var Ni = require('../lib/ni');
e19e135 @chetan51 Updated README for configuration API
authored
21
22 Ni.config('root', "myapp/src");
23
d03cf0a @chetan51 Replaced all tabs with spaces and fixed some alignment
authored
24 Ni.boot(function() {
25 // Ready to start the server!
75acd22 @chetan51 Changed name of automatic view renderer to renderView
authored
26 });
f154f5d @chetan51 First commit
authored
27
75acd22 @chetan51 Changed name of automatic view renderer to renderView
authored
28 The rest of your code now has access to all your models, views, and controllers with `Ni.model('MODELNAME')`, `Ni.view('VIEWNAME')` and `Ni.controller('CONTROLLERNAME')`.
f154f5d @chetan51 First commit
authored
29
a5ca3fc @chetan51 Removed use of globals everywhere
authored
30 Note that your controllers, models, libraries and helpers should be packaged as Node modules, and your views can be plain text, template (Markdown, Mustache, etc), or HTML files.
f154f5d @chetan51 First commit
authored
31
32 You even get a router for free!
33 -------------------------------
34
35 Ni provides a router you can use with Connect to have requests sent to the appropriate controller functions according to URL segments.
36
37 Use it with Connect:
38
d03cf0a @chetan51 Replaced all tabs with spaces and fixed some alignment
authored
39 var app = Connect.createServer(
40 Ni.router
41 // You can add other Connect middle-ware here
42 );
f154f5d @chetan51 First commit
authored
43
44 It parses the URL and sends the request to the correct controller function as follows:
45
e19e135 @chetan51 Updated README for configuration API
authored
46 http://myapp.com/[controller]/[function]/[argument 1]/[argument 2]/[etc]
f154f5d @chetan51 First commit
authored
47
e19e135 @chetan51 Updated README for configuration API
authored
48 If no controller is specified (`http://myapp.com/`), it loads the `home` controller's `index` function.
f154f5d @chetan51 First commit
authored
49
d9ae282 @chetan51 Fixed some formatting
authored
50 If no function is specified (http://yourapp.com/[controller]), it loads the `[controller]`'s `index` function.
f154f5d @chetan51 First commit
authored
51
cae662b @chetan51 Better formatting
authored
52 You can define custom routes using `Ni.addRoute(source, destination, [method])`
2ff1e1c @maritz Add readme for Ni.addRoute
maritz authored
53
54 Some examples:
55
cae662b @chetan51 Better formatting
authored
56 With this custom route calling `myapp.com` will internally redirect to use your `News` controller and call the `index` function on it:
57
2ff1e1c @maritz Add readme for Ni.addRoute
maritz authored
58 Ni.addRoute('/', '/News/index');
59
cae662b @chetan51 Better formatting
authored
60 You can use regular expressions as well. This leads `myapp.com/register` to your `User` controller and its `register` function:
61
2ff1e1c @maritz Add readme for Ni.addRoute
maritz authored
62 Ni.addRoute(/^\/register/i, '/User/register');
63
64 If you want to use arguments with custom routes, you can do that as well:
cae662b @chetan51 Better formatting
authored
65
bfec7d9 @maritz Fix README.md again....
maritz authored
66 Ni.addRoute(/^\/details\/(.*)$/i, '/User/details/$1');
2ff1e1c @maritz Add readme for Ni.addRoute
maritz authored
67
e4772f7 @maritz Fix README.md again
maritz authored
68 You can also define functions to test the path. For example:
cae662b @chetan51 Better formatting
authored
69
70 Calling `myapp.com/add/1/2` will internally redirect to use the `Number` controller and call the `positive` function, while calling
71 `myapp.com/add/1/-2` will call the `negative` function.
72
73 Ni.addRoute(function(path) {
74 var args = path.split('/'),
75 firstNum = parseInt(args[2]),
76 secondNum = parseInt(args[3]),
77 result = firstNum + secondNum;
2ff1e1c @maritz Add readme for Ni.addRoute
maritz authored
78 if (args[1] !== 'add')
79 return false; // this leaves the path untouched and prevents this function from sucking in all other requests as well
cae662b @chetan51 Better formatting
authored
80 return result > 0 ? '/Number/positive' : '/Number/negative';
81 });
2ff1e1c @maritz Add readme for Ni.addRoute
maritz authored
82
83 You can limit the allowed HTTP methods by using custom routes.
cae662b @chetan51 Better formatting
authored
84 This will internally redirect `myapp.com/comment` to use your `Comments` controler and its `new` function - but only if the used HTTP Method is `POST` or `PUT`:
2ff1e1c @maritz Add readme for Ni.addRoute
maritz authored
85
86 Ni.addRoute('/comment', '/Comments/new', ['POST', 'PUT']);
87
cae662b @chetan51 Better formatting
authored
88 And this will redirect all `GET` requests to myapp.com/comment to use your `Comments` controller's `index` function.
89
2ff1e1c @maritz Add readme for Ni.addRoute
maritz authored
90 Ni.addRoute('/comment', '/Comments/', 'GET');
91
92 This way you can disallow methods for some routes as well:
cae662b @chetan51 Better formatting
authored
93
2ff1e1c @maritz Add readme for Ni.addRoute
maritz authored
94 Ni.addRoute('/Comments/update', '/Home/method_not_allowed', 'GET');
95
f154f5d @chetan51 First commit
authored
96 Can I see an example?
97 ---------------------
98
99 If you have your project organized like this:
100
d03cf0a @chetan51 Replaced all tabs with spaces and fixed some alignment
authored
101 /app.js
102 /controllers
103 /calculator.js
104 /home.js
105 /views
106 /calculator.html
107 /home.html
108 /models
109 /calculator.js
f154f5d @chetan51 First commit
authored
110
111 You can access your stuff with:
112
75acd22 @chetan51 Changed name of automatic view renderer to renderView
authored
113 * `Ni.controller('calculator')`
114 * `Ni.view('calculator')`
115 * `Ni.model('calculator')`
f154f5d @chetan51 First commit
authored
116
d9ae282 @chetan51 Fixed some formatting
authored
117 A really well-commented example is in the source code in the `/example` folder, check it out!
f154f5d @chetan51 First commit
authored
118
7daa1a2 @chetan51 Edited README.md via GitHub
authored
119 (Note that you'll need the following to run the example in the `/example` folder: [Connect](https://github.com/senchalabs/Connect), [Quip](https://github.com/caolan/quip) and [Mu](https://github.com/raycmorgan/Mu). You can get them easily using [npm](https://github.com/isaacs/npm).)
46551a1 @chetan51 Added example dependencies to README
authored
120
f154f5d @chetan51 First commit
authored
121 How would my controllers, models, libraries, helpers look?
122 -------------------------------------------------------
123
d9ae282 @chetan51 Fixed some formatting
authored
124 Each of those is just a Node module. For example, the calculator controller mentioned above (in the `/example` folder) looks like this:
f154f5d @chetan51 First commit
authored
125
d03cf0a @chetan51 Replaced all tabs with spaces and fixed some alignment
authored
126 var Ni = require('../../lib/ni'),
127 Mu = require('mu'),
128 Quip = require('quip');
129
130 var CalculatorController = function() {
131
132 /*
133 * This function is called when the URL does not indicate a function to
134 * be called, so it would look like /calculator.
135 */
136
ee801c3 @chetan51 Updated README for automatic views
authored
137 this.index = function(req, res, next) {
d2a88e7 @chetan51 Another minor change to README
authored
138
d03cf0a @chetan51 Replaced all tabs with spaces and fixed some alignment
authored
139 res.ok('Welcome to the calculator!');
d2a88e7 @chetan51 Another minor change to README
authored
140
d03cf0a @chetan51 Replaced all tabs with spaces and fixed some alignment
authored
141 }
142
143 /*
144 * This function is called when the URL indicates "add" as the function
145 * to be called, so it would look like /calculator/add.
146 *
147 * For example, loading the URL /calculator/add/4/5 would call the below
148 * function with a = 4 and b = 5.
149 */
150
ee801c3 @chetan51 Updated README for automatic views
authored
151 this.add = function(req, res, next, a, b) {
d2a88e7 @chetan51 Another minor change to README
authored
152
d03cf0a @chetan51 Replaced all tabs with spaces and fixed some alignment
authored
153 if (a && b) {
154 a = parseInt(a);
155 b = parseInt(b);
156
75acd22 @chetan51 Changed name of automatic view renderer to renderView
authored
157 var template = Ni.view('calculator').template;
d03cf0a @chetan51 Replaced all tabs with spaces and fixed some alignment
authored
158 var data = {result: a + b};
159
160 var compiled = Mu.compileText(template, null);
161 compiled(data).addListener('data', function (c) {
162 res.ok(c);
163 });
164 }
165 else {
166 res.error("a and b must both be provided.");
167 }
d2a88e7 @chetan51 Another minor change to README
authored
168
d03cf0a @chetan51 Replaced all tabs with spaces and fixed some alignment
authored
169 }
d2a88e7 @chetan51 Another minor change to README
authored
170
d03cf0a @chetan51 Replaced all tabs with spaces and fixed some alignment
authored
171 };
172
173 module.exports = new CalculatorController();
f154f5d @chetan51 First commit
authored
174
18f6b8a @chetan51 Fixed small formatting error
authored
175 Let's get crackin'!
f154f5d @chetan51 First commit
authored
176 -------------------
177
755ea0c @chetan51 Made README more clear
authored
178 1. Get Ni by downloading the source code, or `git clone`ing the repo.
179 2. Install Ni as your would any other Node module, by copying `lib/ni.js` to your `~/.node_libraries` folder.
180 3. Copy the `/example` directory and modify it to set up your project.
181 4. Run `node app.js` in the copied directory to start the server.
a5ca3fc @chetan51 Removed use of globals everywhere
authored
182
183 (We'll add Ni to `npm` soon, don't trip.)
d4b282b @chetan51 Added contributors section to README
authored
184
185 Contributors
186 ------------
187
188 A big thank you to you guys who helped (and are helping) make Ni awesome:
189
190 [Moritz Peters](https://github.com/maritz)
Something went wrong with that request. Please try again.