cocooned 1.3.0

data/README.md

@@ -0,0 +1,293 @@
+# Cocooned
+
+[![Build Status](https://travis-ci.org/notus-sh/cocooned.png?branch=master)](https://travis-ci.org/notus-sh/cocooned)
+
+Cocooned makes it easier to handle nested forms in a Rails project.
+
+Cocooned is form builder-agnostic: it works with standard Rails (>= 4.0, < 6.0), [Formtastic](https://github.com/justinfrench/formtastic) or [SimpleForm](https://github.com/plataformatec/simple_form).
+
+## Some Background
+
+Cocooned is a fork of [Cocoon](https://github.com/nathanvda/cocoon) by [Nathan Van der Auwera](https://github.com/nathanvda).
+
+He and all Cocoon contributors did a great job to maintain it for years. Many thanks to them!
+
+But last time I checked, the project seemed to not have been actively maintained for a long time and many pull requests, even simple ones, were on hold. As I needed a more than what Cocoon provided at this time, I had the choice to either maintain an extension or to fork it and integrate everything that was waiting and more.
+
+Cocooned is almost a complete rewrite of Cocoon, with more functionnalities and (I hope) a more fluent API.
+
+**For now, Cocooned is completely compatible with Cocoon and can be used as a drop-in replacement.**  
+Just change the name of the gem in your Gemfile and you're done. It will work the same (but will add a bunch of deprecation warning to your logs).
+
+**The compatibility layer with the original Cocoon API will be dropped in Cocooned 2.0.**
+
+## Prerequisites
+
+Cocooned depends on jQuery, Ruby (>= 2.2) and Rails (>= 4.0, < 6.0).
+
+## Installation
+
+Inside your `Gemfile` add the following:
+
+```ruby
+gem "cocooned"
+```
+
+You must also require `cocooned` in your `application.js` and `application.css`, so it compiles with the asset pipeline.
+
+## Usage
+
+For all the following examples, we will consider modelisation of an administrable list with items.
+Here are the two ActiveRecord models : `List` and `Item`:
+
+```ruby
+class Item < ApplicationRecord
+  has_many :items, inverse_of: :list
+  accepts_nested_attributes_for :items, reject_if: :all_blank, allow_destroy: true
+end
+
+class Item < ApplicationRecord
+  belongs_to :list
+end
+```
+
+We will build a form where we can dynamically add and remove items to a list.
+
+### Strong Parameters Gotcha
+
+To destroy nested models, Rails uses a virtual attribute called `_destroy`.
+When `_destroy` is set, the nested model will be deleted. If the record has previously been persisted, Rails generate and use an automatic `id` field to fetch the wannabe destroyed record.
+
+When using Rails > 4.0 (or strong parameters), you need to explicitly add both `:id` and `:_destroy` to the list of permitted parameters.
+
+E.g. in your `ListsController`:
+
+```ruby
+  def list_params
+    params.require(:list).permit(:name, tasks_attributes: [:id, :description, :done, :_destroy])
+  end
+```
+
+### Basic form
+
+_Please note examples in this section are written with the [`haml` templating language](http://haml.info/)._
+
+[Rails natively supports nested forms](https://guides.rubyonrails.org/form_helpers.html#nested-forms) but does not support adding or removing nested items.
+
+```haml
+/ `app/views/lists/_form.html.haml`
+= form_for @list do |f|
+  = f.input :name
+  
+  %h3 Items
+  = f.fields_for :tasks do |item_form|
+    / This block is repeated for every task in @list.items
+    = item_form.label :description
+    = item_form.text_field :description
+    = item_form.check_box :done
+    
+  = f.submit "Save"
+```
+
+To enable Cocooned on this first, we need to:
+
+1. Move the nested form to a partial
+2. Add a way to add a new item to the collection
+3. Add a way to remove an item from the collection
+4. Initialize Cocooned to handle this form
+
+Let's do it.
+
+#### 1. Move the nested form to a partial
+
+We now have two files:
+
+```haml
+/ `app/views/lists/_form.html.haml`
+= form_for @list do |form|
+  = form.input :name
+  
+  %h3 Items
+  = form.fields_for :items do |item_form|
+    = render 'item_fields', f: item_form
+    
+  = form.submit "Save"
+```
+
+```haml
+/ `app/views/lists/_item_fields.html.haml`
+= f.label :description
+= f.text_field :description
+= f.check_box :done
+```
+
+#### 2. Add a way to add a new item to the collection
+
+```haml
+/ `app/views/lists/_form.html.haml`
+= form_for @list do |form|
+  = form.input :name
+  
+  %h3 Items
+  #items
+    = form.fields_for :tasks do |item_form|
+      = render 'item_fields', f: item_form
+    .links
+      = cocooned_add_item_link 'Add an item', form, :items
+  
+  = form.submit "Save"
+```
+
+By default, a new item will be inserted just before the immediate parent of the 'Add an item' link. You can have a look at the documentation of `cocooned_add_item_link` for more information about how to change that but we'll keep it simple for now.
+
+#### 3. Add a way to remove an item from the collection
+
+```haml
+/ `app/views/lists/_item_fields.html.haml`
+.cocooned-item
+  = f.label :description
+  = f.text_field :description
+  = f.check_box :done
+  = cocooned_remove_item_link 'Remove', f
+```
+
+The `.cocooned-item` class is required for the `cocooned_remove_item_link` to work correctly.
+
+#### 4. Initialize Cocooned to handle this form
+
+Cocooned will detect on page load forms it should handle and initialize itself.
+This detection is based on the presence of a `data-cocooned-options` attribute on the nested forms container.
+
+```haml
+/ `app/views/lists/_form.html.haml`
+= form_for @list do |form|
+  = form.input :name
+  
+  %h3 Items
+  #items{ :data => { cocooned_options: {}.to_json } }
+    = form.fields_for :tasks do |item_form|
+      = render 'item_fields', f: item_form
+    .links
+      = cocooned_add_item_link 'Add an item', form, :items
+  
+  = form.submit "Save"
+``` 
+
+And we're done!
+
+### Wait, what's the point of `data-cocooned-options` if it's to be empty?
+
+For simple use cases as the one we just demonstrated, the `data-cocooned-options` attributes only triggers the Cocooned initialization on page load. But you can use it to pass additional options to the Cocooned javascript and enable plugins.
+
+For now, Cocooned supports two plugins:
+
+* **Limit**, to set a maximum limit of items that can be added to the association
+* **Reorderable**, that will automatically update `position` fields when you add or remove an item or when you reorder associated items.
+
+#### The limit plugin
+
+The limit plugin is autoloaded when needed and does not require anything more than you specifiying the maximum number of items allowed in the association.
+
+```haml
+/ `app/views/lists/_form.html.haml`
+= form_for @list do |form|
+  = form.input :name
+  
+  %h3 Items
+  #items{ :data => { cocooned_options: { limit: 12 }.to_json } }
+    = form.fields_for :tasks do |item_form|
+      = render 'item_fields', f: item_form
+    .links
+      = cocooned_add_item_link 'Add an item', form, :items
+  
+  = form.submit "Save"
+```
+
+#### The reorderable plugin
+
+The reorderable plugin is autoloaded when activated and does not support any particular options.
+
+```haml
+/ `app/views/lists/_form.html.haml`
+= form_for @list do |form|
+  = form.input :name
+  
+  %h3 Items
+  #items{ :data => { cocooned_options: { reorderable: true }.to_json } }
+    = form.fields_for :tasks do |item_form|
+      = render 'item_fields', f: item_form
+    .links
+      = cocooned_add_item_link 'Add an item', form, :items
+  
+  = form.submit "Save"
+```
+
+However, you need to edit your nested partial to add the links that allow your users to move an item up or down in the collection and to add a `position` field.
+
+```haml
+/ `app/views/lists/_item_fields.html.haml`
+.cocooned-item
+  = f.label :description
+  = f.text_field :description
+  = f.check_box :done
+  = f.hidden_field :position
+  = cocooned_move_item_up_link 'Up', f
+  = cocooned_move_item_down_link 'Down', f
+  = cocooned_remove_item_link 'Remove', f
+```
+
+Also, remember the strong parameters gotcha we mentioned earlier.
+
+Of course, it means your model must have a `position` attribute you will use to sort collections.
+
+## How it works
+
+Cocooned defines some helper functions:
+
+* `cocooned_add_item_link` will build a link that, when clicked, dynamically adds a new partial form for the given association. [Have a look at the documentation for available options](https://github.com/notus-sh/cocooned/blob/master/lib/cocooned/helpers.rb#L21).
+* `cocooned_remove_item_link` will build a link that, when clicked, dynamically removes the surrounding partial form. [Have a look at the documentation for available options](https://github.com/notus-sh/cocooned/blob/master/lib/cocooned/helpers.rb#L143).
+* `cocooned_move_item_up_link` and `cocooned_move_item_down_link` will build links that, when clicked, will move the surrounding partial form one step up or down in the collection. [Have a look at the documentation for available options](https://github.com/notus-sh/cocooned/blob/master/lib/cocooned/helpers.rb#L178).
+
+### Javascript callbacks
+
+When your collection is modified, the following events can be triggered:
+
+* `cocooned:before-insert`: called before inserting a new nested child, can be [canceled](#canceling-an-action)
+* `cocooned:after-insert`: called after inserting
+* `cocooned:before-remove`: called before removing the nested child, can be [canceled](#canceling-an-action)
+* `cocooned:after-remove`: called after removal
+
+The limit plugin can trigger its own event:
+
+* `cocooned:limit-reached`: called when the limit is reached (before a new item will be inserted)
+
+And so does the reorderable plugin:
+
+* `cocooned:before-move`: called before moving the nested child, can be [canceled](#canceling-an-action)
+* `cocooned:after-move`: called after moving
+* `cocooned:before-reindex`: called before updating the `position` fields of nested items, can be [canceled](#canceling-an-action) (even if I honestly don't know why you would)
+* `cocooned:after-reindex`: called after `position` fields update
+
+To listen to the events in your JavaScript:
+
+```javascript
+$('#container').on('cocooned:before-insert', function(event, node, cocoonedInstance) {
+  /* Do something */
+});
+```
+
+An event handler is called with 3 arguments:
+
+The event `event` is an instance of `jQuery.Event` and carry some additional data:
+
+* `event.link`, the clicked link
+* `event.node`, the nested item that will be added, removed or moved, as a jQuery object. This is null for `cocooned:limit-reached` and `cocooned:*-reindex` events
+* `event.nodes`, the nested items that will be or just have been reindexed on `cocooned:*-reindex` events, as a jQuery object. Null otherwise. 
+* `event.cocooned`, the Cocooned javascript object instance handling the nested association.
+
+The `node` argument is the same jQuery object as `event.node`.
+The `cocooned` argument is the same as `event.cocooned`.
+
+#### Canceling an action
+
+You can cancel an action within the `cocooned:before-<action>` callback by calling `event.preventDefault()` or `event.stopPropagation()`.

data/Rakefile

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+
+# Test suites
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new
+
+task default: :spec
+
+require 'jasmine'
+load 'jasmine/tasks/jasmine.rake'
+
+# Linters
+require 'rubocop/rake_task'
+RuboCop::RakeTask.new do |task|
+  task.options = ['--config', 'config/linters/ruby.yml']
+end
+
+eslint_args = ['--no-eslintrc', '--config config/linters/js.json']
+eslint_path = ['app/assets/**/*.js', 'spec/javascripts/**/*.js', 'spec/dummy/app/assets/**/*.js']
+
+namespace :eslint do
+  desc 'Auto-correct JavaScript files'
+  task :auto_correct do
+    system("yarnpkg run eslint #{(eslint_args + ['--fix']).join(' ')} #{eslint_path.join(' ')}")
+  end
+end
+
+desc 'Lint JavaScript code'
+task :eslint do
+  system("yarnpkg run eslint #{eslint_args.join(' ')} #{eslint_path.join(' ')}")
+end
+
+# Documentation
+require 'rdoc/task'
+
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Cocooned'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/app/assets/javascripts/cocoon.js

@@ -0,0 +1,14 @@
+/* globals Cocooned */
+//= require 'cocooned'
+
+// Compatibility with the original Cocoon
+function initCocoon () {
+  $(Cocooned.prototype.selector('add')).each(function (_i, addLink) {
+    var container = Cocooned.prototype.findContainer(addLink);
+    var limit = parseInt($(addLink).data('limit'), 10) || false;
+
+    container.cocooned({ limit: limit });
+  });
+}
+
+$(initCocoon);

data/app/assets/javascripts/cocooned/core.js

@@ -0,0 +1,284 @@
+var Cocooned = function (container, options) {
+  this.container = jQuery(container);
+  this.options = jQuery.extend({}, this.defaultOptions(), (options || {}));
+
+  // Autoload plugins
+  for (var moduleName in Cocooned.Plugins) {
+    if (Cocooned.Plugins.hasOwnProperty(moduleName)) {
+      var module = Cocooned.Plugins[moduleName];
+      var optionName = moduleName.charAt(0).toLowerCase() + moduleName.slice(1);
+
+      if (this.options[optionName]) {
+        for (var method in module) {
+          if (module.hasOwnProperty(method) && typeof module[method] === 'function') {
+            this[method] = module[method];
+          }
+        }
+      }
+    }
+  }
+
+  this.init();
+};
+
+Cocooned.Plugins = {};
+Cocooned.prototype = {
+
+  elementsCounter: 0,
+
+  // Compatibility with Cocoon
+  // TODO: Remove in 2.0 (Only Cocoon namespaces).
+  namespaces: {
+    events: ['cocooned', 'cocoon']
+  },
+
+  // Compatibility with Cocoon
+  // TODO: Remove in 2.0 (Only Cocoon class names).
+  classes: {
+    // Actions link
+    add:        ['cocooned-add', 'add_fields'],
+    remove:     ['cocooned-remove', 'remove_fields'],
+    up:         ['cocooned-move-up'],
+    down:       ['cocooned-move-down'],
+    // Containers
+    container:  ['cocooned-container'],
+    item:       ['cocooned-item', 'nested-fields'],
+  },
+
+  defaultOptions: function () {
+    var options = {};
+
+    for (var moduleName in Cocooned.Plugins) {
+      if (Cocooned.Plugins.hasOwnProperty(moduleName)) {
+        var module = Cocooned.Plugins[moduleName];
+        var optionName = moduleName.charAt(0).toLowerCase() + moduleName.slice(1);
+
+        options[optionName] = module.defaultOptionValue;
+      }
+    }
+
+    return options;
+  },
+
+  notify: function (node, eventType, eventData) {
+    return !(this.namespaces.events.some(function(namespace) {
+      var namespacedEventType = [namespace, eventType].join(':');
+      var event = jQuery.Event(namespacedEventType, eventData);
+
+      node.trigger(event, [eventData.node, eventData.cocooned]);
+
+      return (event.isPropagationStopped() || event.isDefaultPrevented());
+    }));
+  },
+
+  selector: function (type, selector) {
+    var s = selector || '&';
+    return this.classes[type].map(function(klass) { return s.replace(/&/, '.' + klass); }).join(', ');
+  },
+
+  namespacedNativeEvents: function (type) {
+    var namespaces = this.namespaces.events.map(function(ns) { return '.' + ns; });
+    namespaces.unshift(type);
+    return namespaces.join('');
+  },
+
+  buildId: function () {
+    return (new Date().getTime() + this.elementsCounter++);
+  },
+
+  buildContentNode: function (content) {
+    var id = this.buildId();
+    var html = (content || this.content);
+    var braced = '[' + id + ']';
+    var underscored = '_' + id + '_';
+
+    ['associations', 'association'].forEach(function (a) {
+      html = html.replace(this.regexps[a]['braced'], braced + '$1');
+      html = html.replace(this.regexps[a]['underscored'], underscored + '$1');
+    }, this);
+
+    return $(html);
+  },
+
+  getInsertionNode: function (adder) {
+    var $adder = $(adder);
+    var insertionNode = $adder.data('association-insertion-node');
+    var insertionTraversal = $adder.data('association-insertion-traversal');
+
+    if (!insertionNode) {
+      return $adder.parent();
+    }
+
+    if (typeof insertionNode === 'function') {
+      return insertionNode($adder);
+    }
+
+    if (insertionTraversal) {
+      return $adder[insertionTraversal](insertionNode);
+    }
+
+    return insertionNode === 'this' ? $adder : $(insertionNode);
+  },
+
+  getInsertionMethod: function (adder) {
+    var $adder = $(adder);
+    return $adder.data('association-insertion-method') || 'before';
+  },
+
+  getItems: function (selector) {
+    selector = selector || '';
+    var self = this;
+    return $(this.selector('item', selector), this.container).filter(function () {
+      return ($(this).closest(self.selector('container')).get(0) === self.container.get(0));
+    });
+  },
+
+  findContainer: function (addLink) {
+    var $adder = $(addLink);
+    var insertionNode = this.getInsertionNode($adder);
+    var insertionMethod = this.getInsertionMethod($adder);
+
+    switch (insertionMethod) {
+      case 'before':
+      case 'after':
+      case 'replaceWith':
+        return insertionNode.parent();
+
+      case 'append':
+      case 'prepend':
+      default:
+        return insertionNode;
+    }
+  },
+
+  findItem: function (removeLink) {
+    return $(removeLink).closest(this.selector('item'));
+  },
+
+  init: function () {
+    var self = this;
+
+    this.addLinks = $(this.selector('add')).filter(function () {
+      var container = self.findContainer(this);
+      return (container.get(0) === self.container.get(0));
+    });
+
+    var addLink = $(this.addLinks.get(0));
+
+    this.content = addLink.data('association-insertion-template');
+    this.regexps = {
+      association: {
+        braced: new RegExp('\\[new_' + addLink.data('association') + '\\](.*?\\s)', 'g'),
+        underscored: new RegExp('_new_' + addLink.data('association') + '_(\\w*)', 'g')
+      },
+      associations: {
+        braced: new RegExp('\\[new_' + addLink.data('associations') + '\\](.*?\\s)', 'g'),
+        underscored: new RegExp('_new_' + addLink.data('associations') + '_(\\w*)', 'g')
+      }
+    };
+
+    this.initUi();
+    this.bindEvents();
+  },
+
+  initUi: function () {
+    var self = this;
+
+    if (!this.container.attr('id')) {
+      this.container.attr('id', this.buildId());
+    }
+    this.container.addClass(this.classes['container'].join(' '));
+
+    $(function () { self.hideMarkedForDestruction(); });
+    $(document).on('page:load turbolinks:load', function () { self.hideMarkedForDestruction(); });
+  },
+
+  bindEvents: function () {
+    var self = this;
+
+    // Bind add links
+    this.addLinks.on(
+      this.namespacedNativeEvents('click'),
+      function (e) {
+        e.preventDefault();
+        self.add(this);
+      });
+
+    // Bind remove links
+    // (Binded on document instead of container to not bypass click handler defined in jquery_ujs)
+    $(document).on(
+      this.namespacedNativeEvents('click'),
+      this.selector('remove', '#' + this.container.attr('id') + ' &'),
+      function (e) {
+        e.preventDefault();
+        self.remove(this);
+      });
+
+    // Bind options events
+    $.each(this.options, function (name, value) {
+      var bindMethod = 'bind' + name.charAt(0).toUpperCase() + name.slice(1);
+      if (value && self[bindMethod]) {
+        self[bindMethod]();
+      }
+    });
+  },
+
+  add: function (adder) {
+    var $adder = $(adder);
+    var insertionMethod = this.getInsertionMethod($adder);
+    var insertionNode = this.getInsertionNode($adder);
+    var contentTemplate = $adder.data('association-insertion-template');
+    var count = parseInt($adder.data('count'), 10) || 1;
+
+    for (var i = 0; i < count; i++) {
+      var contentNode = this.buildContentNode(contentTemplate);
+      var eventData = { link: $adder, node: contentNode, cocooned: this };
+      var afterNode = (insertionMethod === 'replaceWith' ? contentNode : insertionNode);
+
+      // Insertion can be prevented through a 'cocooned:before-insert' event handler
+      if (!this.notify(insertionNode, 'before-insert', eventData)) {
+        return false;
+      }
+
+      insertionNode[insertionMethod](contentNode);
+
+      this.notify(afterNode, 'after-insert', eventData);
+    }
+  },
+
+  remove: function (remover) {
+    var self = this;
+    var $remover = $(remover);
+    var nodeToDelete = this.findItem($remover);
+    var triggerNode = nodeToDelete.parent();
+    var eventData = { link: $remover, node: nodeToDelete, cocooned: this };
+
+    // Deletion can be prevented through a 'cocooned:before-remove' event handler
+    if (!this.notify(triggerNode, 'before-remove', eventData)) {
+      return false;
+    }
+
+    var timeout = triggerNode.data('remove-timeout') || 0;
+
+    setTimeout(function () {
+      if ($remover.hasClass('dynamic')) {
+        nodeToDelete.remove();
+      } else {
+        nodeToDelete.find('input[required], select[required]').each(function (index, element) {
+          $(element).removeAttr('required');
+        });
+        $remover.siblings('input[type=hidden][name$="[_destroy]"]').val('true');
+        nodeToDelete.hide();
+      }
+      self.notify(triggerNode, 'after-remove', eventData);
+    }, timeout);
+  },
+
+  hideMarkedForDestruction: function () {
+    var self = this;
+    $(this.selector('remove', '&.existing.destroyed'), this.container).each(function (i, removeLink) {
+      var node = self.findItem(removeLink);
+      node.hide();
+    });
+  }
+};

data/app/assets/javascripts/cocooned/jquery/onload.js

@@ -0,0 +1,10 @@
+;(function(w, $) {
+  'use strict';
+
+  $(function() {
+    $('*[data-cocooned-options]').each(function(i, el) {
+      $(el).cocooned($(el).data('cocooned-options'));
+    });
+  });
+
+})(window, jQuery);

data/app/assets/javascripts/cocooned/jquery/plugin.js

@@ -0,0 +1,20 @@
+;(function(w, $) {
+  'use strict';
+
+  $.fn.cocooned = function(options) {
+    return this.each(function() {
+      var container = $(this);
+
+      if (typeof container.data('cocooned') !== 'undefined') {
+        if (typeof w.console !== 'undefined') {
+          w.console.warn('Cocooned already initialized on this element.');
+          w.console.debug(container);
+        }
+        return;
+      }
+
+      var cocooned = new Cocooned(container, options);
+      container.data('cocooned', cocooned);
+    });
+  };
+})(window, jQuery);

data/app/assets/javascripts/cocooned/plugins/limit.js

@@ -0,0 +1,22 @@
+Cocooned.Plugins.Limit = {
+
+  defaultOptionValue: false,
+
+  bindLimit: function() {
+    this.limit = this.options['limit'];
+    this.container.on('cocooned:before-insert', function(e) {
+      var cocooned = e.cocooned;
+      if (cocooned.getLength() < cocooned.limit) {
+        return;
+      }
+
+      e.stopPropagation();
+      var eventData = { link: e.link, node: e.node, cocooned: cocooned };
+      cocooned.notify(cocooned.container, 'limit-reached', eventData);
+    });
+  },
+
+  getLength: function() {
+    return this.getItems('&:visible').length;
+  }
+};