Mongoose Slug Hero is a mongoose plugin to generate unique sequential slug. This plugin uses node-slug module to generate slug from targeted field. To guarantee the uniqueness, this plugin uses sequence collection to track the number of used slug -- inspired by mongoose-sequence plugin.
Generated slug stored in your collection in field named slug
.
When you edit your data the slug will be automatically changed based to the new updated data.
But the old slug still alive. Thus we respect this history by storing the old slug to the
slugs
field in your target collection.
Slugs that belongs to deleted data will also not reused.
This plugin automatically create static method for your schema called findBySlug
.
You can find your data by invoking this method by supplying whether the current slug or old slug.
npm install mongoose-slug-hero
- doc (required): Name of slug-hero, this must be unique among collections. You can fill with the model name to make life easier.
- field (required): Name of your field that slug will generate for.
- scope (optional): Array of field names for scope keys (see example: Scoped Slug).
- slugField (optional / global): The slug field name that will be added to the collection to store generated slug. Default:
slug
. - slugsField (optional / global): The slugs field name that will be added to the collection to store slug history. Default:
slugs
. - slugOptions (optional / global): Options for node-slug. Please refer to https://github.com/dodo/node-slug#options. Default:
{lower: true}
. - counter (optional / global): The name of collection to store sequences data. Default:
_slug_ctrs
.
You can set those options above marked with global once for all in the very begining of your code.
For example you want to always use slug_counters
as your collection to store sequences, then you do this:
var slugHero = require('mongoose-slug-hero');
slugHero.config.counter = 'slug_counters'
// You can do same thing for slugField, slugsField or slugOptions
var slugHero = require('mongoose-slug-hero'),
mongoose = require('mongoose'),
fooSchema = new mongoose.Schema({
name: String
});
fooSchema.plugin(slugHero, {doc: 'foo', field: 'name'});
var Foo = mongoose.model('Foo', fooSchema);
var foo = new Foo({ name: 'SpongeBob' });
foo.save(); // foo.slug => 'spongebob'
Next time you create another Foo
var foo = new Foo({ name: 'SpongeBob' });
foo.save(); // foo.slug => 'spongebob-2'
It is like a composite key, that slug should be unique within same referenced key. For example that each user's post should be only unique according to the user:
var postSchema = new mongoose.Schema({userId: Number, post: String});
postSchema.plugin(slugHero, {doc: 'post', field: 'post', scope:['userId']});
var Post = mongoose.model('Post', postSchema);
// create 1st post
(new Post({userId: 1, post: 'Great post ever'})).save(); // post.slug => 'great-post-ever'
// secondly with same user and same post...
(new Post({userId: 1, post: 'Great post ever'})).save(); // post.slug => 'great-post-ever-2'
// now with different user and same post...
(new Post({userId: 2, post: 'Great post ever'})).save(); // post.slug => 'great-post-ever'
// and so on...
findBySlug method returning mongoose query, except that the parameter is slug itself. So you can do mongoose query syntax like here.
Either <Model>.findBySlug(<slug_or_options>, [callbak]);
or <Model>.findBySlug(<slug_or_options>).exec([callbak]);
Example:
Post.findBySlug('great-post-ever', function(err, result) {
// 'result' is what we looking for
});
or
Post.findBySlug('great-post-ever').exec(function(err, result) {
// 'result' is what we looking for
});
For scoped slug, you can feed first parameter with an object instead of slug.
For example you want to find data belongs to userId
with value 1
:
Post.findBySlug({slug: 'great-post-ever', userId: 1}).exec(function(err, result) {
// 'result' is what we looking for
});
You can call ensureSlugIsExists method to generate slug into existing document. For example you have a schema and model like this:
var schema = new mongoose.Schema({
name: String
})
var MyModel = mongoose.model('MyModel', schema)
Then you release your app and of course MyModel
now filled with many data.
Now you change your mind, that you want to have a slug to your MyModel
. All you have to do is:
- Change your schema to have
mongoose-slug-hero
plugged.schema.plugin(slugHero, {doc: 'my-model', field: 'name'})
- Call ensureSlugIsExists right after model initialization:
MyModel.ensureSlugIsExists(function (error) { if (error) { throw error } console.log('success!') })