You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
docuri/README.md

136 lines
3.7 KiB
Markdown

# DocURI [![Build Status](https://travis-ci.org/jo/docuri.svg?branch=master)](https://travis-ci.org/jo/docuri)
Rich document ids for CouchDB:
```js
'movie/blade-runner/gallery-image/12/medium'
```
### Advantages
* You can access the doc type everywhere (eg. in changes feed, response, view results...)
* They sort well in Futon and` _all_docs`
* DocURIs can tell a lot about the document
* You can rely on a schema and construct ids of dependend documents (eg. a specific version of an image)
* Easily delete related documents (eg. by requesting a range from `_all_docs`)
_Give DocURIs a try!_
## Usage
Define methods for certain DocURI fragments and provide a routes hash that pairs routes to methods.
DocURI is inspired by [Backbone.Router](http://backbonejs.org/#Router).
Routes can contain parameter parts, `:param`, which match a single DocURI component
between slashes; and splat parts `*splat`, which can match any number of DocURI
components. Part of a route can be made optional by surrounding it in
parentheses `(/:optional)`.
For example, a route of `'movie/:movie_id/gallery-image'` will generate a function which parses
```js
'movie/blade-runner/gallery-image/12'
// =>
{
movie_id: 'blade-runner',
id: '12'
}
```
and vice versa.
A route of `'movie/:movie_id/:type/*path'` will generate a function which parses
```js
'movie/blade-runner/gallery-image/12'
// =>
{
movie_id: 'blade-runner',
type: 'gallery-image',
path: ['12']
}
// and
'movie/blade-runner/gallery-image/12/medium'
// =>
{
movie_id: 'blade-runner',
type: 'gallery-image',
path: ['12', 'medium']
}
```
The route `'movie/:movie_id/gallery-image/:id(/:version)'` will generate a
function which parses
```js
'movie/blade-runner/gallery-image/12'
// =>
{
movie_id: 'blade-runner',
id: '12'
}
// as well as
'movie/blade-runner/gallery-image/12/medium'
// =>
{
movie_id: 'blade-runner',
id: '12',
version: 'medium'
}
```
### `docuri.route(route, name)`
Create a single route. The `route` argument must be a routing string. The
`name` argument will be the identifier for the resulting function:
`docuri[name]`. Routes added later may override previously declared routes.
```js
// parses 'page/home' as { id: 'home' }:
docuri.route('page/:id', 'page');
```
### `docuri.routes(map)`
Install a routes hash which maps DocURIs with parameters to functions:
```js
docuri.routes({
'movie/:id': 'movie',
'movie/:movie_id/:type/*path': 'movieAsset'
'movie/:movie_id/gallery-image/:id(/:version)': 'galleryImage',
});
```
### `docuri[name](strOrObj, [obj])`
The functions generated by DocURI can have a different behaviour, depending on
the type and number of the supplied arguments:
* `name(str)`: parse DocURI string to object
* `name(obj)`: generate DocURI string from object
* `name(str, obj)`: change DocURI string parts with values provided by object returning a string
The function returns `false` if a string can not be parsed, enabling type
checks.
#### Example
```js
docuri.movie('movie/blade-runner');
// { id: 'blade-runner' }
docuri.movieAsset('movie/blade-runner');
// false
docuri.galleryImage({ movie_id: 'blade-runner', id: 12 });
// 'movie/blade-runner/gallery-image/12'
docuri.galleryImage('movie/blade-runner/gallery-image/12', { version: 'large' });
// 'movie/blade-runner/gallery-image/12/large'
```
## Browser support
To use DocURI in your client-side application, browserify it like this:
```shell
browserify -s DocURI path/to/docuri/index.js > path/to/your/assets
```
Or grab it from [browserify-as-a-service: docuri@latest](http://www.modulefarm.com/standalone/docuri@latest).
## Development
To run the unit tests:
```shell
npm test
```
## License
Copyright (c) 2014 Johannes J. Schmidt, null2 GmbH
Licensed under the MIT license.