rails_omnibar 1.3.2 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0139344a382442752e03ba6b2ef807dd0850891de4ddf01db635e5b7d17861d9'
-  data.tar.gz: 38a8b18c48acf9ccde4eac6561815b52c78985ef17f06b80e93eb61af9f6f5c8
+  metadata.gz: 21f584d48006f4dd826813762553d863b7519ff09687c31be568479088314255
+  data.tar.gz: f8341d39b57397f66f334e417fe2920453494eeec017bf304426e4929e7b4488
 SHA512:
-  metadata.gz: b5ae396c06d0b9fab16f4f28cbe9a12079e57bebda679be68f9d92607528b6f634fdf21c4f4cf299f6fe8174ff1fe5933c6c9d1c1df7b80b8c83675ab74f45e1
-  data.tar.gz: 2ba107efc3bae38d13aece39d8d1060305c46de4a2252df5ae41f1b26643972f5efd3e9d0c5206fa147ebf72b08946388c1c8ccc93cc098e6d6e8dbf6bca416b
+  metadata.gz: aa03433d73eb577524f195e3ce9491c2e832c5ccd8995df017fef33b1652d98ca56e76bab0586c3286b3e8c764d0cbbc228bc004b943b83d93a90b5a75cc3c0b
+  data.tar.gz: 8c3192eafac7ea537f5c8924943eb742002ef4bf4bf2388986468ad595c43324c4bbf1b042a80f58cf8cc7f67981ee123485dcf150c7f740788a46750a4649ac

data/.github/workflows/tests.yml

@@ -8,7 +8,7 @@ jobs:
 
     strategy:
       matrix:
-        ruby: [ '2.7', '3.0', 'ruby-head' ]
+        ruby: [ '3.0', 'ruby-head' ]
 
     steps:
       - uses: actions/checkout@v3

data/CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## [1.5.0] - 2024-01-25
+
+### Added
+
+- `RailsOmnibar::add_webadmin_items`
+
+## [1.4.0] - 2023-01-31
+
+### Added
+
+- `RailsOmnibar::auth=` for fine-grained authorization
+- `RailsOmnibar::html_url` for rendering in SPAs
+
+### Fixed
+
+- double execution of commands / queries
+
 ## [1.3.2] - 2023-01-27
 
 ### Fixed

data/Gemfile

@@ -2,3 +2,17 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in rails_omnibar.gemspec
 gemspec
+
+group :development, :test do
+  gem 'activeadmin', '~> 3.0' # to test activeadmin integration
+  gem 'capybara', '~> 3.0'
+  gem 'csv' # needed for activeadmin, standalone on Ruby >= 3.4
+  gem 'devise', '~> 4.8' # to test auth feature
+  gem 'factory_bot_rails', '~> 6.0'
+  gem 'puma', '~> 6.0'
+  gem 'rake', '~> 13.0'
+  gem 'rspec-rails', '~> 5.0'
+  gem 'sqlite3', '>= 1.3.6'
+  gem 'sprockets-rails', '~> 3.4' # for activeadmin
+  gem 'webdrivers', '~> 5.0'
+end

data/README.md

@@ -15,17 +15,11 @@ Add `rails_omnibar` to your bundle and add the following line to your `config/ro
 mount RailsOmnibar::Engine => '/rails_omnibar'
 ```
 
-You can pick any path.
+You can pick any path. See [Authorization](#authorization) for limiting access to the engine.
 
-To limit access, do something like this:
+## Configuration
 
-```ruby
-authenticate :user, ->(user){ user.superadmin? } do
-  mount RailsOmnibar::Engine => '/rails_omnibar'
-end
-```
-
-### Configuration
+### Basic Usage
 
 ```ruby
 # app/lib/omnibar.rb
@@ -52,6 +46,7 @@ Omnibar = RailsOmnibar.configure do |c|
     next unless name = route.name[/^backoffice_(.+)/, 1]
 
     # items can have icons
+    # arrows, cloud, cog, dev, document, home, question, search, sparkle, user, wallet, x
     c.add_item(title: name.humanize, url: route.format({}), icon: :cog)
   end
 
@@ -97,61 +92,130 @@ Render it somewhere. E.g. `app/views/layouts/application.html.erb`:
 <%= Omnibar.render %>
 ```
 
+If you have a fully decoupled frontend, use `Omnibar.html_url` instead, fetch the omnibar HTML from there, and inject it.
+
+### Authorization
+
+You can limit access to commands (e.g. search commands). This will not limit access to plain items.
+
+#### Option 1: globally limit engine access
+
+```ruby
+authenticate :user, ->(user){ user.superadmin? } do
+  mount RailsOmnibar::Engine => '/rails_omnibar'
+end
+```
+
+#### Option 2: use `RailsOmnibar::auth=`
+
+This is useful for fine-grained authorization, e.g. if there is more than one omnibar or multiple permission levels.
+
+```ruby
+# the auth proc is executed in the controller context by default,
+# but can also take the controller and omnibar as arguments
+MyOmnibar.auth = ->{ user_signed_in? }
+MyOmnibar.auth = ->(controller, omnibar:) do
+  controller.user_signed_in? && omnibar.is_a?(NormalUserOmnibar)
+end
+```
+
 ### Using multiple different omnibars
 
 ```ruby
-UserOmnibar  = Class.new(RailsOmnibar).configure { ... }
-AdminOmnibar = Class.new(RailsOmnibar).configure { ... }
+BaseOmnibar = Class.new(RailsOmnibar)
+BaseOmnibar.configure do |c|
+  c.add_item(
+    title: 'Log in',
+    url:    Rails.application.routes.url_helpers.log_in_url
+  )
+end
+
+UserOmnibar = Class.new(RailsOmnibar)
+UserOmnibar.configure do |c|
+  c.auth = ->{ user_signed_in? }
+  c.add_item(
+    title: 'Log out',
+    url:    Rails.application.routes.url_helpers.log_out_url
+  )
+end
+```
+
+Then, in some layout:
 
-UserOmnibar.render
-AdminOmnibar.render
+```erb
+<%= (user_signed_in? ? UserOmnibar : BaseOmnibar).render %>
 ```
 
 ### Other options and usage patterns
 
+#### Adding multiple items at once
+
 ```ruby
-# Add multiple items
 MyOmnibar.add_items(
   *MyRecord.all.map { |rec| { title: rec.title, url: url_for(rec) } }
 )
+```
+
+#### Adding all ActiveAdmin or RailsAdmin index routes as searchable items
+
+Simply call `::add_webadmin_items` and use the `modal` mode.
 
-# Add ActiveAdmin index routes as searchable items
-Admin::UsersController # trigger autoloading (use your own AA namespace)
-ActiveAdmin.application.namespaces.first.resources.each do |res|
-  index = res.route_collection_path rescue next
-  title = res.menu_item&.label.presence || next
-  MyOmnibar.add_item(title: title, url: index)
+```ruby
+MyOmnibar.configure do |c|
+  c.add_webadmin_items
+  c.modal = true
 end
+```
 
-# Render in ActiveAdmin (`MyOmnibar.modal = true` recommended)
+##### To render in ActiveAdmin
+
+```ruby
 module AddOmnibar
   def build_page(...)
     within(super) { text_node(MyOmnibar.render) }
   end
 end
 ActiveAdmin::Views::Pages::Base.prepend(AddOmnibar)
+```
+
+##### To render in RailsAdmin
+
+Add `MyOmnibar.render` to `app/views/layouts/rails_admin/application.*`.
 
-# Add all index routes as searchable items
+#### Adding all index routes as searchable items
+
+```ruby
 Rails.application.routes.routes.each do |route|
   next unless route.defaults.values_at(:action, :format) == ['index', nil]
   MyOmnibar.add_item(title: route.name.humanize, url: route.format({}))
 end
+```
+
+#### Custom record lookup and rendering
 
-# Custom record lookup and rendering
+```ruby
 MyOmnibar.add_record_search(
   pattern:  /^U(\d+)/,
   example:  'U123',
   model:    User,
-  finder:   ->(id)   { User.find_by(admin: true, id: id) },
-  itemizer: ->(user) { { title: "Admin #{user.name}", url: admin_url(user), icon: :user } }
+  finder:   ->(id) { User.find_by(admin: true, id: id) },
+  itemizer: ->(user) do
+    { title: "Admin #{user.name}", url: admin_url(user), icon: :user }
+  end
 )
+```
 
-# Custom search, plus mapping to multiple results
+#### Custom search, plus mapping to multiple results
+
+```ruby
 MyOmnibar.add_search(
   description: 'Google',
   pattern:     /^g (.+)/,
   example:     'g kittens',
-  finder:      ->(value) { GoogleSearch.fetch(value) },
+  # omnibar: and controller: keyword args are provided to command procs
+  finder:      ->(value, omnibar:) do
+    Google.search(value, limit: omnibar.max_results)
+  end,
   itemizer:    ->(res) do
     [
       { title: res.title, url: res.url },
@@ -159,14 +223,21 @@ MyOmnibar.add_search(
     ]
   end,
 )
+```
+
+#### Completely custom command
 
-# Completely custom command
+```ruby
 MyOmnibar.add_command(
   description: 'Get count of a DB table',
   pattern:     /COUNT (.+)/i,
   example:     'COUNT users',
-  resolver:    ->(value, _omnibar) do
-    { title: value.classify.constantize.count.to_s }
+  resolver:    ->(value, controller:) do
+    if controller.current_user.client?
+      { title: (value.classify.constantize.count * 2).to_s }
+    else
+      { title: value.classify.constantize.count.to_s }
+    end
   rescue => e
     { title: e.message }
   end,

data/Rakefile

@@ -16,14 +16,12 @@ task :generate_spec_app do
   sh 'rm -rf spec/dummy'
   sh *%w[
     rails new spec/dummy
-    --template=spec/app_template.rb
+    --template=spec/templates/app_template.rb
     --skip-action-cable
     --skip-action-mailbox
-    --skip-action-mailer
     --skip-action-text
     --skip-active-job
     --skip-active-storage
-    --skip-asset-pipeline
     --skip-bootsnap
     --skip-bundle
     --skip-git
@@ -33,7 +31,6 @@ task :generate_spec_app do
     --skip-keeps
     --skip-listen
     --skip-spring
-    --skip-sprockets
     --skip-system-test
     --skip-test
     --skip-turbolinks

data/app/controllers/rails_omnibar/base_controller.rb

@@ -1,2 +1,5 @@
 class RailsOmnibar::BaseController < ActionController::API
+  def omnibar
+    @omnibar ||= params.fetch('omnibar_class').constantize
+  end
 end

data/app/controllers/rails_omnibar/html_controller.rb

@@ -0,0 +1,5 @@
+class RailsOmnibar::HtmlController < RailsOmnibar::BaseController
+  def show
+    render html: omnibar.render
+  end
+end

data/app/controllers/rails_omnibar/queries_controller.rb

@@ -1,7 +1,7 @@
 class RailsOmnibar::QueriesController < RailsOmnibar::BaseController
   def show
-    omnibar = params['omnibar_class'].constantize
-    res = omnibar.handle(params[:q])
-    render json: omnibar.handle(params[:q])
+    return head :forbidden unless omnibar.authorize(self)
+
+    render json: omnibar.handle(params[:q], self)
   end
 end

data/config/routes.rb

@@ -1,4 +1,5 @@
 RailsOmnibar::Engine.routes.draw do
   resource :js,    only: :show, defaults: { format: :js }
+  resource :html,  only: :show
   resource :query, only: :show
 end