admin_tools 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2efcc50b8fc94f674ff737feb0f4d1150151cdd23cfaa2cc5b6199ebba6eb286
+  data.tar.gz: 68d78fae2bbffa56d257ed02758eb09261aa3e25e5fdce652d0653c9c34e5a88
+SHA512:
+  metadata.gz: 5abb8c068293a5b09e043f728a752cffb0739ad71fe239cafeefbf30f12215db7777abe710e2407877139c60bc74cc6f4a101afbef9fccf43b1bc163f7af025a
+  data.tar.gz: 1c85c8e1ada5d090635a1b3c142bd13c35c405de2b129415dd5a19ff27d95c89a315183a9097bbf8f1a7679eda3e1e8ce6e421eab486f6eb868101a9f7e8ffb9

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2025-11-26
+
+### Added
+
+- Initial release
+- `admin_tool` helper for wrapping admin-only content
+- `admin_tool_if` helper for conditional admin content
+- `admin_tools_visible?` helper for checking admin status
+- Configurable current user method, admin check method, CSS class, and wrapper element
+- Install generator with optional CSS generation
+- Tailwind CSS support

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Jasper
+
+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,193 @@
+# AdminTools
+
+A lightweight Rails gem for conditionally rendering admin-only content in views. Wrap any content in an `admin_tool` block and it only renders for admin users.
+
+Inspired by [HCB's admin tools pattern](https://github.com/hackclub/hcb).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "admin_tools"
+```
+
+And then execute:
+
+```bash
+bundle install
+rails generate admin_tools:install
+```
+
+## Usage
+
+### Basic Usage
+
+Use the `admin_tool` helper in your views to wrap content that should only be visible to admins:
+
+```erb
+<% admin_tool do %>
+  <%= link_to "Edit", edit_admin_path(@resource) %>
+  <%= button_to "Delete", @resource, method: :delete %>
+<% end %>
+```
+
+Non-admin users see nothing. Admin users see the content wrapped in a `<div class="admin-tools">`.
+
+### With CSS Classes
+
+Pass additional CSS classes (great for Tailwind):
+
+```erb
+<% admin_tool("w-fit bg-red-50 p-2 rounded") do %>
+  <p>Admin-only debugging info: <%= @resource.inspect %></p>
+<% end %>
+```
+
+### Different Wrapper Element
+
+Change the wrapper element type:
+
+```erb
+<% admin_tool("inline-flex gap-2", :span) do %>
+  <span>Admin badge</span>
+<% end %>
+```
+
+### With HTML Attributes
+
+Pass additional HTML attributes:
+
+```erb
+<% admin_tool("", :div, data: { controller: "admin-panel" }, id: "admin-tools") do %>
+  <%= render "admin/quick_actions" %>
+<% end %>
+```
+
+### Conditional Admin Content
+
+Use `admin_tool_if` when you want content visible to everyone OR just admins based on a condition:
+
+```erb
+<%# Show unpublish button only to admins when post is published %>
+<% admin_tool_if(@post.published?) do %>
+  <%= link_to "Unpublish", unpublish_path(@post) %>
+<% end %>
+```
+
+When the condition is `false`, content shows to everyone. When `true`, only admins see it.
+
+### Check Admin Visibility
+
+You can also check visibility directly:
+
+```erb
+<% if admin_tools_visible? %>
+  <p>You're an admin!</p>
+<% end %>
+```
+
+## Configuration
+
+Run the generator to create an initializer:
+
+```bash
+rails generate admin_tools:install
+```
+
+Then customize `config/initializers/admin_tools.rb`:
+
+```ruby
+AdminTools.configure do |config|
+  # Method to call to get the current user (default: :current_user)
+  config.current_user_method = :current_user
+
+  # Method to call on the user to check if they're an admin (default: :admin?)
+  config.admin_method = :admin?
+
+  # CSS class applied to all admin_tool wrappers (default: "admin-tools")
+  config.css_class = "admin-tools"
+
+  # Default HTML element for wrapping content (default: :div)
+  config.wrapper_element = :div
+end
+```
+
+### Examples
+
+**Using Devise with a `role` column:**
+
+```ruby
+config.current_user_method = :current_user
+config.admin_method = :admin?  # assumes User#admin? exists
+```
+
+**Using a different auth system:**
+
+```ruby
+config.current_user_method = :authenticated_user
+config.admin_method = :has_admin_role?
+```
+
+**Using Pundit or similar:**
+
+```ruby
+# In your ApplicationController
+def admin_user?
+  current_user&.admin? || policy(current_user).admin?
+end
+helper_method :admin_user?
+
+# In initializer - call a helper method instead
+config.admin_method = :itself  # Always returns truthy for non-nil users
+# Then override admin_tools_visible? in ApplicationHelper:
+#
+# def admin_tools_visible?
+#   admin_user?
+# end
+```
+
+## Styling
+
+Generate optional CSS to visually distinguish admin tools:
+
+```bash
+# Standard CSS
+rails generate admin_tools:install --css
+
+# Tailwind CSS
+rails generate admin_tools:install --css --tailwind
+```
+
+This creates `app/assets/stylesheets/admin_tools.css` with a dashed red border and "Admin" label. Customize or remove in production as needed.
+
+## Requirements
+
+- Rails >= 6.1
+- Ruby >= 3.0
+- A `current_user` method (or configured equivalent) that returns the logged-in user
+- An `admin?` method (or configured equivalent) on your User model
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests.
+
+## Releasing
+
+1. Update the version in `lib/admin_tools/version.rb`
+2. Update `CHANGELOG.md`
+3. Commit: `git commit -am "Release vX.X.X"`
+4. Tag: `git tag vX.X.X`
+5. Push: `git push origin main --tags`
+
+The GitHub Action will automatically publish to RubyGems.org.
+
+> **Note:** You need to configure [Trusted Publishing](https://guides.rubygems.org/trusted-publishing/) on RubyGems.org and create a `release` environment in your GitHub repo settings.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/admin_tools.gemspec

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "lib/admin_tools/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "admin_tools"
+  spec.version = AdminTools::VERSION
+  spec.authors = ["Jasper Mayone"]
+  spec.email = ["me@jaspermayone.com"]
+
+  spec.summary = "Simple admin-only content helpers for Rails views"
+  spec.description = "A lightweight Rails helper for conditionally rendering admin-only content in views. Wrap any content in an admin_tool block and it only renders for admin users."
+  spec.homepage = "https://github.com/jasper/admin_tools"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile])
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "rails", ">= 6.1"
+end

data/lib/admin_tools/configuration.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module AdminTools
+  class Configuration
+    attr_accessor :current_user_method, :admin_method, :css_class, :wrapper_element
+
+    def initialize
+      @current_user_method = :current_user
+      @admin_method = :admin?
+      @css_class = "admin-tools"
+      @wrapper_element = :div
+    end
+  end
+end

data/lib/admin_tools/helper.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module AdminTools
+  module Helper
+    # Renders content only for admin users
+    #
+    # @param class_name [String] Additional CSS classes to add to the wrapper
+    # @param element [Symbol, String] HTML element to wrap content in (default: configured wrapper_element)
+    # @param options [Hash] Additional HTML attributes for the wrapper element
+    # @yield Block containing the content to render for admins
+    #
+    # @example Basic usage
+    #   <% admin_tool do %>
+    #     <%= link_to "Delete", resource_path, method: :delete %>
+    #   <% end %>
+    #
+    # @example With CSS classes
+    #   <% admin_tool("w-fit bg-red-50 p-2") do %>
+    #     <p>Admin-only content</p>
+    #   <% end %>
+    #
+    # @example With different wrapper element
+    #   <% admin_tool("inline-flex", :span) do %>
+    #     Admin badge
+    #   <% end %>
+    #
+    # @example With HTML attributes
+    #   <% admin_tool("", :div, data: { controller: "admin" }) do %>
+    #     <%= render "admin/panel" %>
+    #   <% end %>
+    #
+    def admin_tool(class_name = "", element = nil, **options, &block)
+      return unless admin_tools_visible?
+
+      element ||= AdminTools.configuration.wrapper_element
+      css_classes = [AdminTools.configuration.css_class, class_name].reject(&:blank?).join(" ")
+
+      concat content_tag(element, class: css_classes, **options, &block)
+    end
+
+    # Conditionally renders content for admins only based on a condition
+    #
+    # If condition is false, content is shown to ALL users.
+    # If condition is true, content is only shown to admins.
+    #
+    # @param condition [Boolean] When true, restrict to admins only
+    # @param args [Array] Arguments passed to admin_tool
+    # @param options [Hash] Options passed to admin_tool
+    # @yield Block containing the content
+    #
+    # @example Show draft badge to everyone, but admin actions only to admins
+    #   <% admin_tool_if(@post.published?) do %>
+    #     <%= link_to "Unpublish", unpublish_path(@post) %>
+    #   <% end %>
+    #
+    def admin_tool_if(condition, *args, **options, &block)
+      yield and return unless condition
+
+      admin_tool(*args, **options, &block)
+    end
+
+    # Returns whether admin tools should be visible to the current user
+    #
+    # @return [Boolean]
+    #
+    def admin_tools_visible?
+      user = send(AdminTools.configuration.current_user_method)
+      return false if user.nil?
+
+      user.send(AdminTools.configuration.admin_method)
+    rescue NoMethodError
+      false
+    end
+  end
+end

data/lib/admin_tools/railtie.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module AdminTools
+  class Railtie < ::Rails::Railtie
+    initializer "admin_tools.helper" do
+      ActiveSupport.on_load(:action_view) do
+        include AdminTools::Helper
+      end
+    end
+  end
+end

data/lib/admin_tools/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module AdminTools
+  VERSION = "0.1.0"
+end

data/lib/admin_tools.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "admin_tools/version"
+require_relative "admin_tools/configuration"
+require_relative "admin_tools/helper"
+require_relative "admin_tools/railtie" if defined?(Rails::Railtie)
+
+module AdminTools
+  class << self
+    attr_writer :configuration
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

data/lib/generators/admin_tools/install/install_generator.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module AdminTools
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates an AdminTools initializer and optional CSS file"
+
+      class_option :css, type: :boolean, default: false, desc: "Generate CSS file with default styles"
+      class_option :tailwind, type: :boolean, default: false, desc: "Use Tailwind CSS classes in generated CSS"
+
+      def create_initializer
+        template "initializer.rb", "config/initializers/admin_tools.rb"
+      end
+
+      def create_css_file
+        return unless options[:css]
+
+        if options[:tailwind]
+          template "admin_tools_tailwind.css", "app/assets/stylesheets/admin_tools.css"
+        else
+          template "admin_tools.css", "app/assets/stylesheets/admin_tools.css"
+        end
+      end
+
+      def show_readme
+        readme "README" if behavior == :invoke
+      end
+    end
+  end
+end

data/lib/generators/admin_tools/install/templates/README

@@ -0,0 +1,24 @@
+
+===============================================================================
+
+AdminTools has been installed!
+
+Next steps:
+
+1. Update config/initializers/admin_tools.rb if you need to customize:
+   - The method used to get the current user
+   - The method used to check if a user is an admin
+   - The default CSS class or wrapper element
+
+2. Use admin_tool in your views:
+
+   <%% admin_tool do %>
+     <%%= link_to "Admin Action", admin_path %>
+   <%% end %>
+
+3. (Optional) Add CSS to style admin tools visually:
+
+   rails generate admin_tools:install --css
+   rails generate admin_tools:install --css --tailwind
+
+===============================================================================

data/lib/generators/admin_tools/install/templates/admin_tools.css

@@ -0,0 +1,41 @@
+/*
+ * AdminTools default styles
+ * These styles help visually distinguish admin-only content during development
+ */
+
+.admin-tools {
+  border: 2px dashed #ec3750;
+  background-color: rgba(236, 55, 80, 0.05);
+  padding: 0.5rem;
+  border-radius: 0.25rem;
+  position: relative;
+}
+
+/* Optional: Add an "Admin" label */
+.admin-tools::before {
+  content: "Admin";
+  position: absolute;
+  top: -0.75rem;
+  left: 0.5rem;
+  background-color: #ec3750;
+  color: white;
+  font-size: 0.625rem;
+  font-weight: 600;
+  padding: 0.125rem 0.375rem;
+  border-radius: 0.25rem;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+
+/* Remove visual styling in production if desired */
+/*
+.admin-tools--production {
+  border: none;
+  background: none;
+  padding: 0;
+}
+
+.admin-tools--production::before {
+  display: none;
+}
+*/

data/lib/generators/admin_tools/install/templates/admin_tools_tailwind.css

@@ -0,0 +1,14 @@
+/*
+ * AdminTools Tailwind styles
+ * Uses Tailwind's @apply directive for styling
+ */
+
+.admin-tools {
+  @apply border-2 border-dashed border-red-500 bg-red-50/50 p-2 rounded relative;
+}
+
+/* Optional: Add an "Admin" label */
+.admin-tools::before {
+  content: "Admin";
+  @apply absolute -top-2.5 left-2 bg-red-500 text-white text-xs font-semibold px-1.5 py-0.5 rounded uppercase tracking-wide;
+}

data/lib/generators/admin_tools/install/templates/initializer.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+AdminTools.configure do |config|
+  # Method to call to get the current user (default: :current_user)
+  # config.current_user_method = :current_user
+
+  # Method to call on the user to check if they're an admin (default: :admin?)
+  # config.admin_method = :admin?
+
+  # CSS class applied to all admin_tool wrappers (default: "admin-tools")
+  # config.css_class = "admin-tools"
+
+  # Default HTML element for wrapping content (default: :div)
+  # config.wrapper_element = :div
+end

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification
+name: admin_tools
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jasper Mayone
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+description: A lightweight Rails helper for conditionally rendering admin-only content
+  in views. Wrap any content in an admin_tool block and it only renders for admin
+  users.
+email:
+- me@jaspermayone.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- admin_tools.gemspec
+- lib/admin_tools.rb
+- lib/admin_tools/configuration.rb
+- lib/admin_tools/helper.rb
+- lib/admin_tools/railtie.rb
+- lib/admin_tools/version.rb
+- lib/generators/admin_tools/install/install_generator.rb
+- lib/generators/admin_tools/install/templates/README
+- lib/generators/admin_tools/install/templates/admin_tools.css
+- lib/generators/admin_tools/install/templates/admin_tools_tailwind.css
+- lib/generators/admin_tools/install/templates/initializer.rb
+homepage: https://github.com/jasper/admin_tools
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/jasper/admin_tools
+  source_code_uri: https://github.com/jasper/admin_tools
+  changelog_uri: https://github.com/jasper/admin_tools/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: Simple admin-only content helpers for Rails views
+test_files: []