legshooter / addel

addel is a simple and lightweight jQuery plugin for powering UIs that enable dynamic addition and deletion of HTML elements, conceived with form elements in mind.

"addel" is short for add-delete and should be pronounced "Adele", just like the singer's name.

..Because it's all in the details, people!

Table of Contents

• Notable Features
• Installation
• Initialization
• HTML structure & restrictions
• Options
  • Options example
  • Data-attributes
    • Data-attributes example
  • Defaults
• Events
  • Events example
• Example
• Browser support
• Release policy
• License

Notable features

• Lightweight
• Maximum HTML flexibility
• Events you can hook on
• Declarative control
• Keyboard convenience through smart focusing
• Customizable animation

Installation

There are multiple options:

• Download addel.jquery.js or addel.jquery.min.js
• Use Bower: bower install addel --save
• Use npm: npm install addel --save
• Use yarn: yarn add addel

And include it: <script src="https://github.com/path/to/file/addel.jquery.min.js"></script>

Initialization

$('.addel-container').addel({
    // optional options object
});

⚠️ HTML structure and restrictions

<div class="addel-container">
    <div class="addel-target">
        <button class="addel-del"></button>
    </div>
    <button class="addel-add"></button>
</div>

As per RFC 2119:

• .addel-container MUST be the element addel is initialized upon
• .addel-container MUST contain everything else: .addel-target, .addel-delete and .addel-add
• .addel-target MAY also contain your own element/s, this is after all what we are here for
• .addel-delete MUST be .addel-container's and .addel-target's descendant
• .addel-add MUST be .addel-container's descendant and MUST NOT be .addel-target's descendant

Note that class names are for reference only and are completely customizable, as described in the options section.

Options

• For more information on animation.duration and animation.easing, see jQuery's .fadeIn() and .fadeOut().
• Note that it is possible to set the add option per element using a data-attribute, as described in the data-attributes section.

Options example

$('.people').addel({
    hide: true,
    add: 2,
    classes: {
        target: 'person',
        add: 'btn-add',
        delete: 'btn-del'
    },
    animation: {
        duration: 300,
        easing: 'linear'
    }
});

Data-attributes

Some options can be set declaratively as data-attributes on the HTML elements:

• Setting data-addel-add is the same as setting data-addel-add="1".
• Setting data-addel-add="5" on .addel-container will make all .addel-add / data-addel-add elements inside of it add 5 targets on click, by default.
• Specifying in addition a data-addel-add="10" on a specific .addel-add / data-addel-add will make that specific element add 10 targets, overriding the default 5 set earlier on the container.
• Note that for elements to behave as buttons that add targets, you need to add either data-addel-add or data-addel-add="<number>" to the element, there's no need for both.

Data-attributes example

<div class="addel" data-addel-hide="true" data-addel-add="2">
    <div data-addel-target>
        <button data-addel-delete></button>
    </div>
    <button data-addel-add="1"></button>  // adds 1 data-addel-target, as expected
    <button data-addel-add></button>      // adds 2 data-addel-target due to default set on .addel
    <button data-addel-add="3"></button>  // adds 3 data-addel-target on click, as expected
</div>
<script>
    $(function() {
        $('.addel').addel();
    });
</script>

Defaults

Override the entire options object:

$.fn.addel.defaults = {
    // options
};

Or a specific option:

$.fn.addel.defaults.option = value;

Events

All events are triggered on the element addel is initialized upon (AKA container).

Events example

Ask for confirmation before deleting:

$('.addel-container').addel({
    
    // other options

    events: {
        delete: function (event) {
            if (!window.confirm('Are you absolutely positively sure?')) {
                event.preventDefault();
            }
        }
    }
});

Or bind the event yourself:

$('.addel-container').addel({
    // other options
})
.on('addel:delete', function (event) {
    if (!window.confirm('Are you absolutely positively sure?')) {
        event.preventDefault();
    }
});

Example

A more elaborate example of all of the above is included.

Dependencies

jQuery (v2-3).

Browser support

addel is developed using Chrome (v57). It should work properly on all evergreen browsers and IE9+.

Release policy

addel adheres to Semantic Versioning.

License

addel is released under the MIT license.