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 ObjectIDs.
Mongoid::Token can help turn this:
Into something more like this:
In your gemfile, add:
gem 'mongoid_token', '~> 2.0.0'
Then update your bundle
$ bundle install
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::Token field :name token end
And that's it! There's lots of configuration options too - which are all
listed below. By default, the
token method will
create tokens 4 characters long, containing random alphanumeric characters.
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.
Using without Rails
If you're using Mongoid without Rails, remember to:
in your app
By default, the gem will add a convenience
find_by_[token name] method, to
make it a tiny bit simpler to query by your tokens. If you'd rather it didn't,
you can disable these with the
skip_finders configuration option.
The methods accept either a single token, or an array of tokens:
Video.find_by_token("x3v98") # If your token was named 'token' Account.find_by_account_number(["ACC-123456", "ACC-567890"]) # If your token was named 'account_number'
Mongoid::Token 2.0.0, you can now choose between two different
systems for managing how your tokens look.
For when you need to generate more complex tokens, you can use the
pattern option, which allows for very low-level control of the precise
structure of your tokens, as well as allowing for static strings, like
prefixes, infixes or suffixes.
This one is easy, it's just an integer.
token :length => 6 # Tokens are now of length 6 token :length => 12 # Whow, whow, whow. Slow down egghead.
You get the idea.
The only caveat here is that if used in combination with the
:contains => :numeric option, tokens may vary in length up to the
Contains has 7 different options:
:alphanumeric- contains uppercase & lowercase characters, as well as numbers
:alpha- contains only uppercase & lowercase characters
:alpha_upper- contains only uppercase letters
:alpha_lower- contains only lowercase letters
:numeric- integer, length may be shorter than
:fixed_numeric- integer, but will always be of length
:fixed_numeric_no_leading_zeros- same as
:fixed_numeric, but will never start with zeros
:fixed_hex_numeric- hex integer, but will always be of length
:fixed_hex_numeric_no_leading_zeros- same as
:fixed_hex_numeric, but will never start with zeros
token :contains => :alpha_upper, :length => 8 token :contains => :fixed_numeric
New in 2.0.0, patterns allow you fine-grained control over how your
tokens look. It's great for generating random data that has a
requirements to also have some basic structure. If you use the
:pattern option, it will override both the
This was designed to operate in a similar way to something like
if the syntax offends you - please open an issue, I'd love to get some
feedback here and better refine how these are generated.
Any characters in the string are treated as static, except those that are
proceeded by a
%. Those special characters represent a single, randomly
generated character, and are as follows:
%s- any uppercase, lowercase, or numeric character
%w- any uppercase, or lowercase character
%c- any lowercase character
%C- any uppercase character
%d- any digit
%D- any non-zero digit
token :pattern => "PRE-%C%C-%d%d%d%d" # Generates something like: 'PRE-ND-3485'
You can also add a repetition modifier, which can help improve readability on more complex patterns. You simply add any integer after the letter.
token :pattern => "APP-%d6" # Generates something like; "APP-638924"
Field Name (
This allows you to change the field name used by
:token). This is particularly handy when you're wanting to
use multiple tokens one a single document.
token :length => 6 token :field_name => :sharing_token, :length => 12 token :field_name => :yet_another
Skip Finders (
This will prevent the gem from creating the extra
token :skip_finders => true
Override to_param (
Mongoid::Token will override to_param, to make it an easy
drop-in replacement for the default ObjectIDs. If needed, you can turn
this behaviour off:
token :override_to_param => false
Retry Count (
In the event of a token collision, this gem will attempt to try three
more times before raising a
error. If you're wanting it to try harder, or less hard, then this
option is for you.
token :retry_count => 9 token :retry_count => 0
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.
Thanks to everyone that has contributed to this gem over the past year. Many, many thanks - you guys rawk.