abyme 0.2.2 → 0.5.1

data/abyme.gemspec

@@ -28,7 +28,21 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency "bundler", "~> 2.0"
   spec.add_development_dependency "rake", "~> 13.0"
+  # Tests
   spec.add_development_dependency "rspec-rails"
-  spec.add_development_dependency "rails-dummy"
+  spec.add_development_dependency 'rails-controller-testing'
+  spec.add_development_dependency 'database_cleaner-active_record'
+  spec.add_development_dependency 'capybara'
+  spec.add_development_dependency 'webdrivers'
+  spec.add_development_dependency "generator_spec"
+  
+  # Dummy app
   spec.add_development_dependency "sqlite3"
+  spec.add_development_dependency 'rails'
+  spec.add_development_dependency 'pry-rails'
+  spec.add_development_dependency 'web-console'
+
+  spec.add_development_dependency 'puma'
+  spec.add_development_dependency 'simplecov'
+  spec.add_development_dependency 'simplecov-lcov'
 end

data/javascript/abyme_controller.js

@@ -1,27 +1,62 @@
 import { Controller } from 'stimulus';
 
 export default class extends Controller {
-  static targets = ['template', 'associations', 'fields', 'newFields'];
+  // static targets = ['template', 'associations', 'fields', 'newFields'];
+  // Some applications don't compile correctly with the usual static syntax. 
+  // Thus implementing targets with standard getters below
+
+  static get targets() {
+    return ['template', 'associations', 'fields', 'newFields'];
+  } 
 
   connect() {
+    console.log("Abyme Connected")
+
     if (this.count) {
-      this.addDefaultAssociations();
+      // If data-count is present,
+      // add n default fields on page load
+
+      this.add_default_associations();
     }
   }
 
+  // return the value of the data-count attribute
+
   get count() {
     return this.element.dataset.minCount || 0;
   }
   
+  // return the value of the data-position attribute
+  // if there is no position specified set end as default
+
   get position() {
     return this.associationsTarget.dataset.abymePosition === 'end' ? 'beforeend' : 'afterbegin';
   }
 
+  // ADD_ASSOCIATION
+
+  // this function is call whenever a click occurs
+  // on the element with the click->abyme#add_association
+  // <button> element by default
+
+  // if a data-count is present the add_association
+  // will be call without an event so we have to check
+  // this case
+
+  // check for limit reached 
+  // dispatch an event if the limit is reached
+
+  // - call the function build_html that take care
+  //   for building the correct html to be inserted in the DOM
+  // - dispatch an event before insert
+  // - insert html into the dom
+  // - dispatch an event after insert
+
   add_association(event) {
     if (event) {
       event.preventDefault();
     }
-    // check for limit reached
+
     if (this.element.dataset.limit && this.limit_check()) {
       this.create_event('limit-reached')
       return false
@@ -33,8 +68,21 @@ export default class extends Controller {
     this.create_event('after-add');
   }
 
+  // REMOVE_ASSOCIATION
+
+  // this function is call whenever a click occurs
+  // on the element with the click->abyme#remove_association
+  // <button> element by default
+
+  // - call the function mark_for_destroy that takes care
+  //   of marking the element for destruction and hiding it
+  // - dispatch an event before mark & hide
+  // - mark for descrution + hide the element
+  // - dispatch an event after mark and hide
+
   remove_association(event) {
     event.preventDefault();
+
     this.create_event('before-remove');
     this.mark_for_destroy(event);
     this.create_event('after-remove');
@@ -42,6 +90,12 @@ export default class extends Controller {
 
   // LIFECYCLE EVENTS RELATED
 
+  // CREATE_EVENT
+
+  // take a stage (String) => before-add, after-add...
+  // create a new custom event 
+  // and dispatch at at the controller level
+
   create_event(stage, html = null) {
     const event = new CustomEvent(`abyme:${stage}`, { detail: {controller: this, content: html} });
     this.element.dispatchEvent(event);
@@ -69,9 +123,14 @@ export default class extends Controller {
   abymeAfterRemove(event) {
   }
 
-  // UTILITIES
+  // BUILD HTML
+
+  // takes the html template and substitutes the sub-string
+  // NEW_RECORD for a generated timestamp
+  // then if there is a sub template in the html (multiple nested level)
+  // set all the sub timestamps back as NEW_RECORD
+  // finally returns the html  
 
-  // build html
   build_html() {
     let html = this.templateTarget.innerHTML.replace(
       /NEW_RECORD/g,
@@ -88,8 +147,15 @@ export default class extends Controller {
 
     return html;
   }
-    
-  // mark association for destroy
+  
+  // MARK_FOR_DESTROY
+
+  // mark association for destruction
+  // get the closest abyme--fields from the remove_association button
+  // set the _destroy input value as 1
+  // hide the element
+  // add the class of abyme--marked-for-destroy to the element
+
   mark_for_destroy(event) {
     let item = event.target.closest('.abyme--fields');
     item.querySelector("input[name*='_destroy']").value = 1;
@@ -97,20 +163,29 @@ export default class extends Controller {
     item.classList.add('abyme--marked-for-destroy')
   }
 
-  // check if associations limit is reached
+
+  // LIMIT_CHECK
+
+  // Check if associations limit is reached
+  // based on newFieldsTargets only
+  // persisted fields are ignored
+
   limit_check() {
     return (this.newFieldsTargets
                 .filter(item => !item.classList.contains('abyme--marked-for-destroy'))).length 
                 >= parseInt(this.element.dataset.limit)
   }
 
-  // Add default blank associations at page load
-  async addDefaultAssociations() {
+  // ADD_DEFAULT_ASSOCIATION
+
+  // Add n default blank associations at page load
+  // call sleep function to ensure uniqueness of timestamp
+
+  async add_default_associations() {
     let i = 0
     while (i < this.count) {
       this.add_association()
       i++
-      // Sleep function to ensure uniqueness of timestamp
       await this.sleep(1);
     }
   }

data/lib/abyme.rb

@@ -1,6 +1,8 @@
 require "abyme/version"
 require 'abyme/view_helpers'
 require 'abyme/engine'
+require 'abyme/controller'
+require 'abyme/action_view_extensions/builder'
 
 module Abyme
   class Error < StandardError; end

data/lib/abyme/abyme_builder.rb

@@ -2,31 +2,42 @@ module Abyme
   class AbymeBuilder < ActionView::Base
     include ActionView
 
-    def initialize(association:, form:, lookup_context:, partial:, &block)
+    # If a block is given to the #abymize helper 
+    # it will instanciate a new AbymeBuilder 
+    # and pass to it the association name (Symbol)
+    # the form object, lookup_context optionaly a partial path
+    # then yield itself to the block 
+
+    def initialize(association:, form:, context:, partial:, &block)
       @association = association
       @form = form
-      @lookup_context = lookup_context
+      @context = context
+      @lookup_context = context.lookup_context
       @partial = partial
       yield(self) if block_given?
     end
+
+    # RECORDS
+
+    # calls the #persisted_records_for helper method
+    # passing association, form and options to it
   
     def records(options = {})
       persisted_records_for(@association, @form, options) do |fields_for_association|
-        render_association_partial(fields_for_association, options)
+        render_association_partial(@association, fields_for_association, @partial, @context)
       end
     end
+
+    # NEW_RECORDS
+
+    # calls the #new_records_for helper method
+    # passing association, form and options to it
     
     def new_records(options = {}, &block)
       new_records_for(@association, @form, options) do |fields_for_association|
-        render_association_partial(fields_for_association, options)
+        render_association_partial(@association, fields_for_association, @partial, @context)
       end
     end
   
-    private
-
-    def render_association_partial(fields, options)
-      partial = @partial || options[:partial] || "abyme/#{@association.to_s.singularize}_fields"
-      ActionController::Base.render(partial: partial, locals: { f: fields })
-    end
   end
 end

data/lib/abyme/action_view_extensions/builder.rb

@@ -0,0 +1,17 @@
+module Abyme
+  module ActionViewExtensions
+    module Builder
+      def abyme_for(association, options = {}, &block)
+        @template.abyme_for(association, self, options, &block)
+      end
+
+      alias :abymize :abyme_for
+    end
+  end
+end
+
+module ActionView::Helpers
+  class FormBuilder
+    include Abyme::ActionViewExtensions::Builder
+  end
+end

data/lib/abyme/controller.rb

@@ -0,0 +1,15 @@
+module Abyme
+  module Controller
+    def abyme_attributes
+      return [] if resource_class.nil?
+      
+      resource_class.abyme_attributes
+    end
+
+    private
+
+    def resource_class
+      self.class.name.match(/(.*)(Controller)/)[1].singularize.safe_constantize
+    end
+  end
+end

data/lib/abyme/engine.rb

@@ -4,9 +4,11 @@ module Abyme
     
     config.after_initialize do
       ActiveSupport.on_load :action_view do
-        # ActionView::Base.send :include, Abyme::ViewHelpers
         include Abyme::ViewHelpers
       end
+      ActiveSupport.on_load :action_controller do
+        include Abyme::Controller
+      end
     end
   end
 end

data/lib/abyme/model.rb

@@ -1,11 +1,87 @@
 module Abyme
   module Model
-    extend ActiveSupport::Concern
-
-    class_methods do
-      def abyme_for(association, options = {})
+    module ClassMethods
+      def abymize(association, permit: nil, reject: nil, **options)
         default_options = {reject_if: :all_blank, allow_destroy: true}
-        accepts_nested_attributes_for association, default_options.merge(options)
+        nested_attributes_options = default_options.merge(options)
+        accepts_nested_attributes_for association, nested_attributes_options
+        # Save allow_destroy value for this model/association for later
+        save_destroy_option(association, nested_attributes_options[:allow_destroy])
+        Abyme::Model.permit_attributes(self.name, association, permit || reject, permit.present?) if permit.present? || reject.present?
+      end
+
+      alias :abyme_for :abymize
+
+      def abyme_attributes
+        Abyme::Model.instance_variable_get(:@permitted_attributes)[self.name]
+      end
+
+      private
+
+      def save_destroy_option(association, value)
+        Abyme::Model.instance_variable_get(:@allow_destroy)[self.name][association] = value
+      end
+    end
+
+    @permitted_attributes ||= {}
+    @allow_destroy        ||= {}
+
+    attr_accessor :allow_destroy
+    attr_reader   :permitted_attributes
+
+    def self.permit_attributes(class_name, association, attributes, permit)
+      @permitted_attributes[class_name]["#{association}_attributes".to_sym] = AttributesBuilder.new(class_name, association, attributes, permit)
+                                                                                               .build_attributes
+    end
+
+    def self.included(klass)
+      @permitted_attributes[klass.name] ||= {}
+      @allow_destroy[klass.name]        ||= {}
+      klass.extend ClassMethods
+    end
+
+    class AttributesBuilder
+      def initialize(model, association, attributes, permit = true)
+        @model = model
+        @association = association
+        @attributes_list = attributes
+        @permit = permit
+        @association_class = @association.to_s.classify.constantize
+      end
+
+      def build_attributes
+        nested_attributes = @association_class.abyme_attributes if @association_class.respond_to? :abyme_attributes
+        authorized_attributes = build_default_attributes
+        if @permit && @attributes_list == :all_attributes
+          authorized_attributes = build_all_attributes(authorized_attributes, nested_attributes)
+        elsif @permit
+          @attributes_list << nested_attributes unless (nested_attributes.blank? || @attributes_list.include?(nested_attributes))
+          authorized_attributes += @attributes_list
+        else
+          authorized_attributes = build_all_attributes(authorized_attributes, nested_attributes)
+          authorized_attributes -= @attributes_list
+        end
+        authorized_attributes
+      end
+
+      def destroy_allowed?
+        Abyme::Model.instance_variable_get(:@allow_destroy).dig(@model, @association)
+      end
+
+      def add_all_attributes
+        @association_class.column_names.map(&:to_sym).reject { |attr| [:id, :created_at, :updated_at].include?(attr) }
+      end
+
+      def build_all_attributes(authorized_attributes, nested_attributes)
+        authorized_attributes += add_all_attributes
+        authorized_attributes << nested_attributes unless (nested_attributes.blank? || authorized_attributes.include?(nested_attributes))
+        authorized_attributes
+      end
+
+      def build_default_attributes
+        attributes = [:id]
+        attributes << :_destroy if destroy_allowed?
+        attributes
       end
     end
   end

data/lib/abyme/version.rb

@@ -1,9 +1,11 @@
+# :nocov:
 module Abyme
   module VERSION
     MAJOR = 0
-    MINOR = 2
-    PATCH = 2
+    MINOR = 5
+    PATCH = 1
 
     STRING = [MAJOR, MINOR, PATCH].join(".")
   end
 end
+# :nocov:

data/lib/abyme/view_helpers.rb

@@ -1,28 +1,108 @@
+require_relative "abyme_builder"
+
 module Abyme
   module ViewHelpers
 
-    def abymize(association, form, options = {}, &block)
+    # ABYME_FOR
+
+    # this helper will generate the top level wrapper markup
+    # with the bare minimum html attributes (data-controller="abyme")
+    # it takes the Symbolized name of the association (plural) and the form object
+    # then you can pass a hash of options (see exemple below)
+    # if no block given it will generate a default markup for
+    # #persisted_records_for, #new_records_for & #add_associated_record methods
+    # if a block is given it will instanciate a new AbymeBuilder and pass to it
+    # the name of the association, the form object and the lookup_context
+
+    # == Options
+
+    # - limit (Integer)
+    # you can set a limit for the new association fields to display
+
+    # - min_count (Integer)
+    # set the default number of blank fields to display
+
+    # - partial (String)
+    # to customize the partial path by default #abyme_for will expect 
+    # a partial to bbe present in views/abyme
+
+    # - Exemple
+
+    # <%= abyme_for(:tasks, f, limit: 3) do |abyme| %>
+    #   ...
+    # <% end %>
+
+    # will output this html
+
+    # <div data-controller="abyme" data-limit="3" id="abyme--tasks">
+    #   ...
+    # </div>
+
+    def abyme_for(association, form, options = {}, &block)
       content_tag(:div, data: { controller: 'abyme', limit: options[:limit], min_count: options[:min_count] }, id: "abyme--#{association}") do
         if block_given?
           yield(Abyme::AbymeBuilder.new(
-            association: association, form: form, lookup_context: self.lookup_context, partial: options[:partial]
+            association: association, form: form, context: self, partial: options[:partial]
             )
           )
         else
           model = association.to_s.singularize.classify.constantize
           concat(persisted_records_for(association, form, options))
           concat(new_records_for(association, form, options)) 
-          concat(add_association(content: options[:button_text] || "Add #{model}"))
+          concat(add_associated_record(content: options[:button_text] || "Add #{model}"))
         end
       end
     end
 
+    alias :abymize :abyme_for
+
+    # NEW_RECORDS_FOR
+
+    # this helper is call by the AbymeBuilder #new_records instance method
+    # it generates the html markup for new associations fields
+    # it takes the association (Symbol) and the form object
+    # then a hash of options.
+
+    # - Exemple
+    # <%= abyme_for(:tasks, f) do |abyme| %>
+    #   <%= abyme.new_records %>
+    #   ...
+    # <% end %>
+
+    # will output this html
+
+    # <div data-target="abyme.associations" data-association="tasks" data-abyme-position="end">
+    #    <template class="abyme--task_template" data-target="abyme.template"> 
+    #       <div data-target="abyme.fields abyme.newFields" class="abyme--fields task-fields">
+    #         ... partial html goes here 
+    #       </div>
+    #    </template>
+    #    ... new rendered fields goes here
+    # </div>
+
+    # == Options
+    # - position (:start, :end)
+    # allows you to specify whether new fields added dynamically 
+    # should go at the top or at the bottom 
+    # :end is the default value
+
+    # - partial (String)
+    # to customize the partial path by default #abyme_for will expect 
+    # a partial to bbe present in views/abyme
+
+    # - fields_html (Hash)
+    # allows you to pass any html attributes to each fields wrapper
+
+    # - wrapper_html (Hash)
+    # allows you to pass any html attributes to the the html element 
+    # wrapping all the fields
+
     def new_records_for(association, form, options = {}, &block)
       options[:wrapper_html] ||= {}
 
       wrapper_default = { 
         data: { 
-          target: 'abyme.associations', 
+          abyme_target: 'associations', 
           association: association, 
           abyme_position: options[:position] || :end 
         } 
@@ -31,25 +111,69 @@ module Abyme
       fields_default = { data: { target: 'abyme.fields abyme.newFields' } }
 
       content_tag(:div, build_attributes(wrapper_default, options[:wrapper_html])) do
-        content_tag(:template, class: "abyme--#{association.to_s.singularize}_template", data: { target: 'abyme.template' }) do
+        content_tag(:template, class: "abyme--#{association.to_s.singularize}_template", data: { abyme_target: 'template' }) do
           form.fields_for association, association.to_s.classify.constantize.new, child_index: 'NEW_RECORD' do |f|
             content_tag(:div, build_attributes(fields_default, basic_fields_markup(options[:fields_html], association))) do
               # Here, if a block is passed, we're passing the association fields to it, rather than the form itself
-              block_given? ? yield(f) : render(options[:partial] || "abyme/#{association.to_s.singularize}_fields", f: f)
+              # block_given? ? yield(f) : render(options[:partial] || "abyme/#{association.to_s.singularize}_fields", f: f)
+              block_given? ? yield(f) : render_association_partial(association, f, options[:partial])
             end
           end
         end
       end
     end
+
+    # PERSISTED_RECORDS_FOR
+
+    # this helper is call by the AbymeBuilder #records instance method
+    # it generates the html markup for persisted associations fields
+    # it takes the association (Symbol) and the form object
+    # then a hash of options.
+
+    # - Exemple
+    # <%= abyme_for(:tasks, f) do |abyme| %>
+    #   <%= abyme.records %>
+    #   ...
+    # <% end %>
+
+    # will output this html
+
+    # <div>
+    #   <div data-target="abyme.fields" class="abyme--fields task-fields">
+    #     ... partial html goes here
+    #   </div>
+    # </div>
+
+    # == Options
+    # - collection (Active Record Collection)
+    # allows you to pass an AR collection
+    # by default every associated records will be present
+
+    # - order (Hash)
+    # allows you to order the collection
+    # ex: order: { created_at: :desc }
+
+    # - partial (String)
+    # to customize the partial path by default #abyme_for will expect 
+    # a partial to bbe present in views/abyme
+
+    # - fields_html (Hash)
+    # allows you to pass any html attributes to each fields wrapper
+
+    # - wrapper_html (Hash)
+    # allows you to pass any html attributes to the the html element 
+    # wrapping all the fields
   
     def persisted_records_for(association, form, options = {})
       records = options[:collection] || form.object.send(association)
       options[:wrapper_html] ||= {}
-      fields_default = { data: { target: 'abyme.fields' } }
+      fields_default = { data: { abyme_target: 'fields' } }
       
       if options[:order].present?
         records = records.order(options[:order])
-        # Get invalid records
+        # by calling the order method on the AR collection
+        # we get rid of the records with errors
+        # so we have to get them back with the 2 lines below
         invalids = form.object.send(association).reject(&:persisted?)
         records = records.to_a.concat(invalids) if invalids.any?
       end 
@@ -57,28 +181,54 @@ module Abyme
       content_tag(:div, options[:wrapper_html]) do
         form.fields_for(association, records) do |f|
           content_tag(:div, build_attributes(fields_default, basic_fields_markup(options[:fields_html], association))) do
-            block_given? ? yield(f) : render(options[:partial] || "abyme/#{association.to_s.singularize}_fields", f: f)
+            block_given? ? yield(f) : render_association_partial(association, f, options[:partial])
           end
         end
       end
     end
+
+    # ADD & REMOVE ASSOCIATION
+
+    # these helpers will call the #create_button method 
+    # to generate the buttons for add and remove associations
+    # with the right action and a default content text for each button
   
-    def add_association(options = {}, &block)
+    def add_associated_record(options = {}, &block)
       action = 'click->abyme#add_association'
+      options[:content] ||= 'Add Association'
       create_button(action, options, &block)
     end
   
-    def remove_association(options = {}, &block)
+    def remove_associated_record(options = {}, &block)
       action = 'click->abyme#remove_association'
+      options[:content] ||= 'Remove Association'
       create_button(action, options, &block)
     end
 
+    alias :add_association    :add_associated_record 
+    alias :remove_association :remove_associated_record
+
     private
+
+    # CREATE_BUTTON
+
+    # this helper is call by either add_associated_record or remove_associated_record
+    # by default it will generate a button tag.
+
+    # == Options
+    # - content (String)
+    # allows you to set the button text
+
+    # - tag (Symbol)
+    # allows you to set the html tag of your choosing
+    # default if :button
+
+    # - html (Hash)
+    # to pass any html attributes you want.
   
     def create_button(action, options, &block)
       options[:html] ||= {}
       options[:tag] ||= :button
-      options[:content] ||= 'Add Association'
   
       if block_given?
         content_tag(options[:tag], { data: { action: action } }.merge(options[:html])) do
@@ -89,6 +239,11 @@ module Abyme
       end
     end
 
+    # BASIC_FIELDS_MARKUP
+
+    # generates the default html classes for fields
+    # add optional classes if present
+
     def basic_fields_markup(html, association = nil)
       if html && html[:class]
         html[:class] = "abyme--fields #{association.to_s.singularize}-fields #{html[:class]}" 
@@ -99,17 +254,33 @@ module Abyme
       html
     end
 
+    # BUILD_ATTRIBUTES
+
+    # add optionals html attributes without overwritting
+    # the default or already present ones
+
     def build_attributes(default, attr)
-      # ADD NEW DATA ATTRIBUTES VALUES TO THE DEFAULT ONES (ONLY VALUES)
+      # Add new data attributes values to the default ones (only values)
       if attr[:data]
         default[:data].each do |key, value|
           default[:data][key] = "#{value} #{attr[:data][key]}".strip
         end
-      # ADD NEW DATA ATTRIBUTES (KEYS & VALUES)
+        # Add new data attributes (keys & values)
         default[:data] = default[:data].merge(attr[:data].reject { |key, _| default[:data][key] })
       end
-      # MERGE THE DATA ATTRIBUTES TO THE HASH OF HTML ATTRIBUTES
+      # Merge data attributes to the hash of html attributes
       default.merge(attr.reject { |key, _| key == :data })
     end
+
+    # RENDER PARTIAL
+
+    # renders a partial based on the passed path, or will expect a partial to be found in the views/abyme directory. 
+
+    def render_association_partial(association, form, partial = nil, context = nil)
+      partial_path = partial ||"abyme/#{association.to_s.singularize}_fields"
+      context ||= self
+      context.render(partial: partial_path, locals: {f: form})
+    end
+
   end
 end