Form Element Repeater is a jQuery plugin for creating repeatable form elements, i.e. an array of input elements, with add/remove capabilities.
Supporting the creation and deletion of a collection of data on a website can be tricky. The problem is due to the way the input elements need to be formatted within a web form.
Some common use cases for using the repeater plugin are managing tags, categories, links, email addresses, etc. More complex examples include managing multiple objects of data such as addresses, social profiles, etc. Basically anything that you create multiple of with multiple fields per entry.
Plugin usage is dependent on a number of configuration settings and conventions. One of the primary conventions you must follow is the usage of jQuery data elements. These data elements, bound to elements in your document, can do a few things:
r-group.
To dynamically add and remove repeatable elements and groups that utilize the label element,
we need a method for incrementing a label's for attribute name. We accomplish this with
a data-pattern-text attribute. Here's an example:
The data-pattern-text attribute accepts a string as well as template keyword indicating
the increment method. Possible values of the template keyword are as follows:
+= This operator will increment by the numeric number following it for each new element added, i.e. +=1 or +=2++ This operator will increment by one for each new element added
In order to have unique IDs and names of our form elements, we need a method for incrementing
and decrementing. We accomplish this with the data-pattern-name and
data-pattern-id attributes. Here's an example:
The data-pattern-name attribute accepts an array based string as well as template keyword indicating
the increment method. A valid array based string can follow a few formatting conventions.
If you are using the repeater plugin for a single form element and not a group/collection, you can use
the convention elementname[++]. Here elementname represents your form item
that you're creating an array of. This could be something like "emails", "links", "categories", "tags",
etc. This will create a one-dimensional array.
If you are using the repeater plugin for a collection or group of form elements, you can use the convention
uniquegroup[++][uniqueelementname]. Here, uniquegroup represents your
overall group/collection name, i.e. "cars", "addresses", "emails", "profiles", etc. It will be passed to your
backend as an array. The uniqueelementname represents the name of the individual form
element you are on, i.e. "engine", "street1", "firstname", "username", etc. This will create a
multi-dimensional array.
If we put it all together, we have the following form example:
To learn more about the other configuration options seen here, continue reading below for details.
There are numerous configuration options included with the Form Element Repeater Plugin.
| Option Name | Details | Default Value |
|---|---|---|
groupClass |
'r-group' |
|
btnAddClass |
'r-btnAdd' |
|
btnRemoveClass |
'r-btnRemove' |
|
minItems |
1 |
|
maxItems |
0 |
|
startingIndex |
The starting index of your array. As 0 is the default in almost all
programming languages, you should almost never need to change this. |
0 |
reindexOnDelete |
true |
|
repeatMode |
The repeat mode decides how the repeater adds elements to your group. Valid options
are append, prepend, and insertAfterLast. Reasons
for leaving this option set to insertAfterLast are that you don't want
your new form elements to appear after your add button, which may happen with append.
|
'insertAfterLast' |
animation |
The type of animation that should occur when adding and removing. | null |
animationSpeed |
The speed of the animation, when enabled, in milliseconds. | 400 |
animationEasing |
The type of jQuery easing to apply to the animation, when enabled. | swing |
clearValues |
This option is not currently in use. | true |
beforeAdd |
A user supplied callback function. Triggers before a new group/collection has been added. You must return the $doppleganger element, even if you don't modify it. | function($doppleganger) { return $doppleganger; } |
afterAdd |
A user supplied callback function. Triggers after a new group/collection has been added. | function($doppleganger) { } |
beforeDelete |
A user supplied callback function. Triggers just prior to removal of the element. | function($elem) { } |
afterDelete |
A user supplied callback function. Triggers after removal of the element and reindexing has occurred. | function() { } |
Below is an example of the default configuration option values that come with the plugin:
Downloads are available via github. The decision is all yours:
git clone [email protected]:cballou/jQuery-Form-Element-Repeater-Plugin.gitgit clone https://github.com/cballou/jQuery-Form-Element-Repeater-Plugin.gitwget https://github.com/cballou/jQuery-Form-Element-Repeater-Plugin/archive/master.zipwget https://github.com/cballou/jQuery-Form-Element-Repeater-Plugin/archive/master.tar.gzIf you have any problems with Form Element Repeater, please file a ticket/issue/bug on Github and I will attempt to address it at my earliest convenience.
Form Element Repeater Issues on GithubForm Element Repeater is licensed under the MIT License.
The MIT License is simple and easy to understand and it places almost no restrictions on what you can do with Form Element Repeater.
You are free to use Form Element Repeater in commercial projects as long as any copyright headers and license file are left intact.
Corey Ballou is a full-stack web applications developer in Charlotte, NC with 9+ years professional experience. He holds a bachelors degree in Computer Science and has been working remotely since 2012. He specializes in LAMP/LEMP stack development with Laravel and WordPress. Corey is the owner and principal consultant at Craft Blue, a custom web applications development consultancy. He's also the co-organizer of the Queen City PHP meetup group in Charlotte. He is an entrepreneur, blogger, open source contributor, beer lover, startup advocate, chicken wrangler, hydroponics gardening dabbler, and homebrewer.
Corey works with agencies, startups, and businesses.
Contact Corey to see how Craft Blue can help you.