Mongoid::SleepingKingStudios
A collection of concerns and extensions to add functionality to Mongoid documents and collections.
The Mixins
HasTree
require 'mongoid/sleeping_king_studios/has_tree'
Sets up a basic tree structure by adding belongs_to :parent and has_many :children relations, as well as some helper methods.
From 0.2.0 to 0.3.1, was Mongoid::SleepingKingStudios::Tree
How To Use:
class TreeDocument
include Mongoid::Document
include Mongoid::SleepingKingStudios::HasTree
has_tree
end # class
Options
You can pass customisation options for the generated relations into the ::has_tree method.
class EvilEmployee
include Mongoid::Document
include Mongoid::SleepingKingStudios::HasTree
has_tree :parent => { :relation_name => :overlord },
:children => { :relation_name => :minions, :dependent => :destroy }
end # class
Available options include the standard Mongoid options for a :belongs_to and a :has_many relationship, respectively. In addition, you can set a :relation_name option to change the name of the created relation (see example above). The concern will automatically update the respective :inverse_of options to match the updated relation names.
Cache Ancestry
Stores the chain of ancestors in an :ancestor_ids array field, and adds the #ancestors and #descendents scopes.
class AncestryTree
include Mongoid::Document
include Mongoid::SleepingKingStudios::HasTree
has_tree :cache_ancestry => true
end # class
Options
You can customize the ancestry cache by passing in a hash of options as the :cache_ancestry value in the ::has_tree method.
class PartGroup
include Mongoid::Document
include Mongoid::SleepingKingStudios::HasTree
# This creates the #assemblies method and #assembly_ids field.
has_tree :cache_ancestry => { :relation_name => :assemblies }
end # class
- foreign_key: The name of the field used to store the ancestor references. Defaults to 'ancestor_ids'.
- relation_name: The name of the generated relation for the array of parent objects. Defaults to 'ancestors'.
Warning: Using this option will make many write operations much, much slower and more resource-intensive. Do not use this option outside of read-heavy applications with very specific requirements, e.g. a directory structure where you must access all parent directories on each page view.
Orderable
require 'mongoid/sleeping_king_studios/orderable'
Adds a field that tracks the index of each record with respect to the provided sort order parameters.
How To Use:
class OrderedDocument
include Mongoid::Document
include Mongoid::SleepingKingStudios::Orderable
cache_ordering :created_at.desc, :as => :most_recent_order
end # class
The ::cache_ordering method accepts a subset of the params for an Origin #order_by query operation, e.g.:
- :first_field.desc, :second_field
- { :first_field => -1, :second_field => :asc }
- [[:first_field, :desc], [:second_field, 1]]
Helpers
Creating an ordering cache also creates the following helpers. The name of the generated helpers will depend on the sort params provided, or the name given via the :as option (see below). For example, providing :as => :alphabetical_order will generate helpers #next_alphabetical, #prev_alphabetical, and ::reorder_alphabetical!.
#next_ordering_name
Finds the next document, based on the stored ordering values. Takes an optional scope parameter to filter the results.
#prev_ordering_name
Finds the previous document, based on the stored ordering values. Takes an optional scope parameter to filter the results.
::first_ordering_name
(Class Method) Finds the first document, based on the stored ordering values. Takes an optional scope parameter to filter the results.
::last_ordering_name
(Class Method) Finds the last document, based on the stored ordering values. Takes an optional scope parameter to filter the results.
::reorder_ordering_name!
(Class Method) Loops through the collection and sets each item's field to the appropriate ordered index. Normally, this is handled on item save, but this helper allows a bulk update of the collection when adding the concern to an existing model, or if data corruption or other issues have broken the existing values.
Options
As
cache_ordering sort_params, :as => :named_order
Sets the name of the generated order field and helpers. If no name is specified, one will be automatically generated of the form first_field_desc_second_field_asc_order.
Filter
cache_ordering sort_params, :filter => { :published => true }
Restricts which records from the collection will be sorted to generate the ordering values. If a record is filtered out, its ordering field will be set to nil.
Sluggable
require 'mongoid/sleeping_king_studios/sluggable'
Adds a slug field that automatically tracks a base attribute and stores a short, url-friendly version.
How To Use:
class SluggableDocument
include Mongoid::Document
include Mongoid::SleepingKingStudios::Sluggable
field :title, :type => String
slugify :title
end # class
Helpers
#generate_slug!
If the document's slug is blank, or if it does not match the base attribute value, calculates the value from the base attribute and assigns it atomically. Locked slugs (see the :lockable option) are unaffected.
::slugify_all!
(Class Method) Loops through all documents in the collection. If the document's slug is blank, or if it does not match the base attribute value, calculates the value from the base attribute and assigns it atomically. Locked slugs (see the :lockable option) are unaffected.
Use this method to generate slugs when adding this concern to a model with existing documents.
#to_slug
Converts the current value of the base attribute to a slug value, but returns the converted value instead of changing the slug field.
::value_to_slug
(Class Method) Converts the provided string to a slug value.
Options
Lockable
slugify :title, :lockable => true
Allows the slug to be specified manually. Adds an additional #slug_lock field that is automatically set to true when #slug= is called. To resume tracking the base attribute, set :slug_lock to false.
License
Mongoid::SleepingKingStudios is released under the MIT License.