From ac211f3cd9a1e26d42ad99108650b4bb64bcb9ab Mon Sep 17 00:00:00 2001 From: Anatoliy Chakkaev Date: Wed, 20 Mar 2013 15:08:51 +0400 Subject: [PATCH 1/6] Added doc builder --- scripts/doc.sh | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100755 scripts/doc.sh diff --git a/scripts/doc.sh b/scripts/doc.sh new file mode 100755 index 0000000..3ffe9c5 --- /dev/null +++ b/scripts/doc.sh @@ -0,0 +1,21 @@ +#!/bin/bash + +src=$1 +dest=$2 + +mkdir -p $(dirname $dest) + +case $dest in + *.[13]) + ronn --roff $1 --pipe --organization=1602\ Software --manual=CompoundJS > $2 + exit $? + ;; + + *.html) + ronn -5 $1 --pipe\ + --style=toc\ + --organization=1602\ Software\ + --manual=CompoundJS > $2 + exit $? + ;; +esac From 09831fd5b08aa75197428174f30a713d23a7813f Mon Sep 17 00:00:00 2001 From: Anatoliy Chakkaev Date: Wed, 20 Mar 2013 15:09:27 +0400 Subject: [PATCH 2/6] Describe man/html rules in Makefile --- Makefile | 53 +++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 47 insertions(+), 6 deletions(-) diff --git a/Makefile b/Makefile index f73d910..9a1ecfc 100644 --- a/Makefile +++ b/Makefile @@ -1,14 +1,55 @@ +# TESTS + +TESTER = ./node_modules/.bin/mocha +OPTS = --require ./test/init.js +TESTS = test/*.test.js + test: - @./node_modules/.bin/mocha --require ./test/init.js test/*.test.js + $(TESTER) $(OPTS) $(TESTS) test-verbose: - @./node_modules/.bin/mocha --reporter spec --require ./test/init.js test/*.test.js + $(TESTER) $(OPTS) --reporter spec $(TESTS) testing: - ./node_modules/.bin/mocha --watch --reporter min --require ./test/init.js --require should test/*.test.js + $(TESTER) $(OPTS) --watch $(TESTS) + +# MAN DOCS + +CLI_MAN = $(shell find docs/cli -name '*.md' \ + |sed 's|.md|.1|g' \ + |sed 's|docs/cli/|man/man1/|g' ) + +API_MAN = $(shell find docs/api -name '*.md' \ + |sed 's|.md|.3|g' \ + |sed 's|docs/api/|man/man3/|g' ) + +API_WEB = $(shell find docs/api -name '*.md' \ + |sed 's|.md|.html|g' \ + |sed 's|docs/api/|man/html/|g' ) + +man/man1/%.1: docs/cli/%.md scripts/doc.sh + @[ -d man/man1 ] || mkdir -p man/man1 + scripts/doc.sh $< $@ + +man/man3/%.3: docs/api/%.md scripts/doc.sh + @[ -d man/man3 ] || mkdir -p man/man3 + scripts/doc.sh $< $@ + +man/html/%.html: docs/api/%.md scripts/doc.sh + @[ -d man/man3 ] || mkdir -p man/man3 + scripts/doc.sh $< $@ + +MAN = $(API_MAN) $(CLI_MAN) + +build: all + +all: $(MAN) $(API_WEB) + +man: $(MAN) + +# WEBSITE DOCS + docs: node docs/sources/build apidocs: makedoc lib/*.js lib/*/*.js -t "RailwayJS API docs" -g "1602/express-on-railway" --assets -.PHONY: test -.PHONY: doc -.PHONY: docs +.PHONY: test doc docs From 9a9e8be10ebbb53e88df51121b60fda8839a139d Mon Sep 17 00:00:00 2001 From: Anatoliy Chakkaev Date: Wed, 20 Mar 2013 15:09:48 +0400 Subject: [PATCH 3/6] Route compound help to man --- bin/compound.js | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/bin/compound.js b/bin/compound.js index ff2cc66..9ecfae1 100755 --- a/bin/compound.js +++ b/bin/compound.js @@ -46,12 +46,17 @@ process.nextTick(function () { break; } } + var topic = args.shift(); + if (topic) { + showMan(topic); + return; + } var help = [ 'Usage: compound command [argument(s)]\n', 'Commands:' ]; var commands = [ - ['h', 'help', 'Display usage information'], + ['h', 'help [topic]', 'Display compound man page'], ['i', 'init', 'Initialize compound app'], ['g', 'generate [smth]', 'Generate something awesome'] ]; @@ -102,4 +107,16 @@ process.nextTick(function () { }); +function showMan(topic) { + var manDir = require('path').resolve(__dirname + '/../man/man3'); + require('child_process').spawn( + 'man', [manDir + '/' + topic + '.3'], + { + customFds: [0, 1, 2], + env: process.env, + cwd: process.cwd() + } + ); +} + /*vim ft:javascript*/ From e4db5113f652c2f31a0d99fe71002ebd3cf6a6bc Mon Sep 17 00:00:00 2001 From: Anatoliy Chakkaev Date: Wed, 20 Mar 2013 15:12:15 +0400 Subject: [PATCH 4/6] Added some docs --- docs/api/helpers.md | 74 +++++++++ docs/api/index.txt | 2 + docs/api/routing.md | 374 +++++++++++++++++++++++++++++++++++++++++++ docs/cli/compound.md | 39 +++++ 4 files changed, 489 insertions(+) create mode 100644 docs/api/helpers.md create mode 100644 docs/api/index.txt create mode 100644 docs/api/routing.md create mode 100644 docs/cli/compound.md diff --git a/docs/api/helpers.md b/docs/api/helpers.md new file mode 100644 index 0000000..1b331bb --- /dev/null +++ b/docs/api/helpers.md @@ -0,0 +1,74 @@ +compound-helpers(3) - view helpers +================================== + +## DESCRIPTION + +Helpers produce html code. [Built-in][BUILT-IN HELPERS] helpers available in any +view. Custom helpers available in specific controller, see [CUSTOM HELPERS][] +section. + +## BUILT-IN HELPERS + +### stylesheetLinkTag(file1[, file2[, ...[, fileN]]]) + +Generates `` tag. +Following ejs: + + <%- stylesheetLinkTag('reset', 'style', 'mobile') %> + +will produce in develompent env: + + + + + +and in production env: + + + +depending on `app.set('merge stylesheets');` option. + +### javascriptIncludeTag +### linkTo +### contentFor +### anchor +### matcher +### icon +### imageTag +### csrfTag +### csrfMetaTag +### metaTag +### formFor +### fieldsFor +### errorMessagesFor +### formTag +### formTagBegin +### formTagEnd +### labelTag +### submitTag +### buttonTag +### selectTag +### optionTag + +## FORM HELPERS + +### begin +### end +### label +### select +### input +### file +### textarea +### checkbox +### submit + +## CUSTOM HELPERS + +There are two kind of custom helpers: application-wide and local. To define +custom helpers create *./app/helpers/application_helper.js* file. Local helpers +available only for specific controller, and should be located in +*./app/helpers/controllerName_helper.js* file. + +## SEE ALSO + +routing(3) diff --git a/docs/api/index.txt b/docs/api/index.txt new file mode 100644 index 0000000..57ec7b1 --- /dev/null +++ b/docs/api/index.txt @@ -0,0 +1,2 @@ +# manuals +routing(3) routing diff --git a/docs/api/routing.md b/docs/api/routing.md new file mode 100644 index 0000000..7fa4fdc --- /dev/null +++ b/docs/api/routing.md @@ -0,0 +1,374 @@ +compound-routing(3) - compound map drawer +========================================= + +## DESCRIPTION + +The purpose of routes is to connect an URL with a controller action. + +## FILE + +`config/routes.js` should export `routes(map)` function: + + exports.routes = function draw(map) { + map.root('dashboard#home'); + map.namespace('admin', function(admin) { + admin.resources('users'); + }); + }; + +## EVENT + +You can use `routes` event on compound object to define routes: + + compound.on('routes', function(map, compound) { + map.get('auth', 'session#auth'); + }); + +It could be useful when you want to define some routes before application +initialization. When app initialized use `compound.map` object. + +## BASIC ROUTING METHODS + +To define routes we have map object which have number of methods: + +* `get`: + Define route for GET method. + +* `post`: + Define route for POST method. + +* `put`: + Define route for PUT method. + +* `del`: + Define route for DELETE method. + +* `all`: + Define route for all http methods. + +All these methods have following signature: + + map.get(path, handler, middleware, options); + +Params meaning: + +* `path`: + some path, which could contain params, see [ROUTE PATH PARAMS][] + +* `handler`: + string `controllerName#actionName` + +* `middleware`: + function or array of functions (optional) + +* `options`: + object containing params for route (optional), see [ROUTE OPTIONS][] + +## ADVANCED ROUTING METHODS + +### NAMESPACE + +### RESOURCE + +## ROUTE PATH PARAMS + +TODO + +## ROUTE OPTIONS + +TODO + +## EXAMPLES + +To link `GET /signup` with `new` action of `users` controller: + +`map.get('signup', 'users#new');` + +The following route will link `GET /` to the `index` action of the`home` controller: + +`map.root('home#index');` + +## URL HELPERS + +URL helpers provide you convenient way to work with paths in your app. When you +define route: + + map.get('bunny', 'bunny#show'); + +you can use `pathTo.bunny` in your controllers and views, which will generate + + /bunny + +path for you. You also can specify another helper name is you want using `as` +param: + + map.get('bunny', 'bunny#show', {as: 'rabbit'}); + +and now `pathTo.rabbit` available. + +If your route has param, for example + + map.get('profile/:user', 'users#show'); + map.get('posts/:post_id/comments/:comment_id', 'comments#show'); + +URL helper will accept parameter (String), so that: + + pathTo.profile('Bugs_Bunny', 'users#show'); + > '/profile/Bugs_Bunny' + pathTo.post_comment(2, 2383); + > '/posts/2/comments/2383' + +

+Why use URL helpers?
+First of all it's convenient and beauty. But what is more important +url helpers take care about namespaces. In case if your application will be +used as part of another application, mounted on some URL like "/foreign-app" +URL helpers will return correct value: "/foreign-app/profile/Bugs_Bunny" +instead of "/profile/Bugs_Bunny" +

+ +How to learn what helper name was generated? Read "Debugging" section. + +## Debugging + +To debug routes of your compound application you can use `compound routes` +command (or shortcut `compound r`). You can also specify optional argument for +filtering by helper name or method, for example: + +``` +~: ) compound r post + posts GET /posts.:format? posts#index + posts POST /posts.:format? posts#create + new_post GET /posts/new.:format? posts#new + edit_post GET /posts/:id/edit.:format? posts#edit + post DELETE /posts/:id.:format? posts#destroy + post PUT /posts/:id.:format? posts#update + post GET /posts/:id.:format? posts#show +~: ) compound r GET + posts GET /posts.:format? posts#index + new_post GET /posts/new.:format? posts#new + edit_post GET /posts/:id/edit.:format? posts#edit + post GET /posts/:id.:format? posts#show +~: ) compound r new + new_post GET /posts/new.:format? posts#new +``` + +## Resources + +Resource-based routing provides standard mapping between HTTP verbs and controller actions: + +``` +map.resources('posts'); +``` + +will provide the following routes: + +``` + helper | method | path | controller#action + posts GET /posts posts#index + posts POST /posts posts#create + new_post GET /posts/new posts#new +edit_post GET /posts/:id/edit posts#edit + post DELETE /posts/:id posts#destroy + post PUT /posts/:id posts#update + post GET /posts/:id posts#show. +``` + +To list all available routes you can run the command `compound routes`. + +The first column of the table represents the `helper` - you can use this identifier in views and controllers to get the route. Some examples: + +``` +path_to.new_post # /posts/new +path_to.edit_post(1) # /posts/1/edit +path_to.edit_post(post) # /posts/1/edit (in this example post = {id: 1}) +path_to.posts # /posts +path_to.post(post) # /posts/1. + +``` + +### Options + +If you want to override default routes behaviour, you can use two options: `as` and `path` to specify a helper name and a path you want to have in the result. + + +{ as: 'helperName' } + + +Path helper aliasing: + +``` +map.resources('posts', { as: 'articles' }); +``` + +This will create the following routes: + +``` + articles GET /posts.:format? posts#index + articles POST /posts.:format? posts#create + new_article GET /posts/new.:format? posts#new +edit_article GET /posts/:id/edit.:format? posts#edit + article DELETE /posts/:id.:format? posts#destroy + article PUT /posts/:id.:format? posts#update + article GET /posts/:id.:format? posts#show. +``` + + +{ path: 'alternatePath' } + + +If you want to change the base path: + +``` +map.resources('posts', { path: 'articles' }); +``` + +This will create the following routes: + +``` + posts GET /articles.:format? posts#index + posts POST /articles.:format? posts#create + new_post GET /articles/new.:format? posts#new +edit_post GET /articles/:id/edit.:format? posts#edit + post DELETE /articles/:id.:format? posts#destroy + post PUT /articles/:id.:format? posts#update + post GET /articles/:id.:format? posts#show +``` + + +Both "as" and "path" together + + +If you want to alias both the helper and the path: + +``` +map.resources('posts', { path: 'articles', as: 'stories' }); +``` + +This will create the following routes: + +``` + stories GET /articles.:format? posts#index + stories POST /articles.:format? posts#create + new_story GET /articles/new.:format? posts#new +edit_story GET /articles/:id/edit.:format? posts#edit + story DELETE /articles/:id.:format? posts#destroy + story PUT /articles/:id.:format? posts#update + story GET /articles/:id.:format? posts#show +``` + +## Nested resources + +Some resources may have nested sub-resources, for example `Post` has many `Comments`, and of course we want to get a post's comments using `GET /post/1/comments`. + +Let's describe the route for our nested resource: + +``` +map.resources('post', function (post) { + post.resources('comments'); +});. +``` + +This routing map will provide the following routes: + +``` +$ compound routes + post_comments GET /posts/:post_id/comments comments#index + post_comments POST /posts/:post_id/comments comments#create + new_post_comment GET /posts/:post_id/comments/new comments#new + edit_post_comment GET /posts/:post_id/comments/:id/edit comments#edit + post_comment DELETE /posts/:post_id/comments/:id comments#destroy + post_comment PUT /posts/:post_id/comments/:id comments#update + post_comment GET /posts/:post_id/comments/:id comments#show + posts GET /posts posts#index + posts POST /posts posts#create + new_post GET /posts/new posts#new + edit_post GET /posts/:id/edit posts#edit + post DELETE /posts/:id posts#destroy + post PUT /posts/:id posts#update + post GET /posts/:id posts#show. +``` + +### Using url helpers for nested routes + +To use routes like `post_comments` you should call helper with param: parent resource or identifier before nested resource: + +``` +path_to.post_comments(post) # /posts/1/comments +path_to.edit_post_comment(post, comment) # /posts/1/comments/10/edit +path_to.edit_post_comment(2, 300) # /posts/2/comments/300/edit +``` + +## Namespaces + +You may wish to organize groups of controllers under a namespace. The most common use-case is an administration area. All controllers within the `admin` namespace should be located inside the `app/controllers/` directory. + +For example, let's create an admin namespace: + +``` +map.namespace('admin', function (admin) { + admin.resources('users'); +}); +``` + +This routing rule will match with `/admin/users`, `/admin/users/new` and will create appropriate url helpers: + +``` + admin_users GET /admin/users.:format? admin/users#index + admin_users POST /admin/users.:format? admin/users#create + new_admin_user GET /admin/users/new.:format? admin/users#new +edit_admin_user GET /admin/users/:id/edit.:format? admin/users#edit + admin_user DELETE /admin/users/:id.:format? admin/users#destroy + admin_user PUT /admin/users/:id.:format? admin/users#update + admin_user GET /admin/users/:id.:format? admin/users#show +``` + +## Restricting routes + +If you need routes only for several actions (e.g. `index`, `show`), you can specify the `only` option: + +``` +map.resources('users', { only: ['index', 'show'] }); +``` + +If you want to have all routes except a specific route, you can specify the `except` option: + +``` +map.resources('users', { except: ['create', 'destroy'] }); +``` + +## Custom actions in resourceful routes + +If you need some specific action to be added to your resource-based route, use this example: + +``` +map.resource('users', function (user) { + user.get('avatar', 'users#avatar'); // /users/:user_id/avatar + user.get('top', 'users#top', {collection: true}); // /users/top +}); +``` + +## Middleware + +You may want to use middleware in routes. It's not recommended, but if you need +it you can put it as second argument: + +``` +map.get('/admin', authenticate, 'admin#index'); +map.get('/protected/resource', [ middleware1, middleware2 ], 'resource#access'); +``` + +## Subdomain + +**experimental** + +If you want to support subdomain filter, specify it as `subdomain` option: + + map.get('/url', 'ctl#action', {subdomain: 'subdomain.tld'}); + +use \* as wildcard domain + + map.get('/url', 'ctl#action', {subdomain: '*.example.com'}); + +This feature relies on `host` header, if your node process behind nginx or proxy, +make sure you've passed this header to process. diff --git a/docs/cli/compound.md b/docs/cli/compound.md new file mode 100644 index 0000000..7a3a769 --- /dev/null +++ b/docs/cli/compound.md @@ -0,0 +1,39 @@ +compound(1) -- MVC framework for NodeJS +======================================= + +## SYNOPSIS + + compound [args] [opts] + +## DESCRIPTION + +Compound is MVC framework for the Node JavaScript platform. It adds structure +and API to ExpressJS application, provides tools and generators for rapid +web applications development. + +Run `compound help [topic]` to get help on specific topic. + +## BUGS + +When you find issues, please report them: + +* web: + +* email: + + +## HISTORY + +See compound-changelog(1) + +## AUTHOR + +* [Anatoliy Chakkaev](http://anatoliy.in/) +* [1602](https://github.com/1602/) +* [anatoliychakkaev](https://github.com/anatoliychakkaev/) +* [@1602](http://twitter.com/1602) +* + +## SEE ALSO + +compound(3) From 41476f50e6ccec546237b968fc7ca9a6e957edd4 Mon Sep 17 00:00:00 2001 From: Anatoliy Chakkaev Date: Wed, 20 Mar 2013 15:21:06 +0400 Subject: [PATCH 5/6] Indent sources --- docs/api/routing.md | 210 ++++++++++++++++++-------------------------- 1 file changed, 87 insertions(+), 123 deletions(-) diff --git a/docs/api/routing.md b/docs/api/routing.md index 7fa4fdc..1446737 100644 --- a/docs/api/routing.md +++ b/docs/api/routing.md @@ -135,44 +135,38 @@ To debug routes of your compound application you can use `compound routes` command (or shortcut `compound r`). You can also specify optional argument for filtering by helper name or method, for example: -``` -~: ) compound r post - posts GET /posts.:format? posts#index - posts POST /posts.:format? posts#create - new_post GET /posts/new.:format? posts#new - edit_post GET /posts/:id/edit.:format? posts#edit - post DELETE /posts/:id.:format? posts#destroy - post PUT /posts/:id.:format? posts#update - post GET /posts/:id.:format? posts#show -~: ) compound r GET - posts GET /posts.:format? posts#index - new_post GET /posts/new.:format? posts#new - edit_post GET /posts/:id/edit.:format? posts#edit - post GET /posts/:id.:format? posts#show -~: ) compound r new - new_post GET /posts/new.:format? posts#new -``` + ~: ) compound r post + posts GET /posts.:format? posts#index + posts POST /posts.:format? posts#create + new_post GET /posts/new.:format? posts#new + edit_post GET /posts/:id/edit.:format? posts#edit + post DELETE /posts/:id.:format? posts#destroy + post PUT /posts/:id.:format? posts#update + post GET /posts/:id.:format? posts#show + ~: ) compound r GET + posts GET /posts.:format? posts#index + new_post GET /posts/new.:format? posts#new + edit_post GET /posts/:id/edit.:format? posts#edit + post GET /posts/:id.:format? posts#show + ~: ) compound r new + new_post GET /posts/new.:format? posts#new ## Resources Resource-based routing provides standard mapping between HTTP verbs and controller actions: -``` -map.resources('posts'); -``` + map.resources('posts'); will provide the following routes: -``` - helper | method | path | controller#action - posts GET /posts posts#index - posts POST /posts posts#create - new_post GET /posts/new posts#new -edit_post GET /posts/:id/edit posts#edit - post DELETE /posts/:id posts#destroy - post PUT /posts/:id posts#update - post GET /posts/:id posts#show. -``` + helper | method | path | controller#action + posts GET /posts posts#index + posts POST /posts posts#create + new_post GET /posts/new posts#new + edit_post GET /posts/:id/edit posts#edit + post DELETE /posts/:id posts#destroy + post PUT /posts/:id posts#update + post GET /posts/:id posts#show. To list all available routes you can run the command `compound routes`. @@ -197,21 +191,17 @@ If you want to override default routes behaviour, you can use two options: `as` Path helper aliasing: -``` -map.resources('posts', { as: 'articles' }); -``` + map.resources('posts', { as: 'articles' }); This will create the following routes: -``` - articles GET /posts.:format? posts#index - articles POST /posts.:format? posts#create - new_article GET /posts/new.:format? posts#new -edit_article GET /posts/:id/edit.:format? posts#edit - article DELETE /posts/:id.:format? posts#destroy - article PUT /posts/:id.:format? posts#update - article GET /posts/:id.:format? posts#show. -``` + articles GET /posts.:format? posts#index + articles POST /posts.:format? posts#create + new_article GET /posts/new.:format? posts#new + edit_article GET /posts/:id/edit.:format? posts#edit + article DELETE /posts/:id.:format? posts#destroy + article PUT /posts/:id.:format? posts#update + article GET /posts/:id.:format? posts#show. { path: 'alternatePath' } @@ -219,21 +209,17 @@ edit_article GET /posts/:id/edit.:format? posts#edit If you want to change the base path: -``` -map.resources('posts', { path: 'articles' }); -``` + map.resources('posts', { path: 'articles' }); This will create the following routes: -``` - posts GET /articles.:format? posts#index - posts POST /articles.:format? posts#create - new_post GET /articles/new.:format? posts#new -edit_post GET /articles/:id/edit.:format? posts#edit - post DELETE /articles/:id.:format? posts#destroy - post PUT /articles/:id.:format? posts#update - post GET /articles/:id.:format? posts#show -``` + posts GET /articles.:format? posts#index + posts POST /articles.:format? posts#create + new_post GET /articles/new.:format? posts#new + edit_post GET /articles/:id/edit.:format? posts#edit + post DELETE /articles/:id.:format? posts#destroy + post PUT /articles/:id.:format? posts#update + post GET /articles/:id.:format? posts#show Both "as" and "path" together @@ -241,21 +227,17 @@ Both "as" and "path" together If you want to alias both the helper and the path: -``` -map.resources('posts', { path: 'articles', as: 'stories' }); -``` + map.resources('posts', { path: 'articles', as: 'stories' }); This will create the following routes: -``` - stories GET /articles.:format? posts#index - stories POST /articles.:format? posts#create - new_story GET /articles/new.:format? posts#new -edit_story GET /articles/:id/edit.:format? posts#edit - story DELETE /articles/:id.:format? posts#destroy - story PUT /articles/:id.:format? posts#update - story GET /articles/:id.:format? posts#show -``` + stories GET /articles.:format? posts#index + stories POST /articles.:format? posts#create + new_story GET /articles/new.:format? posts#new + edit_story GET /articles/:id/edit.:format? posts#edit + story DELETE /articles/:id.:format? posts#destroy + story PUT /articles/:id.:format? posts#update + story GET /articles/:id.:format? posts#show ## Nested resources @@ -263,41 +245,35 @@ Some resources may have nested sub-resources, for example `Post` has many `Comme Let's describe the route for our nested resource: -``` -map.resources('post', function (post) { - post.resources('comments'); -});. -``` + map.resources('post', function (post) { + post.resources('comments'); + });. This routing map will provide the following routes: -``` -$ compound routes - post_comments GET /posts/:post_id/comments comments#index - post_comments POST /posts/:post_id/comments comments#create - new_post_comment GET /posts/:post_id/comments/new comments#new - edit_post_comment GET /posts/:post_id/comments/:id/edit comments#edit - post_comment DELETE /posts/:post_id/comments/:id comments#destroy - post_comment PUT /posts/:post_id/comments/:id comments#update - post_comment GET /posts/:post_id/comments/:id comments#show - posts GET /posts posts#index - posts POST /posts posts#create - new_post GET /posts/new posts#new - edit_post GET /posts/:id/edit posts#edit - post DELETE /posts/:id posts#destroy - post PUT /posts/:id posts#update - post GET /posts/:id posts#show. -``` + $ compound routes + post_comments GET /posts/:post_id/comments comments#index + post_comments POST /posts/:post_id/comments comments#create + new_post_comment GET /posts/:post_id/comments/new comments#new + edit_post_comment GET /posts/:post_id/comments/:id/edit comments#edit + post_comment DELETE /posts/:post_id/comments/:id comments#destroy + post_comment PUT /posts/:post_id/comments/:id comments#update + post_comment GET /posts/:post_id/comments/:id comments#show + posts GET /posts posts#index + posts POST /posts posts#create + new_post GET /posts/new posts#new + edit_post GET /posts/:id/edit posts#edit + post DELETE /posts/:id posts#destroy + post PUT /posts/:id posts#update + post GET /posts/:id posts#show. ### Using url helpers for nested routes To use routes like `post_comments` you should call helper with param: parent resource or identifier before nested resource: -``` -path_to.post_comments(post) # /posts/1/comments -path_to.edit_post_comment(post, comment) # /posts/1/comments/10/edit -path_to.edit_post_comment(2, 300) # /posts/2/comments/300/edit -``` + path_to.post_comments(post) # /posts/1/comments + path_to.edit_post_comment(post, comment) # /posts/1/comments/10/edit + path_to.edit_post_comment(2, 300) # /posts/2/comments/300/edit ## Namespaces @@ -305,58 +281,46 @@ You may wish to organize groups of controllers under a namespace. The most commo For example, let's create an admin namespace: -``` -map.namespace('admin', function (admin) { - admin.resources('users'); -}); -``` + map.namespace('admin', function (admin) { + admin.resources('users'); + }); This routing rule will match with `/admin/users`, `/admin/users/new` and will create appropriate url helpers: -``` - admin_users GET /admin/users.:format? admin/users#index - admin_users POST /admin/users.:format? admin/users#create - new_admin_user GET /admin/users/new.:format? admin/users#new -edit_admin_user GET /admin/users/:id/edit.:format? admin/users#edit - admin_user DELETE /admin/users/:id.:format? admin/users#destroy - admin_user PUT /admin/users/:id.:format? admin/users#update - admin_user GET /admin/users/:id.:format? admin/users#show -``` + admin_users GET /admin/users.:format? admin/users#index + admin_users POST /admin/users.:format? admin/users#create + new_admin_user GET /admin/users/new.:format? admin/users#new + edit_admin_user GET /admin/users/:id/edit.:format? admin/users#edit + admin_user DELETE /admin/users/:id.:format? admin/users#destroy + admin_user PUT /admin/users/:id.:format? admin/users#update + admin_user GET /admin/users/:id.:format? admin/users#show ## Restricting routes If you need routes only for several actions (e.g. `index`, `show`), you can specify the `only` option: -``` -map.resources('users', { only: ['index', 'show'] }); -``` + map.resources('users', { only: ['index', 'show'] }); If you want to have all routes except a specific route, you can specify the `except` option: -``` -map.resources('users', { except: ['create', 'destroy'] }); -``` + map.resources('users', { except: ['create', 'destroy'] }); ## Custom actions in resourceful routes If you need some specific action to be added to your resource-based route, use this example: -``` -map.resource('users', function (user) { - user.get('avatar', 'users#avatar'); // /users/:user_id/avatar - user.get('top', 'users#top', {collection: true}); // /users/top -}); -``` + map.resource('users', function (user) { + user.get('avatar', 'users#avatar'); // /users/:user_id/avatar + user.get('top', 'users#top', {collection: true}); // /users/top + }); ## Middleware You may want to use middleware in routes. It's not recommended, but if you need it you can put it as second argument: -``` -map.get('/admin', authenticate, 'admin#index'); -map.get('/protected/resource', [ middleware1, middleware2 ], 'resource#access'); -``` + map.get('/admin', authenticate, 'admin#index'); + map.get('/protected/resource', [ middleware1, middleware2 ], 'resource#access'); ## Subdomain From 604582795e5cef6940545696697c611ee5022231 Mon Sep 17 00:00:00 2001 From: Anatoliy Chakkaev Date: Wed, 20 Mar 2013 15:22:32 +0400 Subject: [PATCH 6/6] Amend man structure --- .gitignore | 1 + Makefile | 14 +++++++------- package.json | 9 ++++++++- 3 files changed, 16 insertions(+), 8 deletions(-) diff --git a/.gitignore b/.gitignore index 1889252..70570f8 100644 --- a/.gitignore +++ b/.gitignore @@ -10,3 +10,4 @@ log/test.log analyse-ab.r log tags.sh +man diff --git a/Makefile b/Makefile index 9a1ecfc..2d59610 100644 --- a/Makefile +++ b/Makefile @@ -15,26 +15,26 @@ testing: CLI_MAN = $(shell find docs/cli -name '*.md' \ |sed 's|.md|.1|g' \ - |sed 's|docs/cli/|man/man1/|g' ) + |sed 's|docs/cli/|man/|g' ) API_MAN = $(shell find docs/api -name '*.md' \ |sed 's|.md|.3|g' \ - |sed 's|docs/api/|man/man3/|g' ) + |sed 's|docs/api/|man/|g' ) API_WEB = $(shell find docs/api -name '*.md' \ |sed 's|.md|.html|g' \ |sed 's|docs/api/|man/html/|g' ) -man/man1/%.1: docs/cli/%.md scripts/doc.sh - @[ -d man/man1 ] || mkdir -p man/man1 +man/%.1: docs/cli/%.md scripts/doc.sh + @[ -d man ] || mkdir man scripts/doc.sh $< $@ -man/man3/%.3: docs/api/%.md scripts/doc.sh - @[ -d man/man3 ] || mkdir -p man/man3 +man/%.3: docs/api/%.md scripts/doc.sh + @[ -d man ] || mkdir man scripts/doc.sh $< $@ man/html/%.html: docs/api/%.md scripts/doc.sh - @[ -d man/man3 ] || mkdir -p man/man3 + @[ -d man/html ] || mkdir -p man/html scripts/doc.sh $< $@ MAN = $(API_MAN) $(CLI_MAN) diff --git a/package.json b/package.json index 52971ec..6da7baa 100644 --- a/package.json +++ b/package.json @@ -3,6 +3,7 @@ "version": "1.1.5-18", "author": "Anatoliy Chakkaev", "contributors": [ + "Anatoliy Chakkaev (http://anatoliy.in)", "Sascha Gehlich (http://filshmedia.net)" ], "description": "CompoundJS - MVC framework for NodeJS", @@ -23,6 +24,11 @@ "compound": "bin/compound.js", "rw": "bin/compound.js" }, + "man": [ + "./man/compound.1", + "./man/helpers.3", + "./man/routing.3" + ], "dependencies": { "yaml-js": ">= 0.0.2", "coffee-script": ">= 1.1.1", @@ -46,6 +52,7 @@ "mocha": "1.8.1" }, "scripts": { - "test": "make test" + "test": "make test", + "prepublish": "make build" } }