active_scaffold_kanban 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e25b955b58cdedd3c53158c2c0750756e9939033ca0622e14b5e5a74f065ade3
+  data.tar.gz: 6e2809f0242b81621ced3742b04c16d0a288568f6dca7c3f5df88f2448983519
+SHA512:
+  metadata.gz: 61313ca7f2eeaf6317b87f22cb9a526caa48a9406a7c9789503742f7c059a9813d05ffe9ee88496c26cbdb07ad830fef423e177dfc3898a82a3d4937e12337d9
+  data.tar.gz: ed1fde6d9d9f84c8a5473fb122067a568a6b1e8831f846c939c15b41e132d5f30694f14c4c14461ce52bd5f5fe4a8741502a97db42f9e06b51b32da222746357

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Sergio Cambra
+
+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,31 @@
+# Kanban for ActiveScaffold
+
+An addon for ActiveScaffold to render a kanban board instead of normal list, using a model's column for the kanban columns.
+
+## Usage
+
+Add :kanban to actions.
+
+```rb
+active_scaffold :model do |conf|
+  conf.actions << :kanban
+```
+
+Kanban view is used when index action is loaded with `view=kanban` parameter. Default list view can be replaced with kanban with `conf.kanban.replace_list_view = true`.
+
+Then define the column used as kanban columns in the board with `conf.kanban.group_by_column`. It works with both DB column and association.
+The columns for the board are returned with the `kanban_columns` helper, and it uses the same way to get the values as :select form_ui. The helper `kanban_columns` can be overrided, supporting model prefix, but the default helper supports the same methods to define or change the available values:
+  - for single columns, define with `options[:options]` in the column, or override `active_scaffold_enum_options` (supports model prefix)
+  - for associations, define `options_for_association_conditions` or `association_klass_scoped`, model prefix is supported too.
+
+Dragging a card to other column will use `update_column` action, like inplace edit, to change the value. If `update_column` action fails to save, the card is reverted to the original position.
+
+If no position column is defined in sortable, or sortable action is not added, the position on the column can't be changed (drop on the same column reverts to the original position), and the position on the new column is not respected (position may change when kanban is reloaded).
+
+To define a position column, add `:sortable` to `conf.actions`, and define `conf.sortable.column`, then changing the position on the original column will use `reorder` action (as active_scaffold_sortable), and dragging to other column will use `update_action` and will pass the new order to update the order too.
+
+A column may accept items, but don't allow to drag items out. Override `kanban_column_receive_only?` (supports model prefix too) which receives the column value (associated record if the column is an association) and return true for the columns which don't accept to move cards out.
+
+Define the method used for the title with conf.kanban.title_method (defaults to :to_label), and method used for description with conf.kanban.description_method. The card is rendered with `_kanban_card.html.erb` view partial, which can be overrided to change the html structure of a card, and supports model prefix too. Also the `kanban_description` helper can be defined, which supports model prefix, to change only the body of the card. The actions are rendered calling the `kanban_actions` helper, which supports model prefix, or actions can be ignored in kanban by defining ignore_method? in the action_link to skip them if `@kanban_view` variable is set, or overriding `skip_action_link?` helper.
+
+A javascript event `kanban:beforeChange` is fired on the card, when it's drop into other column, before sending the request to update the column. The event receives a object argument with 2 properties, the id of the card and the value of the new column (when column is an association, value is an id too).  If the event listener returns false, it will reject the change, and the card will revert to the original position. The event listener can set extra params to send to the `update_column` action, with `jQuery(event.target).data('params', {key: value})`.

data/app/assets/javascripts/active_scaffold_kanban.js

@@ -0,0 +1,100 @@
+ActiveScaffold.update_positions = function(content) {
+  if (typeof(content) == 'string') content = jQuery('#' + content);
+  var element = content.closest('.sortable-container');
+  jQuery.each(content.find('.sub-form-record input[name$="[' + element.data('column') + ']"]'), function(i, field) {
+    jQuery(field).val(i+1); // don't use 0
+  });
+}
+ActiveScaffold.kanban = function(container) {
+  jQuery.each(jQuery('.kanban', container), function(i, kanban) {
+    kanban = jQuery(kanban);
+
+    var revert = function(item) {
+      var prev = jQuery(item).data('prev_card');
+      if (prev.length) prev.after(item);
+      else jQuery(item).data('prev_column').find('.cards').prepend(item);
+    };
+    var reorder_info = function(column) {
+      var kanban = column.closest('.kanban');
+      return column.sortable('serialize', {
+        key: encodeURIComponent(kanban.data('reorder-key') + '[]'),
+        expression: new RegExp(kanban.data('format'))
+      });
+    }
+
+    var reorder_url = kanban.data('reorder-url'),
+      change_url = kanban.data('change-url'),
+      options = {
+        connectWith: '.active-scaffold .kanban .kanban-column .cards',
+        cancel: '.kanban-column[data-receive-only] .card',
+        start: function(event, ui) {
+          ui.item.data('prev_column', ui.item.closest('.kanban-column'))
+            .data('prev_card', ui.item.prev());
+        },
+        beforeStop: function(event, ui) {
+          event.handleObj.data = jQuery.extend(event.handleObj.data, {column_changed: ui.item.closest('.cards').get(0) !== this});
+          if (!reorder_url) ui.item.cancel = !event.handleObj.data.column_changed;
+        },
+        update: function(event, ui) {
+          if (ui.item.cancel) jQuery(this).sortable('cancel');
+          else if (!event.handleObj.data || !event.handleObj.data.column_changed) {
+            jQuery.ajax({
+              url: reorder_url,
+              data: reorder_info(jQuery(this)),
+              method: 'POST',
+              context: ui.item,
+              error: function(xhr, status, error) {
+                if (xhr.status >= 400) revert(this);
+              }
+            });
+          }
+        },
+        over: function(event, ui) {
+          jQuery(this).addClass('ui-highlight');
+        },
+        out: function(event, ui) {
+          jQuery(this).removeClass('ui-highlight');
+        },
+        receive: function(event, ui) {
+          var $this = jQuery(this), id = ui.item.data('value'),
+            column_value = $this.closest('.kanban-column').data('value'),
+            data = {value: column_value};
+          if (jQuery.rails.fire(ui.item, 'kanban:beforeChange', {id: id, column: column_value})) {
+            jQuery.extend(data, ui.item.data('params') || {});
+            if (reorder_url) data = jQuery.param(data) + '&' + reorder_info($this);
+            jQuery.ajax({
+              url: change_url.replace('--ID--', id),
+              data: data,
+              method: 'POST',
+              context: ui.item,
+              error: function(xhr, status, error) {
+                if (xhr.status >= 400) revert(this);
+              }
+            });
+          } else revert(ui.item);
+        }
+      };
+    kanban.find('.kanban-column .cards').sortable(options);
+    return;
+    if (url) {
+      var csrf = jQuery('meta[name=csrf-param]').attr('content') + '=' + jQuery('meta[name=csrf-token]').attr('content');
+      sortable_options.update = function(event, ui) {
+        var $this = jQuery(this),
+          body = $this.sortable('serialize',{key: encodeURIComponent(($this.data('key') || $this.attr('id')) + '[]'), expression: new RegExp(element.data('format'))});
+        var params = element.data('with');
+        if (params) body += '&' + params;
+        jQuery.post(url, body + '&' + csrf);
+      };
+    }
+  });
+};
+
+jQuery(document).ready(function($) {
+  $(document).on('as:action_success', 'a.as_action', function(e, action_link) {
+    ActiveScaffold.kanban(action_link.adapter);
+  });
+  $(document).on('as:element_updated', function(e) {
+    ActiveScaffold.kanban(e.target);
+  });
+  ActiveScaffold.kanban(document);
+});

data/app/assets/stylesheets/active_scaffold_kanban.scss

@@ -0,0 +1,64 @@
+.active-scaffold .kanban {
+  display: flex;
+  flex-direction: row;
+
+  .kanban-column {
+    display: flex;
+    flex-direction: column;
+    margin-left: 1em;
+    &:first-child {
+      margin-left: 0;
+    }
+
+    .title {
+      margin-bottom: 0.5em;
+    }
+
+    .cards {
+      width: 15em;
+      height: 100%;
+      padding: 4px;
+      border-radius: 5px;
+      &.ui-highlight {
+        background-color: #f8f8f8;
+      }
+    }
+
+    &:not([data-receive-only]) .ui-sortable .card {
+      cursor: grab;
+      &.ui-sortable-helper {
+        cursor: grabbing;
+      }
+    }
+
+    .card {
+      margin-top: 0.5em;
+      border: 1px solid #555;
+      border-radius: 5px;
+      padding: 0.2em 0.4em;
+
+      .card-title {
+        position: relative;
+
+        .actions {
+          position: absolute;
+          display: none;
+          right: 0;
+          top: 1.5em;
+          background: #fff;
+          border: 1px solid #bbb;
+        }
+        &:hover .actions {
+          display: block;
+        }
+      }
+
+      .card-description {
+        font-size: 90%;
+        padding-top: 0.5em;
+        margin-top: 0.5em;
+        border-top: 1px solid #aaa;
+      }
+    }
+  }
+}

data/app/views/active_scaffold_overrides/_kanban.html.erb

@@ -0,0 +1,16 @@
+<% column_receive_only_method = override_helper_per_model(:kanban_column_receive_only?, active_scaffold_config.model) %>
+<%= content_tag :div, class: 'kanban', data: kanban_data_attrs do %>
+<% send(override_helper_per_model(:kanban_columns, active_scaffold_config.model)).each do |label, value| %>
+  <%
+    id = value.id if @kanban_column.association
+    column_data = {value: id || value}
+    column_data[:receive_only] = true if send(column_receive_only_method, value)
+  %>
+  <%= content_tag :div, class: 'kanban-column', data: column_data do %>
+    <div class="title"><%= label %></div>
+    <div class="cards">
+      <%= render partial: 'kanban_card', as: :record, collection: @records.select { |record| record.send(@kanban_column.name) == value } %>
+    </div>
+  <% end %>
+<% end %>
+<% end %>

data/app/views/active_scaffold_overrides/_kanban_card.html.erb

@@ -0,0 +1,12 @@
+<% @kanban_card_body_method ||= override_helper_per_model(:kanban_description, record.class) %>
+<div class="card record" data-value="<%= record.id %>" id="<%= element_row_id(:action => :list, :id => record.id) %>">
+  <div class="card-title">
+    <%= record.send(active_scaffold_config.kanban.title_method) %>
+    <div class="actions">
+      <%= display_action_links(active_scaffold_config.action_links.member, record, for: record) %>
+    </div>
+  </div>
+  <div class="card-description">
+    <%= send(@kanban_card_body_method, record) %>
+  </div>
+</div>

data/app/views/active_scaffold_overrides/_list.html.erb

@@ -0,0 +1,5 @@
+<% if @kanban_view %>
+  <%= render 'kanban' %>
+<% else %>
+  <%= render :super %>
+<% end %>

data/app/views/active_scaffold_overrides/_new_record.js.erb

@@ -0,0 +1,8 @@
+<% if @kanban_view %>
+<%= selector = ".kanban-column[data-value=\"#{@record.send(@kanban_column.name)}\"] .cards" %>
+// ActiveScaffold.create_record_row('<%= active_scaffold_id %>', html, <%= {insert_at: insert_at, body_selector: selector}.to_json.html_safe %>);
+jQuery('<%= selector %>').prepend('<%= escape_javascript render('kanban_card', record: @record) %>');
+jQuery('<%= selector %>').sortable('refresh');
+<% else %>
+<%= render :super %>
+<% end %>

data/app/views/active_scaffold_overrides/update_column.js.erb

@@ -0,0 +1,7 @@
+<% if @kanban_view %>
+<% if successful? %>
+ActiveScaffold.replace('<%= element_row_id(action: :list) %>', '<%= escape_javascript render('kanban_card', record: @record) %>');
+<% end %>
+<% else %>
+<%= render :super %>
+<% end %>

data/lib/active_scaffold/actions/kanban.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module ActiveScaffold
+  module Actions
+    module Kanban
+      def self.included(base)
+        base.before_action :setup_kanban, only: [:index, :update_column, :reorder, :create]
+        base.after_action :reorder_cards, only: :update_column
+        base.after_action :set_error_status_code, only: [:update_column, :reorder]
+      end
+
+      protected
+
+      def setup_kanban
+        return unless params[:view] == 'kanban' || active_scaffold_config.kanban.replace_list_view
+        @kanban_view = true
+        @kanban_column = active_scaffold_config.columns[active_scaffold_config.kanban.group_by_column]
+        active_scaffold_config.list.pagination = nil
+      end
+
+      def reorder_cards
+        reorder if successful? && active_scaffold_config.actions.include?(:sortable) && ordered_ids
+      end
+
+      def set_error_status_code
+        response.status = 400 unless successful?
+      end
+    end
+  end
+end

data/lib/active_scaffold/config/kanban.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module ActiveScaffold
+  module Config
+    class Kanban < Base
+      self.crud_type = :read
+
+      def initialize(core_config)
+        super
+        @title_method = self.class.title_method
+        @description_method = self.class.description_method
+        @replace_list_view = self.class.replace_list_view
+      end
+
+      # global level configuration
+      # --------------------------
+      # the model's method used for card's title
+      cattr_accessor :title_method, instance_accessor: false
+      @@title_method = :to_label
+
+      # the model's method used for card's description, set to nil for no description
+      cattr_accessor :description_method, instance_accessor: false
+
+      # enable it to replace list view with kanban, instead of being optional with view=kanban param
+      cattr_accessor :replace_list_view, instance_accessor: false
+
+      # the model's method used for card's title
+      attr_accessor :title_method
+
+      # the model's method used for card's description, set to nil for no description
+      attr_accessor :description_method
+
+      # enable it to replace list view with kanban, instead of being optional with view=kanban param
+      attr_accessor :replace_list_view
+
+      # the model's column used for kanban columns
+      attr_accessor :group_by_column
+
+      UserSettings.class_eval do
+        user_attr :title_method, :description_method, :group_by_column, :replace_list_view
+      end
+    end
+  end
+end

data/lib/active_scaffold/helpers/kanban_helpers.rb

@@ -0,0 +1,49 @@
+module ActiveScaffold
+  module Helpers
+    module KanbanHelpers
+      def kanban_columns
+        record = active_scaffold_config.model.new
+        if @kanban_column.association
+          sorted_association_options_find(@kanban_column.association, nil, record).map do |record_column|
+            [record_column.send(@kanban_column.options[:label_method] || :to_label), record_column]
+          end
+        else
+          enum_options_method = override_helper_per_model(:active_scaffold_enum_options, record.class)
+          send(enum_options_method, @kanban_column, record).collect do |text, value|
+            text, value = active_scaffold_translated_option(@kanban_column, text, value)
+            value = value.to_s if value.is_a? Symbol
+            [text, value]
+          end
+        end
+      end
+
+      def kanban_column_receive_only?(column_value)
+        false
+      end
+
+      def kanban_description(record)
+        record.send(active_scaffold_config.kanban.description_method) if active_scaffold_config.kanban.description_method
+      end
+
+      def kanban_data_attrs
+        attrs = {
+          change_url: url_for(params_for(action: :update_column, id: '--ID--', column: active_scaffold_config.kanban.group_by_column)),
+          format: '^[^_-](?:[A-Za-z0-9_-]*)-(.*)-row$',
+          reorder_key: active_scaffold_tbody_id
+        }
+        if active_scaffold_config.actions.include?(:sortable) && active_scaffold_config.sortable.column
+          attrs[:reorder_url] = url_for(params_for(action: :reorder, id: nil))
+        end
+        attrs
+      end
+
+      def action_link_html_options(link, record, options)
+        options = super
+        if @kanban_view && link.position == :after
+          options[:data][:position] = :replace
+        end
+        options
+      end
+    end
+  end
+end

data/lib/active_scaffold_kanban/engine.rb

@@ -0,0 +1,9 @@
+module ActiveScaffoldKanban
+  class Engine < ::Rails::Engine
+    initializer 'active_scaffold_kanban.action_view' do
+      ActiveSupport.on_load :action_view do
+        ActionView::Base.send :include, ActiveScaffold::Helpers::KanbanHelpers
+      end
+    end
+  end
+end

data/lib/active_scaffold_kanban/version.rb

@@ -0,0 +1,9 @@
+module ActiveScaffoldKanban
+  module Version
+    MAJOR = 0
+    MINOR = 1
+    PATCH = 0
+
+    STRING = [MAJOR, MINOR, PATCH].compact.join('.')
+  end
+end

data/lib/active_scaffold_kanban.rb

@@ -0,0 +1,20 @@
+require 'active_scaffold_kanban/engine'
+require 'active_scaffold_kanban/version'
+require 'active_scaffold_sortable' # ensure dependent gem is loaded
+
+module ActiveScaffold
+  module Actions
+    ActiveScaffold.autoload_subdir('actions', self, File.dirname(__FILE__))
+  end
+
+  module Config
+    ActiveScaffold.autoload_subdir('config', self, File.dirname(__FILE__))
+  end
+
+  module Helpers
+    ActiveScaffold.autoload_subdir('helpers', self, File.dirname(__FILE__))
+  end
+end
+
+ActiveScaffold.stylesheets << 'active_scaffold_kanban'
+ActiveScaffold.javascripts << 'active_scaffold_kanban'

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification
+name: active_scaffold_kanban
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Sergio Cambra
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-12-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: active_scaffold
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.7.10
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.7.10
+- !ruby/object:Gem::Dependency
+  name: active_scaffold_sortable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.2.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.2.2
+description: User may reorder records and change to a different column
+email: activescaffold@googlegroups.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- LICENSE
+- README.md
+- app/assets/javascripts/active_scaffold_kanban.js
+- app/assets/stylesheets/active_scaffold_kanban.scss
+- app/views/active_scaffold_overrides/_kanban.html.erb
+- app/views/active_scaffold_overrides/_kanban_card.html.erb
+- app/views/active_scaffold_overrides/_list.html.erb
+- app/views/active_scaffold_overrides/_new_record.js.erb
+- app/views/active_scaffold_overrides/update_column.js.erb
+- lib/active_scaffold/actions/kanban.rb
+- lib/active_scaffold/config/kanban.rb
+- lib/active_scaffold/helpers/kanban_helpers.rb
+- lib/active_scaffold_kanban.rb
+- lib/active_scaffold_kanban/engine.rb
+- lib/active_scaffold_kanban/version.rb
+homepage: https://activescaffold.eu
+licenses:
+- MIT
+metadata: {}
+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.5.11
+signing_key:
+specification_version: 4
+summary: Show records as kanban board, using ActiveScaffold
+test_files: []