kadmin 0.1.7 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e9d50b4cc493eab605ce1ba63e1652c57f4cebda
-  data.tar.gz: 916d45a69e5a1e2a751a8bae2e87237e42ea2e15
+  metadata.gz: 6ab1df6f025d446075d7ea0ff8e6f5e6267e5048
+  data.tar.gz: e01b485202b100b31014c57680fe99ded5017518
 SHA512:
-  metadata.gz: 8ce32466d84c80136a4bc37543bb5d34c1b73792a02a8d7b6cfc2022b924aff030d90a7f0d2126658f8166b7d5a8264f145907dd94effac247404f33ca5a4dac
-  data.tar.gz: 861b60839df2cf82d6e338869d4157d35a641eab80d05680aa7a8672ed0968ecc1ed277bdbe22667309207cb49a0c2189c25da1ff7c31940934ab4a37300f6e3
+  metadata.gz: 221c1f51318638636bbafbd2c7dd135cd21f69f0cf4df6edbd97be4eda02ee07e2b3013a041aa9138b4c106eaf296747f0139ee7df80d6ff1e7392260cbd944e
+  data.tar.gz: cbc7767909e0b85ff93f7fa6ee6a08d4d03d57ac4ad0db975b35f9d8b79fd17bc487f290313c25f8e3f712aadb0fc4f588583f572631cb081984632b6f7926ef

data/README.md

@@ -1,6 +1,6 @@
 # Kadmin
 
-[![GitHub release](https://img.shields.io/badge/release-0.1.7-blue.png)](https://github.com/barcoo/kadmin/releases/tag/0.1.7)
+[![GitHub release](https://img.shields.io/badge/release-0.2.2-blue.png)](https://github.com/barcoo/kadmin/releases/tag/0.2.2)
 
 Collection of utility, configuration, etc., for admin areas in different projects.
 
@@ -33,3 +33,11 @@ When you want to create a new release, use the rake task ```cim:release``` (in t
 ```shell
 bundle exec rake cim:release
 ```
+
+## Roadmap
+
+TODOs:
+
+* [ ] Finish form objects (destruction and creation) + tests + examples
+* [ ] Make a generic typehead-select form object
+* [x] Wrap Finder objects + view helpers

data/app/assets/stylesheets/kadmin/application.scss

@@ -2,6 +2,15 @@
 @import "bootstrap-sprockets";
 @import "bootstrap";
 
+/**
+ * Highlights fields properly when they have errors
+ * Rails automatically appends .field_with_errors on any form element whose model
+ * attributes has an error (as marked in model.errors)
+ */
+.field_with_errors {
+  @extend .has-error;
+}
+
 a.thumbnail {
   max-width: 100%;
   overflow: hidden;

data/app/decorators/kadmin/finder_decorator.rb

@@ -0,0 +1,33 @@
+module Kadmin
+  class FinderDecorator
+    # @return [Kadmin::Finder] underlying finder model
+    attr_reader :finder
+
+    delegate :filters, :scope, :results, to: :finder
+
+    def initialize(finder)
+      @finder = finder
+    end
+
+    # @return [String] human readable, singular/plural form of the finder's model
+    def resource_name
+      return @finder.scope.model_name.human(count: pager.displayed_items)
+    end
+
+    # @return [String] a description of the current applied filters
+    def applied_filters
+      filters = @finder.filters.reduce([]) do |acc, (name, filter)|
+        next(acc) if filter.value.blank?
+        acc << %(<strong>#{filter.value}</strong> on <em>#{name}</em>).html_safe
+      end
+      applied_filters = "(filtering: #{filters.join('; ')})" unless filters.empty?
+
+      return applied_filters
+    end
+
+    # @return [Kadmin::PagerDecorator] decorated pager of the underlying finder
+    def pager
+      return @pager ||= Kadmin::PagerDecorator.new(@finder.pager)
+    end
+  end
+end

data/app/decorators/kadmin/pager_decorator.rb

@@ -0,0 +1,33 @@
+module Kadmin
+  class PagerDecorator
+    # @return [Kadmin::Pager] underlying pager model
+    attr_reader :pager
+
+    delegate :total, :size, :offset, :pages, :current_page, :contains?, :next_page?,
+      :previous_page?, :offset_at, :current_page?,
+      to: :pager
+
+    def initialize(pager)
+      @pager = pager
+    end
+
+    # @return [Integer] the current number of items displayed for this page
+    def displayed_items
+      return page_end - offset
+    end
+
+    # @return [Integer] the index number of the last item for this page
+    def page_end
+      return [next_page_offset, total].min
+    end
+
+    # @return [Integer] the index number of the start item for this page
+    def page_start
+      return offset + 1
+    end
+
+    def next_page_offset
+      return @pager.offset_at(current_page + 1)
+    end
+  end
+end

data/app/views/kadmin/components/_finder.html.erb

@@ -0,0 +1,18 @@
+<%= render partial: 'kadmin/components/finder/header', locals: { finder: finder } %>
+
+<div class='container-fluid'>
+  <% if finder.filters.present? %>
+    <div class='row'>
+      <%= render partial: 'kadmin/components/finder/form', locals: { finder: finder } %>
+    </div>
+  <% end %>
+
+  <div class='row' style='padding-top: 15px'>
+    <% if finder.results.empty? %>
+      <%= render partial: 'kadmin/components/finder/empty', locals: { finder: finder } %>
+    <% else %>
+      <%= yield %>
+      <%= paginate(finder.pager, [15, 30, 50, 100]) %>
+    <% end %>
+  </div>
+</div>

data/app/views/kadmin/components/finder/_empty.html.erb

@@ -0,0 +1,3 @@
+<div class='jumbotron'>
+  <p><%= t('kadmin.components.finder.empty') %></p>
+</div>

data/app/views/kadmin/components/finder/_form.erb

@@ -0,0 +1,10 @@
+<%= form_tag(request.path, method: 'get', class: 'form-inline') do %>
+  <div class='form-group'>
+    <%= link_to('Create', url_for(action: :new), class: 'btn btn-primary') %>
+    <% finder.filters.each do |name, filter| %>
+      <%= text_field_tag("filter_#{name}", filter&.value, class: 'form-control', placeholder: "Filter by #{name}...") %>
+    <% end %>
+    <%= submit_tag('Filter', class: 'btn btn-default form-control') %>
+    <%= link_to('Clear', request.path, class: 'btn btn-danger form-control') %>
+  </div>
+<% end %>

data/app/views/kadmin/components/finder/_header.html.erb

@@ -0,0 +1,7 @@
+<div class="page-header">
+  <h2>
+    Showing <%= finder.resource_name.downcase %>
+    <%= finder.pager.page_start %> - <%= finder.pager.page_end %>
+    <small>out of <%= finder.pager.total %> <%= finder.applied_filters %></small>
+  </h2>
+</div>

data/app/views/kadmin/helpers/_form_errors.html.erb

@@ -0,0 +1,10 @@
+<% if model.errors.present? %>
+  <%= alert('danger') do %>
+    <p><%= glyphicon('exclamation-sign') %> <%= t('kadmin.forms.please_correct') %></p>
+    <ul>
+      <% model.errors.full_messages.each do |message| %>
+        <li><%= message.html_safe %></li>
+      <% end %>
+    </ul>
+  <% end %>
+<% end %>

data/app/views/layouts/kadmin/application.html.erb

@@ -46,7 +46,7 @@
         <% if content_for?(:sidebar) %>
           <!-- main -->
           <div class="col-sm-8 col-md-8 col-lg-9 main">
-            <%= render partial: 'kadmin/alerts' %>
+            <%= render partial: 'kadmin/helpers/alerts' %>
             <%= yield %>
           </div>
           <!-- sidebar -->
@@ -55,7 +55,7 @@
           </div>
         <% else %>
           <div class="col-sm-12 col-md-12 main">
-            <%= render partial: 'kadmin/alerts' %>
+            <%= render partial: 'kadmin/helpers/alerts' %>
             <%= yield %>
           </div>
         <% end %>

data/config/locales/de.yml

@@ -6,9 +6,14 @@ de:
       please_login: Bitte melden Sie sich an
       unauthorized: Unberechtigte Zugriff
       unauthorized_message: Sie haben für die gewünschte Seite leider keine Zugriffsrechte; falls Sie haben sollten, bitte das Apps & Services Team kontaktieren
+    components:
+      finder:
+        empty: Nichts zu zeigen
     dash_message: Schaue Dir mal die Bereiche in der Navigationsleiste oben. Wenn es irgenwelche Probleme gibt, oder es fehlt Dir Zugriffsrechte, bitte das Apps & Services Team kontaktieren.
     error: Fehler
     errors:
       not_found: Objekt nicht gefunden
       params_missing: Fehlenden erforderlichen Parameter
+    forms:
+      please_correct: "Bitte die folgende Felde korrigieren:"
     welcome: Willkommen zurück, %{user}!

data/config/locales/en.yml

@@ -6,9 +6,14 @@ en:
       please_login: Please authenticate yourself
       unauthorized: Unauthorized access
       unauthorized_message: You are not authorized to access this resource; if you think you should be, contact the Apps & Services team
+    components:
+      finder:
+        empty: Nothing to show
     dash_message: See the top navigation bar for the different admin sections. If you are missing authorizations, or if there is any issue at all, contact the Apps & Services team!
     error: Error
     errors:
       not_found: Requested object not found
       params_missing: Missing required parameters
+    forms:
+      please_correct: "Please correct the following:"
     welcome: Welcome %{user}!

data/lib/kadmin/finder.rb

@@ -17,16 +17,19 @@ module Kadmin
       @scope = scope
       @pager = nil
       @filters = {}
+      @results = nil
     end
 
     # @param [String] name the filter name (should be unique)
     # @param [String, Array<String>] column the column(s) name to filter on
     # @param [String, Array<String>] value the value or values to look for (OR'd)
     def filter(name:, column:, value:)
-      if column.present? && value.present? && !@filters.key?(name)
+      if column.present? && !@filters.key?(name)
         @filters[name] = Kadmin::Finder::Filter.new(column, value)
-        @scope = @scope.where("#{@scope.table_name}.`#{column}` LIKE ?", value.tr('*', '%'))
-        @pager&.total = @scope.count
+        if value.present?
+          @scope = @scope.where("#{@scope.table_name}.`#{column}` LIKE ?", value.tr('*', '%'))
+          @pager&.total = @scope.count
+        end
       end
 
       return self
@@ -47,10 +50,16 @@ module Kadmin
     end
 
     # @return [ActiveRecord::Relation] the filtered (and optionally paginated) results
-    def find
-      results = @scope
-      results = @pager.page(results) unless @pager.nil?
+    def results
+      return @results ||= begin
+        results = @scope
+        results = @pager.page(results) unless @pager.nil?
+        results
+      end
+    end
 
+    def find!
+      @results = nil
       return results
     end
   end

data/lib/kadmin/form.rb

@@ -36,7 +36,7 @@ module Kadmin
     # @return [ActiveModel::Model] underlying model to populate
     attr_reader :model
 
-    delegate :id, :persisted?, to: :model
+    delegate :id, :persisted?, :to_key, :to_query, :to_param, :type_for_attribute, to: :model
 
     def initialize(model)
       @errors = ActiveModel::Errors.new(self)
@@ -44,52 +44,23 @@ module Kadmin
       @form_input = {}
     end
 
-    # @!group Parsing/Deserialization
-
-    # Populates the model based on the form input. The input is typically obtained
-    # from the controller's params method, but can be any hash which conforms to
-    # whatever the form object is expecting.
-    # If some input was previously parsed, there is no "rollback" on the state
-    # of the model; it should be done prior to reparsing if it is necessary.
-    # @param [Hash<String, Object>] form_input a hash representing the raw form input
-    def assign_attributes(form_input)
-      @errors.clear
-      form_input.each do |attr, value|
-        setter = "#{attr}="
-        send(setter, value) if respond_to?(setter)
-      end
+    def to_model
+      return @model
     end
 
-    # @!endgroup
+    # @!group Attributes assignment/manipulation
 
-    # @!group Validation
+    # Allows parsing of multi parameter attributes, such as those returned by
+    # the form helpers date_select, datetime_select, etc.
+    # Also allows nested attributes, but this is not currently in use.
+    include ActiveRecord::AttributeAssignment
 
-    validate :model_valid?
-
-    # Validates the models and merge errors back into our own errors if they
-    # are invalid.
-    # Overload if you need to validate associations.
-    # @example
-    #   class PersonForm < Form
-    #     def model_valid?
-    #       super
-    #       if @model&.child&.changed? && !@model.child.valid?
-    #         @errors.add(:base, :invalid, message: 'child model is invalid')
-    #       end
-    #     end
-    #   end
-    def model_valid?
-      unless @model.valid?
-        @model.errors.each do |attribute, error|
-          @errors.add(attribute, error)
-        end
-      end
+    # For now, we overload the method to accept all attributes.
+    # This is removed in Rails 5, so once we upgrade we can remove the overload.
+    def sanitize_for_mass_assignment(attributes)
+      return attributes
     end
 
-    # @!endgroup
-
-    # @!group Helper methods
-
     class << self
       # Delegates the list of attributes to the model, both readers and writers.
       # If the attribute value passed is a hash and not a symbol, assumes it is
@@ -98,23 +69,102 @@ module Kadmin
       #   delegate_attributes :first_name, { last_name: [:reader] }
       # @param [Array<Symbol, Hash<Symbol, Array<Symbol>>>] attributes list of attributes to delegate to the model
       def delegate_attributes(*attributes)
-        delegates = attributes.reduce([]) do |acc, attribute|
+        delegates = attributes.each_with_object([]) do |attribute, acc|
           case attribute
           when Hash
             key, value = attribute.first
             acc << key if value.include?(:reader)
             acc << "#{key}=" if value.include?(:writer)
           when Symbol, String
-            acc << attribute
+            acc.push(attribute, "#{attribute}=")
           else
             raise(ArgumentError, 'Attribute must be one of: Hash, Symbol, String')
           end
+        end
 
-          delegate(*delegates, to: model)
+        delegate(*delegates, to: :model)
+      end
+
+      # Delegates a specified associations to other another form object
+      # @example
+      #   delegate_associations :child, :parent, to: 'Forms::PersonForm'
+      cattr_accessor(:associations) { {} }
+      def delegate_association(association, to:)
+        self.associations[association] = to
+
+        # add a reader attribute
+        class_eval <<~METHOD, __FILE__, __LINE__ + 1
+          def #{association}
+            return self.associated_forms['#{association}']
+          end
+        METHOD
+      end
+    end
+
+    def associated_forms
+      return @associated_forms ||= begin
+        self.class.associations.map do |name, form_class_name|
+          form_class = form_class_name.constantize
+          form_class.new(@model.public_send(name))
         end
       end
     end
 
     # @!endgroup
+
+    # @!group Validation
+
+    validate :validate_model
+    def validate_model
+      unless @model.valid?
+        @model.errors.each do |attribute, error|
+          @errors.add(attribute, error)
+        end
+      end
+    end
+    protected :validate_model
+
+    validate :validate_associated_forms
+    def validate_associated_forms
+      self.associated_forms.each do |_name, form|
+        next if form.valid?
+        form.errors.each do |_attribute, _error|
+          @errors.add(:base, :association_error, "associated #{form.model_name.human} form has some errors")
+        end
+      end
+    end
+    protected :validate_associated_forms
+
+    # @!endgroup
+
+    # @!group Persistence
+
+    def save
+      saved = false
+      @model.class.transaction do
+        saved = @model.save
+        self.associated_forms.each do |_name, form|
+          saved &&= form.save
+        end
+
+        raise ActiveRecord::Rollback unless saved
+      end
+
+      return saved
+    end
+
+    def save!
+      saved = false
+      @model.class.transaction do
+        saved = @model.save!
+        self.associated_forms.each do |_name, form|
+          saved &&= form.save! # no need to raise anything, save! will do so
+        end
+      end
+
+      return saved
+    end
+
+    # @!endgroup
   end
 end