Mongoid::Token - Short snappy tokens for Mongoid documents
This library is a quick and simple way to generate unique, random tokens for your mongoid documents, in the cases where you can't, or don't want to use slugs, or the default MongoDB IDs.
Mongoid::Token can help turn this:
Into something more like this:
In your gemfile, add:
gem 'mongoid_token', '~> 1.0.0'
Then update your bundle
$ bundle update
In your Mongoid documents, just add
include Mongoid::Token and the
token method will take care of all the setup, like so:
class Person include Mongoid::Document include Mongoid::Timestamps include Mongoid::Token field :first_name field :last_name token :length => 8 end
Obviously, this will create tokens of 8 characters long - make them as short or as long as you require.
Note: Mongoid::Token leverages Mongoid's 'safe mode' by automatically creating a unique index on your documents using the token field. In order to take advantage of this feature (and ensure that your documents always have unique tokens) remember to create your indexes.
See 'Token collision/duplicate prevention' below for more details.
token method has a couple of key options:
length, which determines the
length (or maximum length, in some cases) and
contains, which tells
Mongoid::Token which characters to use when generating the token.
The options for
contains are as follows:
:alphanumeric- letters (upper and lowercase) and numbers
:alpha- letters (upper and lowercase) only
:numeric- numbers only, anything from 1 character long, up to and
:fixed_numeric- numbers only, but with the number of characters always the same as
You can also rename the token field, if required, using the
token :contains => :numeric, :field_name => :purchase_order_number
token :length => 8, :contains => :alphanumericgenerates something like
token :length => 5, :contains => :alphagereates something like
token :length => 4, :contains => :numericcould generate anything from
9999- but in a random order
token :length => 4, :contains => :fixed_numericwill generate anything from
9999in a random order
The library also contains a finder method for looking up your documents
Adding tokens to existing documents
If you've got an app with existing data that you would like to add tokens to - all you need to do is save each of your models and they will be assigned a token, if it's missing.
Token collision/duplicate prevention
Mongoid::Token leverages Mongoid's 'safe mode' by automatically creating a unique index on your documents using the token field. In order to take advantage of this feature (and ensure that your documents always have unique tokens) remember to create your indexes.
You can read more about indexes in the Mongoid docs.
Additionally, Mongoid::Token will attempt to create a token 3 times
before eventually giving up and raising a
Mongoid::Token::CollisionRetriesExceeded exception. To take advantage
of this, one must set
persist_in_safe_mode = true in your Mongoid
The number of retry attempts is adjustable in the
token method using the
:retry options. Set it to zero to turn off retrying.
token :length => 6, :retry => 4Will retry token generation 4 times before bailing out
token :length => 3, :retry => 0Retrying disabled
If you find a problem, please submit an issue (and a failing test, if you can). Pull requests and feature requests are always welcome and greatly appreciated.