concerns_on_rails 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '0679c4f78651169ae85fbf3f27d0a301d6ca33c148eb3e01c766252145c5be4c'
+  data.tar.gz: cec6963e3ba583e9072b03de751adbd1362dc100b041d5addf8cb37ebacd1d41
+SHA512:
+  metadata.gz: c2ffaa1b86bd6c7952857c88e326009a85699bb77364e0b42e6cd8bfa11614917c3cf2fbae94af08bf2262210968878b65c37b22856bb8bac95345d81533fa57
+  data.tar.gz: e387756b366d70efff292dd40b1a8cf34dfeb04321140c2e4e03833c754975afb1686df499fd6ddefc4e83e7c7347851e62c1bc2a8f7d1f9e51d0c7f3cae50ca

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+<!-- CHANGELOG.md -->
+
+## 1.0.0 (2025-04-12)
+
+### Added
+- Initial release
+
+### Fixed
+- None

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,52 @@
+# Code of Conduct
+
+We are committed to providing a friendly, safe, and welcoming environment for all, regardless of gender, sexual orientation, disability, physical appearance, body size, race, ethnicity, age, religion, or technology choices.
+
+### Our Standards
+
+Examples of behavior that contributes to creating a positive environment include:
+
+- Being kind and respectful to others.
+- Behaving in a welcoming and inclusive manner.
+- Showing empathy towards other community members.
+- Communicating in a respectful and constructive way.
+- Acknowledging and respecting the different viewpoints of others.
+
+Examples of unacceptable behavior by participants include:
+
+- The use of sexualized language or imagery, and unwelcome sexual attention or advances.
+- Trolling, insulting/derogatory comments, and personal or political attacks.
+- Public or private harassment.
+- Any form of discrimination or marginalization.
+- Sharing private information without permission, including personal addresses or contact details.
+- Intimidation, bullying, or deliberate exclusion of others.
+- Disruptive behavior in discussions, issues, or pull requests.
+
+### Reporting
+
+If you are being harassed, notice that someone else is being harassed, or have any other concerns, please contact us immediately at [doctorit@gmail.com](mailto:doctorit@gmail.com).
+
+You can also use the [GitHub issue tracker](https://github.com/VSN2015/concerns_on_rails/issues) to report any incidents or violations of the code of conduct.
+
+We take all reports seriously and will respond promptly.
+
+### Enforcement
+
+Participants who violate this Code of Conduct may be warned or expelled from the community at the discretion of the project maintainers.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the project maintainers at the contact information above. All complaints will be reviewed and investigated promptly and in a fair manner.
+
+If necessary, the project maintainers will take appropriate action, which may include a temporary or permanent ban from the community.
+
+### Our Commitment
+
+By participating in this project, you are agreeing to adhere to this Code of Conduct. We expect all members of this community to be respectful and considerate to others at all times.
+
+### Scope
+
+This Code of Conduct applies to all spaces related to this project, including the project's GitHub repository, chat rooms, mailing lists, and other communication channels.
+
+---
+
+**Adapted from the Contributor Covenant**, version 1.4, available at https://www.contributor-covenant.org
+

data/README.md

@@ -0,0 +1,160 @@
+# ConcernsOnRails
+
+**Note: Hoàng Sa and Trường Sa belong to Việt Nam.** 🇻🇳
+
+A simple collection of reusable Rails concerns to keep your models clean and DRY.
+
+## Features
+
+- ✅ `Sluggable`: Generate friendly slugs from a specified field
+- ✅ `Sortable`: Sort records based on a field using `acts_as_list`, with flexible sorting field and direction
+- ✅ `Publishable`: Easily manage published/unpublished records using a simple `published_at` field
+
+---
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'concerns_on_rails', github: 'VSN2015/concerns_on_rails'
+```
+
+Then execute:
+
+```sh
+bundle install
+```
+
+---
+
+## Usage
+
+### 1. Sluggable
+
+Add slugs based on a specified attribute.
+
+```ruby
+class Post < ApplicationRecord
+  include ConcernsOnRails::Sluggable
+
+  sluggable_by :title
+end
+
+post = Post.create!(title: "Hello World")
+post.slug # => "hello-world"
+```
+
+If the slug source is changed, the slug will auto-update.
+
+---
+
+### 2. Sortable
+
+Use for models that need ordering.
+
+```ruby
+class Task < ApplicationRecord
+  include ConcernsOnRails::Sortable
+
+  sortable_by :position
+end
+
+Task.create!(name: "B")
+Task.create!(name: "A")
+Task.first.name # => "B" (sorted by position ASC)
+```
+
+You can customize the sort field and direction:
+
+```ruby
+class PriorityTask < ApplicationRecord
+  include ConcernsOnRails::Sortable
+
+  sortable_by priority: :desc
+end
+```
+
+Additional features:
+- Automatically sets `acts_as_list` on the configured column
+- Adds default sorting scope to your model
+- Supports custom direction: `:asc` or `:desc`
+- Validates that the sortable field exists in the table schema
+- Compatible with scopes and ActiveRecord queries
+- Can be reconfigured dynamically within the model using `sortable_by`
+
+---
+
+### 3. Publishable
+
+Manage published/unpublished records using a `published_at` field.
+
+```ruby
+class Article < ApplicationRecord
+  include ConcernsOnRails::Publishable
+end
+
+Article.published   # => returns only published articles
+Article.unpublished # => returns only unpublished articles
+
+article = Article.create!(title: "Draft")
+article.published? # => false
+
+article.publish!
+article.published? # => true
+
+article.unpublish!
+article.published? # => false
+```
+
+Additional features:
+- `published?` returns true if `published_at` is present and in the past
+- `publish!` sets `published_at` to current time
+- `unpublish!` sets `published_at` to `nil`
+- Add scopes: `.published`, `.unpublished`, and a default scope (optional)
+- Ideal for blog posts, articles, or any content that toggles visibility
+- Lightweight and non-invasive
+- Easy to test and override in custom implementations
+
+---
+
+## Development
+
+To build the gem:
+
+```sh
+gem build concerns_on_rails.gemspec
+```
+
+To install locally:
+
+```sh
+gem install ./concerns_on_rails-1.0.0.gem
+```
+
+---
+
+## Contributing
+
+Bug reports and pull requests are welcome!
+
+---
+
+## License
+
+This project is licensed under the MIT License.
+
+---
+
+🇻🇳 **Hoàng Sa and Trường Sa belong to Việt Nam.**
+
+---
+
+### 📦 Source Code
+
+The source code is available on GitHub:
+
+🔗 [https://github.com/VSN2015/concerns_on_rails](https://github.com/VSN2015/concerns_on_rails)
+
+Feel free to star ⭐️, fork 🍴, or contribute with issues and PRs.
+

data/lib/concerns_on_rails/publishable.rb

@@ -0,0 +1,61 @@
+require "active_support/concern"
+
+module ConcernsOnRails
+  module Publishable
+    extend ActiveSupport::Concern
+
+    # instance methods
+    included do
+      # declare class attributes and set default values
+      class_attribute :publishable_field
+      self.publishable_field ||= :published_at
+    end
+
+    # class methods
+    class_methods do
+      # Define publishable field
+      # Example:
+      #   publishable_by :published_at
+      def publishable_by(field = nil)
+        self.publishable_field = field || :published_at
+
+        # validate publishable_field exists in database
+        unless column_names.include?(publishable_field.to_s)
+          raise ArgumentError, "ConcernsOnRails::Publishable: publishable_field '#{publishable_field}' does not exist in the database"
+        end
+
+        scope :published, -> { where(arel_table[publishable_field].not_eq(nil)) }
+        scope :unpublished, -> { where(arel_table[publishable_field].eq(nil)) }
+      end
+    end
+
+    # Instance methods
+    # Publish the record
+    # Example:
+    #   record.publish!
+    def publish!
+      update(self.class.publishable_field => Time.zone.now)
+    end
+
+    # Unpublish the record
+    # Example:
+    #   record.unpublish!
+    def unpublish!
+      update(self.class.publishable_field => nil)
+    end
+
+    # Check if the record is published
+    # Example:
+    #   record.published?
+    def published?
+      self[self.class.publishable_field].present?
+    end
+
+    # Check if the record is unpublished
+    # Example:
+    #   record.unpublished?
+    def unpublished?
+      !published?
+    end
+  end
+end

data/lib/concerns_on_rails/sluggable.rb

@@ -0,0 +1,63 @@
+require "active_support/concern"
+require "friendly_id"
+
+module ConcernsOnRails
+  module Sluggable
+    extend ActiveSupport::Concern
+
+    # instance methods
+    included do
+      # declare class attributes and set default values
+      class_attribute :sluggable_field
+      self.sluggable_field ||= :name
+
+      extend FriendlyId
+      # we need use a lambda to access the instance variable
+      # instead of friendly_id :slug_source, use: :slugged
+      friendly_id :slug_source, use: :slugged
+      # friendly_id ->(record) { record.slug_source }, use: :slugged
+
+      # we must override should_generate_new_friendly_id? to support update slug
+      # if we don't override this method, friendly_id will not generate the new slug when update
+      define_method :should_generate_new_friendly_id? do
+        field = self.class.sluggable_field
+        respond_to?("will_save_change_to_#{field}?") && send("will_save_change_to_#{field}?")
+      end
+    end
+
+    # class methods
+    class_methods do
+      # Define sluggable field
+      # Example:
+      #   sluggable_by :wonderful_name
+      def sluggable_by(field)
+        self.sluggable_field = field.to_sym
+
+        validate_sluggable_field!
+      end
+
+      private
+      # Validate sluggable_field exists in database
+      def validate_sluggable_field!
+        unless column_names.include?(sluggable_field.to_s)
+          raise ArgumentError, "ConcernsOnRails::Sluggable: sluggable_field '#{sluggable_field}' does not exist in the database"
+        end
+      end
+    end
+
+    # Instance methods
+    # Returns the source for the slug
+    # we are calling the class attribute, so we can use it in the lambda
+    # Example:
+    #   record.slug_source
+    def slug_source
+      if self.class.sluggable_field.present? && respond_to?(self.class.sluggable_field)
+        send(self.class.sluggable_field)
+      elsif respond_to?(:title)
+        title
+      else
+        to_s
+      end
+    end
+  end
+end

data/lib/concerns_on_rails/sortable.rb

@@ -0,0 +1,80 @@
+require "active_support/concern"
+require "acts_as_list"
+
+module ConcernsOnRails
+  module Sortable
+    extend ActiveSupport::Concern
+
+    # instance methods
+    # include Sortable in model to enable sorting
+    # Example:
+    #   class Task < ApplicationRecord
+    #     include Sortable
+    #     sortable_by :priority
+    #   end
+    included do
+      # declare class attributes
+      class_attribute :sortable_field
+      class_attribute :sortable_direction
+
+      # set default values
+      self.sortable_field ||= :position
+      self.sortable_direction ||= :asc
+
+      # we cannot use acts_as_list here
+      default_scope { order(sortable_field => sortable_direction) }
+    end
+
+    # class methods
+    # Example: Task.sortable_by(priority: :asc)
+    class_methods do
+      # Define sortable field and direction
+      # Example:
+      #   sortable_by :position
+      #   sortable_by position: :asc
+      #   sortable_by position: :desc
+      #
+      #   sortable_by :position, use_acts_as_list: false
+      def sortable_by(field_config, use_acts_as_list: true)
+        # parse field_config
+        field, direction = parse_sortable_config(field_config)
+
+        # validate direction and must be :asc or :desc
+        direction = :asc unless %i[asc desc].include?(direction)
+
+        # set class attributes
+        self.sortable_field = field
+        self.sortable_direction = direction
+
+        validate_sortable_field!
+
+        # add acts_as_list and default scope
+        # Setup sorting behaviors
+        acts_as_list column: sortable_field if use_acts_as_list
+
+        # add default scope: position => asc
+        default_scope { order(sortable_field => sortable_direction) }
+      end
+
+      private
+      def parse_sortable_config(config)
+        if config.is_a?(Hash)
+          # extract key and value
+          # when we call .first, we get the first key-value pair
+          # Example: { position: :asc }.first => ["position", :asc]
+          key, value = config.first
+          [key.to_sym, value.to_sym]
+        else
+          [config.to_sym, :asc]
+        end
+      end
+
+      # Validate sortable_field exists in database
+      def validate_sortable_field!
+        unless column_names.include?(sortable_field.to_s)
+          raise ArgumentError, "ConcernsOnRails::Sortable: sortable_field '#{sortable_field}' does not exist in the database"
+        end
+      end
+    end
+  end
+end

data/lib/concerns_on_rails/version.rb

@@ -0,0 +1,3 @@
+module ConcernsOnRails
+  VERSION = "1.0.0"
+end

data/lib/concerns_on_rails.rb

@@ -0,0 +1,8 @@
+require "active_support/concern"
+require "concerns_on_rails/version"
+require "concerns_on_rails/sortable"
+require "concerns_on_rails/publishable"
+require "concerns_on_rails/sluggable"
+
+module ConcernsOnRails
+end

metadata

@@ -0,0 +1,97 @@
+--- !ruby/object:Gem::Specification
+name: concerns_on_rails
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Ethan Nguyen
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-04-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: acts_as_list
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.7.5
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.7.5
+- !ruby/object:Gem::Dependency
+  name: friendly_id
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.4'
+description: A collection of plug-and-play ActiveSupport concerns for Rails models
+  and Rails controllers
+email:
+- doctorit@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- README.md
+- lib/concerns_on_rails.rb
+- lib/concerns_on_rails/publishable.rb
+- lib/concerns_on_rails/sluggable.rb
+- lib/concerns_on_rails/sortable.rb
+- lib/concerns_on_rails/version.rb
+homepage: https://github.com/VSN2015/concerns_on_rails
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/VSN2015/concerns_on_rails
+  source_code_uri: https://github.com/VSN2015/concerns_on_rails
+  changelog_uri: https://github.com/VSN2015/concerns_on_rails/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.6
+signing_key:
+specification_version: 4
+summary: Reusable Rails concerns like Sortable, Publishable, and Sluggable
+test_files: []