mirror of https://github.com/jo/docuri.git
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.
136 lines
3.7 KiB
Markdown
136 lines
3.7 KiB
Markdown
# DocURI [](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.
|
|
|