mongoid-slug 4.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: ae9c5f1b269558e56ea27b2c659cc14d4670b886
+  data.tar.gz: bd270a6a2320c369d822dfb7836ea2a13d85db01
+SHA512:
+  metadata.gz: 9c662ebc338efef83a34c6d509c2c012e1404b50ddf9337a8570e27c76ef8ee5e8c2e0eae6ba871bcd669042fee6b3f69576213073726a5f45f5be2e84c9eaac
+  data.tar.gz: 63d767317c4169410246110ea16942ced927e773c7ec94ea83bef62a1d2004a46fa2ce3c9d65ea94a5ef63fad6b2e0f3fe391e4af162a7a5a67dd112a9593a36

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010-2012 Hakan Ensari
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,333 @@
+*IMPORTANT:*  If you are upgrading to Mongoid Slug 1.0.0 please migrate in accordance with the instructions in https://github.com/digitalplaywright/mongoid-slug/wiki/How-to-upgrade-to-1.0.0-or-newer.
+Mongoid Slug 1.0.0  stores the slugs in a single field _slugs of array type, and all previous slugs must be migrated.
+
+Mongoid Slug
+============
+
+Mongoid Slug generates a URL slug or permalink based on one or more fields in a
+Mongoid model. It sits idly on top of [stringex] [1], supporting non-Latin
+characters.
+
+[![Build Status](https://secure.travis-ci.org/digitalplaywright/mongoid-slug.png)](http://travis-ci.org/digitalplaywright/mongoid-slug) [![Dependency Status](https://gemnasium.com/digitalplaywright/mongoid-slug.png)](https://gemnasium.com/digitalplaywright/mongoid-slug) [![Code Climate](https://codeclimate.com/github/digitalplaywright/mongoid-slug.png)](https://codeclimate.com/github/digitalplaywright/mongoid-slug)
+
+Installation
+------------
+
+Add to your Gemfile:
+
+```ruby
+gem 'mongoid-slug'
+```
+
+Usage
+-----
+
+Set up a slug:
+
+```ruby
+class Book
+  include Mongoid::Document
+  include Mongoid::Slug
+
+  field :title
+  slug :title
+end
+```
+
+Find a document by its slug:
+
+```ruby
+# GET /books/a-thousand-plateaus
+book = Book.find params[:book_id]
+```
+
+Mongoid Slug will attempt to determine whether you want to find using the `slugs` field or the `_id` field by inspecting the supplied parameters.
+
+* Mongoid Slug will perform a find based on `slugs` only if all arguments passed to `find` are of the type `String`
+* If your document uses `BSON::ObjectId` identifiers, and all arguments look like valid `BSON::ObjectId`, then Mongoid Slug will perform a find based on `_id`.
+* If your document uses any other type of identifiers, and all arguments passed to `find` are of the same type, then Mongoid Slug will perform a find based on `_id`.
+* If your document uses `String` identifiers and you want to be able find by slugs or ids, to get the correct behaviour, you should add a slug_id_strategy option to your _id field definition.  This option should return something that responds to `call` (a callable) and takes one string argument, e.g. a lambda.  This callable must return true if the string looks like one of your ids.
+
+
+```ruby
+Book.fields['_id'].type
+=> String
+book = Book.find 'a-thousand-plateaus' # Finds by slugs
+=> ...
+
+class Post
+  include Mongoid::Document
+  include Mongoid::Slug
+
+  field :_id, type: String, slug_id_strategy: lambda {|id| id.start_with?('....')}
+
+  field :name
+  slug  :name, :history => true
+end
+
+Post.fields['_id'].type
+=> String
+post = Post.find 'a-thousand-plateaus' # Finds by slugs
+=> ...
+post = Post.find '50b1386a0482939864000001' # Finds by bson ids
+=> ...
+```
+[Read here] [4] for all available options.
+
+Custom Slug Generation
+-------
+
+By default Mongoid Slug generates slugs with stringex. If this is not desired you can
+define your own slug generator like this:
+
+```ruby
+class Caption
+  include Mongoid::Document
+  include Mongoid::Slug
+
+  #create a block that takes the current object as an argument
+  #and returns the slug.
+  slug do |cur_object|
+    cur_object.slug_builder.to_url
+  end
+end
+```
+You can call stringex `to_url` method.
+
+Scoping
+-------
+
+To scope a slug by a reference association, pass `:scope`:
+
+```ruby
+class Company
+  include Mongoid::Document
+
+  references_many :employees
+end
+
+class Employee
+  include Mongoid::Document
+  include Mongoid::Slug
+
+  field :name
+  referenced_in :company
+
+  slug  :name, :scope => :company
+end
+```
+
+In this example, if you create an employee without associating it with any
+company, the scope will fall back to the root employees collection.
+
+Currently, if you have an irregular association name, you **must** specify the
+`:inverse_of` option on the other side of the assocation.
+
+Embedded objects are automatically scoped by their parent.
+
+The value of `:scope` can alternatively be a field within the model itself:
+
+```ruby
+class Employee
+  include Mongoid::Document
+  include Mongoid::Slug
+
+  field :name
+  field :company_id
+
+  slug  :name, :scope => :company_id
+end
+```
+
+Optionally find and create slugs per model type
+-------
+
+By default when using STI, the scope will be around the super-class.
+
+```ruby
+class Book
+  include Mongoid::Document
+  include Mongoid::Slug
+  field :title
+
+  slug  :title, :history => true
+  embeds_many :subjects
+  has_many :authors
+end
+
+class ComicBook < Book
+end
+
+book = Book.create(:title => "Anti Oedipus")
+comic_book = ComicBook.create(:title => "Anti Oedipus")
+comic_book.slugs.should_not eql(book.slugs)
+```
+
+If you want the scope to be around the subclass, then set the option :by_model_type => true.
+
+```ruby
+class Book
+  include Mongoid::Document
+  include Mongoid::Slug
+  field :title
+
+  slug  :title, :history => true, :by_model_type => true
+  embeds_many :subjects
+  has_many :authors
+end
+
+class ComicBook < Book
+end
+
+book = Book.create(:title => "Anti Oedipus")
+comic_book = ComicBook.create(:title => "Anti Oedipus")
+comic_book.slugs.should eql(book.slugs)
+```
+
+History
+-------
+
+To specify that the history of a document should be kept track of, pass
+`:history` with a value of `true`.
+
+```ruby
+class Page
+  include Mongoid::Document
+  include Mongoid::Slug
+
+  field :title
+
+  slug :title, history: true
+end
+```
+
+The document will then be returned for any of the saved slugs:
+
+```ruby
+page = Page.new title: "Home"
+page.save
+page.update_attributes title: "Welcome"
+
+Page.find("welcome") == Page.find("home") #=> true
+```
+
+Reserved Slugs
+--------------
+
+Pass words you do not want to be slugged using the `reserve` option:
+
+```ruby
+class Friend
+  include Mongoid::Document
+
+  field :name
+  slug :name, reserve: ['admin', 'root']
+end
+
+friend = Friend.create name: 'admin'
+Friend.find('admin') # => nil
+friend.slug # => 'admin-1'
+```
+
+When reserved words are not specified, the words 'new' and 'edit' are considered reserved by default.
+Specifying an array of custom reserved words will overwrite these defaults.
+
+Localize Slug
+--------------
+
+The slug can be localized:
+
+```ruby
+class PageSlugLocalize
+  include Mongoid::Document
+  include Mongoid::Slug
+
+  field :title, localize: true
+  slug  :title, localize: true
+end
+```
+
+This feature is built upon Mongoid localized fields, so fallbacks and localization
+works as documented in the Mongoid manual.
+
+PS! A migration is needed to use Mongoid localized fields for documents that was created when this
+feature was off. Anything else will cause errors.
+
+Custom Find Strategies
+--------------
+
+By default find will search for the document by the id field if the provided id
+looks like a BSON::ObjectId, and it will otherwise find by the _slugs field. However,
+custom strategies can ovveride the default behavior, like e.g:
+
+```ruby
+module Mongoid::Slug::UuidIdStrategy
+  def self.call id
+    id =~ /\A([0-9a-fA-F]){8}-(([0-9a-fA-F]){4}-){3}([0-9a-fA-F]){12}\z/
+  end
+end
+```
+
+Use a custom strategy by adding the slug_id_strategy annotation to the _id field:
+
+```ruby
+class Entity
+  include Mongoid::Document
+  include Mongoid::Slug
+
+  field :_id, type: String, slug_id_strategy: UuidIdStrategy
+
+  field :user_edited_variation
+  slug  :user_edited_variation, :history => true
+end
+```
+
+
+Adhoc checking whether a string is unique on a per Model basis
+--------------------------------------------------------------
+
+Lets say you want to have a auto-suggest function on your GUI that could provide a preview of what the url or slug could be before the form to create the record was submitted.
+
+You can use the UniqueSlug class in your server side code to do this, e.g.
+
+```ruby
+title = params[:title]
+unique = Mongoid::Slug::UniqueSlug.new(Book.new).find_unique(title)
+...
+# return some representation of unique
+```
+
+
+Mongoid::Paranoia Support
+-------------------------
+
+The [Mongoid::Paranoia](http://github.com/simi/mongoid-paranoia) gem adds "soft-destroy" functionality to Mongoid documents.
+Mongoid::Slug contains special handling for Mongoid::Paranoia:
+- When destroying a paranoid document, the slug will be unset from the database.
+- When restoring a paranoid document, the slug will be rebuilt. Note that the new slug may not match the old one.
+- When resaving a destroyed paranoid document, the slug will remain unset in the database.
+- For indexing purposes, sparse unique indexes are used. The sparse condition will ignore any destroyed paranoid documents, since their slug is not set in database.
+
+```ruby
+class Entity
+  include Mongoid::Document
+  include Mongoid::Slug
+  include Mongoid::Paranoia
+end
+```
+
+The following variants of Mongoid Paranoia are officially supported:
+* Mongoid 3 built-in Mongoid::Paranoia
+* Mongoid 4 gem http://github.com/simi/mongoid-paranoia
+
+Mongoid 4 gem "mongoid-paranoia" (http://github.com/haihappen/mongoid-paranoia)
+is not officially supported but should also work.
+
+
+References
+----------
+
+[1]: https://github.com/rsl/stringex/
+[2]: https://secure.travis-ci.org/hakanensari/mongoid-slug.png
+[3]: http://travis-ci.org/hakanensari/mongoid-slug
+[4]: https://github.com/digitalplaywright/mongoid-slug/blob/master/lib/mongoid/slug.rb

data/lib/mongoid/slug.rb

@@ -0,0 +1,333 @@
+require 'mongoid'
+require 'stringex'
+require 'mongoid/slug/criteria'
+require 'mongoid/slug/index'
+require 'mongoid/slug/paranoia'
+require 'mongoid/slug/unique_slug'
+require 'mongoid/slug/slug_id_strategy'
+
+module Mongoid
+  # Slugs your Mongoid model.
+  module Slug
+    extend ActiveSupport::Concern
+
+    included do
+      cattr_accessor :reserved_words,
+                     :slug_scope,
+                     :slugged_attributes,
+                     :url_builder,
+                     :history,
+                     :by_model_type
+
+      # field :_slugs, type: Array, default: [], localize: false
+      # alias_attribute :slugs, :_slugs
+    end
+
+    module ClassMethods
+      # @overload slug(*fields)
+      #   Sets one ore more fields as source of slug.
+      #   @param [Array] fields One or more fields the slug should be based on.
+      #   @yield If given, the block is used to build a custom slug.
+      #
+      # @overload slug(*fields, options)
+      #   Sets one ore more fields as source of slug.
+      #   @param [Array] fields One or more fields the slug should be based on.
+      #   @param [Hash] options
+      #   @param options [Boolean] :history Whether a history of changes to
+      #   the slug should be retained. When searched by slug, the document now
+      #   matches both past and present slugs.
+      #   @param options [Boolean] :permanent Whether the slug should be
+      #   immutable. Defaults to `false`.
+      #   @param options [Array] :reserve` A list of reserved slugs
+      #   @param options :scope [Symbol] a reference association or field to
+      #   scope the slug by. Embedded documents are, by default, scoped by
+      #   their parent.
+      #   @yield If given, a block is used to build a slug.
+      #
+      # @example A custom builder
+      #   class Person
+      #     include Mongoid::Document
+      #     include Mongoid::Slug
+      #
+      #     field :names, :type => Array
+      #     slug :names do |doc|
+      #       doc.names.join(' ')
+      #     end
+      #   end
+      #
+      def slug(*fields, &block)
+        options = fields.extract_options!
+
+        self.slug_scope            = options[:scope]
+        self.reserved_words        = options[:reserve] || Set.new(["new", "edit"])
+        self.slugged_attributes    = fields.map &:to_s
+        self.history               = options[:history]
+        self.by_model_type         = options[:by_model_type]
+
+        field :_slugs, type: Array, default: [], localize: options[:localize]
+        alias_attribute :slugs, :_slugs
+
+        # Set index
+        unless embedded?
+          index(*Mongoid::Slug::Index.build_index(self.slug_scope_key, self.by_model_type))
+        end
+
+        #-- Why is it necessary to customize the slug builder?
+        default_url_builder = lambda do |cur_object|
+          cur_object.slug_builder.to_url
+        end
+
+        self.url_builder = block_given? ? block : default_url_builder
+
+        #-- always create slug on create
+        #-- do not create new slug on update if the slug is permanent
+        if options[:permanent]
+          set_callback :create, :before, :build_slug
+        else
+          set_callback :save, :before, :build_slug, :if => :slug_should_be_rebuilt?
+        end
+
+        # If paranoid document:
+        # - include shim to add callbacks for restore method
+        # - unset the slugs on destroy
+        # - recreate the slug on restore
+        # - force reset the slug when saving a destroyed paranoid document, to ensure it stays unset in the database
+        if is_paranoid_doc?
+          self.send(:include, Mongoid::Slug::Paranoia) unless self.respond_to?(:before_restore)
+          set_callback :destroy, :after,  :unset_slug!
+          set_callback :restore, :before, :set_slug!
+          set_callback :save,    :before, :reset_slug!, :if => :paranoid_deleted?
+          set_callback :save,    :after,  :clear_slug!, :if => :paranoid_deleted?
+        end
+      end
+
+      def look_like_slugs?(*args)
+        with_default_scope.look_like_slugs?(*args)
+      end
+
+      # Returns the scope key for indexing, considering associations
+      #
+      # @return [ Array<Document>, Document ] Whether the document is paranoid
+      def slug_scope_key
+        return nil unless self.slug_scope
+        self.reflect_on_association(self.slug_scope).try(:key) || self.slug_scope
+      end
+
+      # Find documents by slugs.
+      #
+      # A document matches if any of its slugs match one of the supplied params.
+      #
+      # A document matching multiple supplied params will be returned only once.
+      #
+      # If any supplied param does not match a document a Mongoid::Errors::DocumentNotFound will be raised.
+      #
+      # @example Find by a slug.
+      #   Model.find_by_slug!('some-slug')
+      #
+      # @example Find by multiple slugs.
+      #   Model.find_by_slug!('some-slug', 'some-other-slug')
+      #
+      # @param [ Array<Object> ] args The slugs to search for.
+      #
+      # @return [ Array<Document>, Document ] The matching document(s).
+      def find_by_slug!(*args)
+        with_default_scope.find_by_slug!(*args)
+      end
+
+      def queryable
+        scope_stack.last || Criteria.new(self) # Use Mongoid::Slug::Criteria for slugged documents.
+      end
+
+      # Indicates whether or not the document includes Mongoid::Paranoia
+      #
+      # This can be replaced with .paranoid? method once the following PRs are merged:
+      # - https://github.com/simi/mongoid-paranoia/pull/19
+      # - https://github.com/haihappen/mongoid-paranoia/pull/3
+      #
+      # @return [ Array<Document>, Document ] Whether the document is paranoid
+      def is_paranoid_doc?
+        !!(defined?(::Mongoid::Paranoia) && self < ::Mongoid::Paranoia)
+      end
+    end
+
+    # Builds a new slug.
+    #
+    # @return [true]
+    def build_slug
+      if localized?
+        begin
+          orig_locale = I18n.locale
+          all_locales.each do |target_locale|
+            I18n.locale = target_locale
+            apply_slug
+          end
+        ensure
+          I18n.locale = orig_locale
+        end
+      else
+        apply_slug
+      end
+      true
+    end
+
+    def apply_slug
+      _new_slug = find_unique_slug
+
+      #skip slug generation and use Mongoid id
+      #to find document instead
+      return true if _new_slug.size == 0
+
+      # avoid duplicate slugs
+      self._slugs.delete(_new_slug) if self._slugs
+
+      if !!self.history && self._slugs.is_a?(Array)
+        append_slug(_new_slug)
+      else
+        self._slugs = [_new_slug]
+      end
+    end
+
+    # Builds slug then atomically sets it in the database.
+    # This is used when working with the Mongoid::Paranoia restore callback.
+    #
+    # This method is adapted to use the :set method variants from both
+    # Mongoid 3 (two args) and Mongoid 4 (hash arg)
+    def set_slug!
+      build_slug
+      self.method(:set).arity == 1 ? set({_slugs: self._slugs}) : set(:_slugs, self._slugs)
+    end
+
+    # Atomically unsets the slug field in the database. It is important to unset
+    # the field for the sparse index on slugs.
+    #
+    # This also resets the in-memory value of the slug field to its default (empty array)
+    def unset_slug!
+      unset(:_slugs)
+      clear_slug!
+    end
+
+    # Rolls back the slug value from the Mongoid changeset.
+    def reset_slug!
+      self.reset__slugs!
+    end
+
+    # Sets the slug to its default value.
+    def clear_slug!
+      self._slugs = []
+    end
+
+    # Finds a unique slug, were specified string used to generate a slug.
+    #
+    # Returned slug will the same as the specified string when there are no
+    # duplicates.
+    #
+    # @return [String] A unique slug
+    def find_unique_slug
+      UniqueSlug.new(self).find_unique
+    end
+
+    # @return [Boolean] Whether the slug requires to be rebuilt
+    def slug_should_be_rebuilt?
+      (new_record? or _slugs_changed? or slugged_attributes_changed?) and !paranoid_deleted?
+    end
+
+    # Indicates whether or not the document has been deleted in paranoid fashion
+    # Always returns false if the document is not paranoid
+    #
+    # @return [Boolean] Whether or not the document has been deleted in paranoid fashion
+    def paranoid_deleted?
+      !!(self.class.is_paranoid_doc? and self.deleted_at != nil)
+    end
+
+    def slugged_attributes_changed?
+      slugged_attributes.any? { |f| attribute_changed? f.to_s }
+    end
+
+    # @return [String] A string which Action Pack uses for constructing an URL
+    # to this record.
+    def to_param
+      slug || super
+    end
+
+    # @return [String] the slug, or nil if the document does not have a slug.
+    def slug
+      return _slugs.last if _slugs
+      return _id.to_s
+    end
+
+    def slug_builder
+      _cur_slug = nil
+      if new_with_slugs? or persisted_with_slug_changes?
+        #user defined slug
+        _cur_slug = _slugs.last
+      end
+      #generate slug if the slug is not user defined or does not exist
+      _cur_slug || pre_slug_string
+    end
+
+    def self.mongoid3?
+      ::Mongoid.const_defined? :Observer
+    end
+
+    private
+
+    def append_slug(_slug)
+      if localized?
+        # This is necessary for the scenario in which the slugged locale is not yet present
+        # but the default locale is. In this situation, self._slugs falls back to the default
+        # which is undesired
+        current_slugs = self._slugs_translations.fetch(I18n.locale.to_s, [])
+        current_slugs << _slug
+        self._slugs_translations = self._slugs_translations.merge(I18n.locale.to_s => current_slugs)
+      else
+        self._slugs << _slug
+      end
+    end
+
+    # Returns true if object is a new record and slugs are present
+    def new_with_slugs?
+      if localized?
+        # We need to check if slugs are present for the locale without falling back
+        # to a default
+        new_record? and _slugs_translations.fetch(I18n.locale.to_s, []).any?
+      else
+        new_record? and _slugs.present?
+      end
+    end
+
+    # Returns true if object has been persisted and has changes in the slug
+    def persisted_with_slug_changes?
+      if localized?
+        changes = self._slugs_change
+        return (persisted? and false) if changes.nil?
+
+        # ensure we check for changes only between the same locale
+        original = changes.first.try(:fetch, I18n.locale.to_s, nil)
+        compare = changes.last.try(:fetch, I18n.locale.to_s, nil)
+        persisted? and original != compare
+      else
+        persisted? and _slugs_changed?
+      end
+    end
+
+    def localized?
+      self.fields['_slugs'].options[:localize] rescue false
+    end
+
+    # Return all possible locales for model
+    # Avoiding usage of I18n.available_locales in case the user hasn't set it properly, or is
+    # doing something crazy, but at the same time we need a fallback in case the model doesn't
+    # have any localized attributes at all (extreme edge case).
+    def all_locales
+      locales = self.slugged_attributes
+                    .map{|attr| self.send("#{attr}_translations").keys if self.respond_to?("#{attr}_translations")}
+                    .flatten.compact.uniq
+      locales = I18n.available_locales if locales.empty?
+      locales
+    end
+
+    def pre_slug_string
+      self.slugged_attributes.map { |f| self.send f }.join ' '
+    end
+  end
+end