hwangc / meteor-friendly-slugs Goto Github PK

This package has two main purposes:

1. Make it easy to create a sanitized and URL friendly slug based off of an existing field
2. Auto-increment the slug if needed to ensure each item has a unique URL

• Automatically assign a URL friendly slug based on a field of your specification. The slug will be sanitized following these rules:
  • Uses all lowercase letters
  • Transliterates accented and other variants (see Transliteration)
  • Replace spaces with -
  • Removes apostrophes
  • Replace anything that is not 0-9, a-z, or - with -
  • Replace multiple - with single -
  • Trim - from start of text
  • Trim - from end of text
• Checks other items in the collection for the same slug, adds an auto-incrementing index to the end if needed. For example if a slug is based of a field who's value is "Foo Bar" and there is another item with the same value, the new slug will be 'foo-bar-1'.
• Can create slugs for multiple fields.
• Can optionally create a slug without the auto-incrementing index.
• Can optionally update a slug when the field it is based from is updated.
• Do all of these things efficiently, storing the base and index for a quick query

meteor add todda00:friendly-slugs

After you define your collection with something like:

Collection = new Mongo.Collection("collection");

You can call the friendlySlugs function a few different ways:

Collection.friendlySlugs();

This will look for a field named 'name' and create a slug field named 'slug'

Collection.friendlySlugs('name');

This will create a 'slug' field based off of the field you specify

Collection.friendlySlugs(
  {
    slugFrom: 'name',
    slugField: 'slug',
    distinct: true,
    updateSlug: true
  }
);

These are the default values, include what you would like to change

Collection.friendlySlugs([
  {
    slugFrom: 'name',
    slugField: 'slug',
  },
  {
    slugFrom: 'anotherField',
    slugField: 'slug2',
  }
]);

Each field specified will create a slug to the slug field specified.

This package does not extend iron router, you can select your items using normal means by querying the slugField. Here is an example in coffeescript:

@route "/collection/:slug",
  name:'collection'
  waitOn: ->
    @subscribe 'collection', @params.slug
  data: ->
    return Collection.findOne({slug:@params.slug})

The default settings transliterate characters with accents and other variations to the closest english ASCII alphanumeric equivelant. The conversion is customizable, so you can transliterate from any characters to any character(s).

The tranliteration setting can be set as such: (this example is the default usage, you don't need to add the option to get these results.) (coffeescript)

Collection.friendlySlugs
  transliteration: [
    {from: 'àáâäãа', to: 'a'}
    {from: 'б',      to: 'b'}
    {from: 'ç',      to: 'c'}
    {from: 'д',      to: 'd'}
    {from: 'èéêëẽэе',to: 'e'}
    {from: 'ф',      to: 'f'}
    {from: 'г',      to: 'g'}
    {from: 'х',      to: 'h'}
    {from: 'ìíîïи',  to: 'i'}
    {from: 'к',      to: 'k'}
    {from: 'л',      to: 'l'}
    {from: 'м',      to: 'm'}
    {from: 'ñн',     to: 'n'}
    {from: 'òóôöõо', to: 'o'}
    {from: 'п',      to: 'p'}
    {from: 'р',      to: 'r'}
    {from: 'с',      to: 's'}
    {from: 'т',      to: 't'}
    {from: 'ùúûüу',  to: 'u'}
    {from: 'в',      to: 'v'}
    {from: 'йы',     to: 'y'}
    {from: 'з',      to: 'z'}
    {from: 'æ',      to: 'ae'}
    {from: 'ч',      to: 'ch'}
    {from: 'щ',      to: 'sch'}
    {from: 'ш',      to: 'sh'}
    {from: 'ц',      to: 'ts'}
    {from: 'я',      to: 'ya'}
    {from: 'ю',      to: 'yu'}
    {from: 'ж',      to: 'zh'}
    {from: 'ъь',     to: ''}
  ]

"...Only alphanumerics [0-9a-zA-Z], the special characters "$-_.+!*'()," [not including the quotes - ed], and reserved characters used for their reserved purposes may be used unencoded within a URL."

For the slug part of the URL, we are only allowing a-z, 0-9, and - This keeps in accordance with RFC 1738 explained here in a more helpful way

Using the distinctUpTo option (which is relevant only if distinct = true) you can specify what fields need to match in order to cause the slug to increment the ID at the end.

Business case: The slug have to be distinct not for the whole collection but only for the given user. Example, we insert:

{title:'Title A', created_user_id:'U1' }
{title:'Title B', created_user_id:'U1' }
{title:'Title C', created_user_id:'U2' }
{title:'Title B', created_user_id:'U2' }
{title:'Title C', created_user_id:'U2' }

And the generated slugs are:

title-a
title-b
title-c
title-b
title-c-1

The url can then be formatted using the created_user_id as part of the URL:

http://.../:user/:slug

Multiple fields can be specified for more specific distinction.

Usage:

Collection.friendlySlugs(
  {
    slugFrom: 'name',
    slugField: 'slug',
    ...
    distinctUpTo: ['created_user_id','another_field']
  });

The underlying package friendlySlugs uses for insert/update hooks (https://github.com/matb33/meteor-collection-hooks/) doesn't support upsert yet; see Meteor-Community-Packages/meteor-collection-hooks#88. Once that package supports upsert, I will update this package to support it as well. For now, you can split the upsert into insert / update code if you would like to use this package.

This package will not update slugs for Documents when an update is for multiple documents (multi=true) When I was attempting to get these to work right, it kept using the slug from the first document for all subsequent documents. If you wish to work on this issue, a PR would be welcome.

If you need to create slugs for existing documents, modify the following code to your needs and place in a server file (coffeescript) Increase the limit slowly as your server / workstation can handle. Comment this out or remove once all documents are updated.

Meteor.startup ->
  docs = Collection.find({ slug: {$exists: false}},{limit:50})
  count = 0
  docs.forEach (doc) ->
    Collection.update({_id:doc._id},{$set:{fake:''}})
    count += 1
  console.log 'Update slugs for ' + count + ' Documents.'

• Register a 301 redirect for old URLs when the slug has changed. Anyone have any ideas on how this could be accomplished?
• Create 1 slug based off of 2 fields.
• Let me know if you think anything else would be beneficial.

This is a pretty new package, let me know if something isn't working for your use case.

Feedback and PRs are welcome.