This gem is a fork that changes the original behaviour of Mongoid::Token: Instead of a custom field it changes the _id field by default. And you may still use tokens on custom fields.

This library is a quick and simple way to generate unique, random ids for your mongoid documents, in the cases where you can't, or don't want to use slugs, or the default MongoDB ObjectIDs.

Mongoid::Ids can help turn this:

http://bestappever.com/video/4dcfbb3c6a4f1d4c4a000012

Into something more like this:

http://bestappever.com/video/8tmQ9p

In your gemfile, add:

gem 'mongoid-ids'

In your Mongoid documents, just add include Mongoid::Ids and the token method will take care of all the setup, like so:

class Person
  include Mongoid::Document
  include Mongoid::Ids

  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.

Notice: Every Mongoid overriding has been removed (#find and #to_param).

class Person
  include Mongoid::Document
  include Mongoid::Ids

  field :name

  token :code
  token :token
  token :other_code
end

Note on custom field: Mongoid::Ids 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. Also, Mongoid::Ids will never override to_param.

Mongoid::Ids will never override find. There's some helpers for custom fields:

Video.find_by_code("x3v98")
Account.find_by_token("ACC-123456")

You can disable these with the skip_finders configuration option.

You may choose between two different systems for how your tokens look:

For simple setup, you can use combination of the length and contains, which modify the length and types of characters to use.

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.

Example:

token length: 8  # Tokens are now of length 8
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 specified length.

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 :length
• :fixed_numeric - integer, but will always be of length :length
• :fixed_numeric_no_leading_zeros - same as :fixed_numeric, but will never start with zeros

Examples:

token contains: :alpha_upper, length: 8
token contains: :fixed_numeric

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 :length and :contains options.

This was designed to operate in a similar way to something like strftime, 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

Example:

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.

Examples:

token pattern: "APP-%d6" # Generates something like; "APP-638924"

This allows you to change the field name used by Mongoid::Ids This is particularly handy to use multiple tokens one a single document.

Examples:

token length: 6
token :sharing_token, length: 12
token :yet_another

This will prevent the gem from creating the customised finders and overrides for the default find behaviour used by Mongoid.

Example:

token skip_finders: true

In the event of a token collision, this gem will attempt to try three more times before raising a Mongoid::Ids::CollisionRetriesExceeded error. If you're wanting it to try harder, or less hard, then this option is for you.

Examples:

token retry_count: 9
token retry_count: 0

This gem just changes the Mongoid::Token behaviour, which is found at:

http://github.com/thetron/mongoid_token

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.

Test matrix: Mongoid 4 & 5.

Thanks to everyone that has contributed to this gem over the past year. Many, many thanks - you guys rawk.

Thanks to everyone who has provided support for this gem over the years. In particular: olliem, msolli, siong1987, stephan778, eagleas, and jamesotron.