cable_modal 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f0bbdd38fb8edb2a7fda04b883f73a5194e5367886ddbb276b1e5b03d190d835
+  data.tar.gz: 1fa914c7baa60f73a33dffca06bbf97eab726b27d56bd7cdae8e1f82f3112141
+SHA512:
+  metadata.gz: 1a74de7c534c22bdc69477378e847de1372911d1c07c6b8a55f701010256d21e34215aa1bc7e2b787a78910986b115099bd820d49ab0ea1486c0fc5919494a26
+  data.tar.gz: 74c207904600ef061b4f243114f36d512d42e728368eb43be8964909c98bd2e3e3d0253f08037767dcc23fe7b0f33954af3dcdbefce05c4709a4f40fcd0f98b6

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2021 Rafe Rosen
+
+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,115 @@
+# CableModal
+This plugin facilitates creating server-rendered modal workflows in Rails using [CableReady](https://cableready.stimulusreflex.com) custom operations.  A plugin system is provided to allow you to use your modal provider of choice.  A plugin for Bootstrap 5 is provided and used in these examples.
+
+The plugin provides a `<cable-modal>` web component and a set of custom CableReady operations for controlling it.  Once the `<cable-modal>` element is on the page, you can control it with the following operations:
+
+- `openModal()`
+- `closeModal()`
+- `updateModal({html: "HTML string for modal content"})`
+
+![Demo screencast](/demo.gif)
+
+## Installation
+First install the gem
+
+```bash
+$ bundle add cable_modal
+```
+
+Next install the npm package
+
+```bash
+$ yarn add cable_modal
+```
+
+Finally, run the generator
+
+```
+$ bin/rails g cable_modal:install
+```
+
+The generator does three things:
+
+1. installs a `<cable-modal>` web component into your `application.html.erb` layout
+3. installs a `cable_modal.html.erb` template into `app/views/layouts`.  Use this layout to assist with rendering modal content.
+2. adds intialization code to `application.js`
+
+## Usage with Mrujs / CableCar
+
+This gem adds 3 custom operations you can use anywhere you use CableReady:
+- openModal
+- closeModal
+- updateModal
+
+A great way to to use these to control the custom modal is with [mrujs](https://mrujs.com) and the [cable_car feature](https://cableready.stimulusreflex.com/v/v5/cable-car) added in CableReady 5.  Here's an example.
+
+First you'll want to set up mrujs with the CableCar plugin.  Follow the [instructions in the mrujs docs](https://mrujs.com/how-tos/integrate-cablecar).
+
+Now you can add `data-cable-car` to any links or forms you want to use to control the modal.
+
+```html
+  <a href="/confirmations/new" data-cable-car>Open Confirmation in Modal</a>
+
+  <!-- OR -->
+
+  <form action="/confirmations" data-cable-car>
+    <button>Submit form and process result in modal</button>
+  </form>
+```
+
+Then in your controllers, process the request and use `render operations:` to send CableReady operations back to the client.
+
+```ruby
+  # confirmations_controller.rb
+
+  def new
+    @confirmation = Confirmation.new
+    render operations: cable_car
+      .update_modal(
+        html: self.class.render(
+          template: "confirmations/new",
+          assigns: {confirmation: @confirmation},
+          layout: "cable_modal",
+        ))
+      .open_modal
+  end
+
+  def create
+    @confirmation = Confirmation.new(confirmation_params)
+    if @confirmation.save
+      render operations: cable_car.close_modal
+    else
+      render operations: cable_car.update_modal(
+        html: self.class.render(
+          template: "confirmations/new",
+          assigns: {confirmation: @confirmation},
+          layout: "cable_modal",
+        ))
+    end
+  end
+```
+
+## Customization
+
+If you don't want to use Bootstrap's modals, you can write your own plugin and then pass it to `CableModal.use(plugin)` in your javascript initializion.
+
+Plugins are plain javascript objects with the following properties:
+
+```javascript
+  {
+    connect() {}, // runs when the <cable-modal> component is added
+    disconnect() {}, // runs when the <cable-modal> component is removed
+    openModal: (operation) -> {}, // open the modal
+    closeModal: (operation) -> {}, // close the modal
+    updateModal: (operation) -> {}, // update the modal's content
+    defaultContent: string // default innerHTML of the <cable-modal> component
+  }
+```
+
+Note that all functions will run bound to the `<cable-modal>` DOM node.  You can access the original plugin object inside these bound functions by calling `this.plugin`.
+
+## Contributing
+Issues and pull requests are welcome.
+
+## 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,18 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+load "rails/tasks/statistics.rake"
+
+require "bundler/gem_tasks"
+
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.pattern = "test/**/*_test.rb"
+  t.verbose = false
+end
+
+task default: :test

data/lib/cable_modal.rb

@@ -0,0 +1,6 @@
+require "cable_modal/version"
+require "cable_modal/engine"
+
+module CableModal
+  # Your code goes here...
+end

data/lib/cable_modal/engine.rb

@@ -0,0 +1,13 @@
+require "cable_ready"
+
+module CableModal
+  class Engine < ::Rails::Engine
+    initializer "cable_modal.operations" do
+      CableReady.configure do |config|
+        config.add_operation_name :open_modal
+        config.add_operation_name :update_modal
+        config.add_operation_name :close_modal
+      end
+    end
+  end
+end

data/lib/cable_modal/version.rb

@@ -0,0 +1,3 @@
+module CableModal
+  VERSION = "0.1.0"
+end

data/lib/generators/cable_modal/install_generator.rb

@@ -0,0 +1,44 @@
+class CableModal::InstallGenerator < Rails::Generators::Base
+  class_option :skip_application_layout, type: "boolean", default: false, desc: "Don't modify application layout"
+  class_option :skip_javascript, type: "boolean", default: false, desc: "Don't modify application javascript"
+  class_option :skip_modal_layout, type: "boolean", default: false, desc: "Don't install a custom layout for your modal content"
+  class_option :application_layout, type: "string", default: "app/views/layouts/application.html.erb", desc: "Specify a custom layout install target"
+  class_option :javascript, type: "string", default: "app/javascript/packs/application.js", desc: "Specify a custom javascript install target"
+  class_option :plugin, type: "string", default: "bootstrap", desc: "Specify your modal provider plugin.  Currently bootstrap (5) is the only provided option. You can always configure custom plugins in your application scripts."
+
+  source_root File.expand_path("../templates", __FILE__)
+
+  def install
+    install_application_layout unless options.skip_application_layout?
+    install_modal_content_layout unless options.skip_modal_layout?
+    install_javascript unless options.skip_javascript?
+  end
+
+  private
+
+  def install_application_layout
+    insert_into_file options.application_layout, "  <cable-modal></cable-modal>\n  ", before: "</body>"
+  end
+
+  def install_javascript
+    append_to_file "app/javascript/packs/application.js", File.read(javascript_template)
+  end
+
+  def install_modal_content_layout
+    copy_file modal_layout_template, "app/views/layouts/cable_modal.html.erb"
+  end
+
+  def javascript_template
+    case options.plugin
+    when "bootstrap" then File.expand_path("../templates/init_bootstrap.js", __FILE__)
+    else raise "Unrecognized plugin `#{options.plugin}`"
+    end
+  end
+
+  def modal_layout_template
+    case options.plugin
+    when "bootstrap" then "layouts/cable_modal/bootstrap.html.erb"
+    else raise "Unrecognized plugin `#{options.plugin}`"
+    end
+  end
+end

data/lib/generators/cable_modal/templates/init_bootstrap.js

@@ -0,0 +1,5 @@
+
+// Initialize CableModal using Bootstrap plugin
+import { CableModal, Bootstrap } from "cable_modal"
+import { Modal } from "bootstrap"
+CableModal.use(new Bootstrap(Modal))

data/lib/generators/cable_modal/templates/layouts/cable_modal/bootstrap.html.erb

@@ -0,0 +1,14 @@
+<% if content_for?(:cable_modal_header) %>
+  <div class="modal-header">
+    <%= content_for(:cable_modal_header) %>
+    <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
+  </div>
+<% end %>
+<div class="modal-body">
+  <%= yield %>
+</div>
+<% if content_for?(:cable_modal_footer) %>
+  <div class="modal-footer">
+    <%= content_for(:cable_modal_footer) %>
+  </div>
+<% end %>

data/lib/tasks/cable_modal_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :cable_modal do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,114 @@
+--- !ruby/object:Gem::Specification
+name: cable_modal
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Rafe Rosen
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2021-08-22 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.4
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 6.1.4
+- !ruby/object:Gem::Dependency
+  name: cable_ready
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 5.0.0pre2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 5.0.0pre2
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: This library provides a set of CableReady operations for driving server-rendered
+  modal form workflows in Rails.  Right now it provides an adapter for Bootstrap 5.
+  Plugins for other modal libraries may be added in the future.
+email:
+- rafe@existentialmutt.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- lib/cable_modal.rb
+- lib/cable_modal/engine.rb
+- lib/cable_modal/version.rb
+- lib/generators/cable_modal/install_generator.rb
+- lib/generators/cable_modal/templates/init_bootstrap.js
+- lib/generators/cable_modal/templates/layouts/cable_modal/bootstrap.html.erb
+- lib/tasks/cable_modal_tasks.rake
+homepage: https://github.com/existentialmutt/cable_modal
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/existentialmutt/cable_modal
+  source_code_uri: https://github.com/existentialmutt/cable_modal
+  changelog_uri: https://github.com/existentialmutt/cable_modal/releases
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '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: "Modal form workflows, powered by CableReady operations and \U0001F9E1"
+test_files: []