JQuery InsertInOrder plugin

A JQuery plugin to insert a new DOM element at the right place within sibling DOM elements.

For instance, say you have an HTML list like this:

<ul>
  <li>Hello 0</li>
  <li>Hello 2</li>
  <li>Hello 4</li>
</ul>

and you want to insert <li>Hello 3</li> at the right place, this library does just that effortlessly (by using an extra data-order attribute, not represented here).

Getting Started

Install on your website manually

Download the production version or the development version.

In your web page:

<script src="//ajax.googleapis.com/ajax/libs/jquery/1.11.0/jquery.min.js"></script>
<script src="js/insertinorder.min.js"></script>

Install on your website with Bower

This assumed you installed Bower, and ran bower init

Run in the terminal:

bower install --save jquery-insertinorder

Add into your webpage:

<script type="text/javascript" src="bower_components/jquery/dist/jquery.min.js"></script>
<script type="text/javascript" src="bower_components/jquery-insertinorder/dist/insertinorder.min.js"></script>

Documentation

Three prerequisites:

• JQuery must be included in your webpage, of course.
• the elements in the list you're inserting into all have a data-order attribute (those that don't will be ignored), and this attribute is a numeral.
• the elements already in the list are ordered on their data-order attribute, in the same direction as the one you're using to insert the element.

Apply the method on the JQuery element objet of the parent element. Note that even though the library was created with a particular use case in mind, that you will probably apply the method on a ul DOM element, in order to keep its li children ordered, this is actually not a necessity (it should work with div elements within div elements, or anything else).

Parameters in insertinorder(liStr, order, options)

• liStr (mandatory): the string representation of the element you're inserting. If you wish to insert other elements later, don't forget to give it a data-order attribute containing its order in the list.
• order (mandatory): its order within the list, as a numeral value (can seem repetitive, as you most likely inserted it in liStr's data-order attribute, but having it directly as a number makes the whole thing more performant).
• options (optional): an object containing options (see below)

Options:

• direction:
• 'asc': the list is ordered in an ascending direction, smallest first (default value).
• 'desc': the list is ordered in a descending direction, biggest first.

Examples

Adding an element in the ascending direction

If this is in your DOM:

<ul id="foo">
  <li data-order="0">Hello 0</li>
  <li data-order="2">Hello 2</li>
  <li data-order="4">Hello 4</li>
  <li data-order="6">Hello 6</li>
</ul>

And you run:

$('#foo').insertinorder('<li data-order="3">Hello 3</li>', 3)

You get:

<ul id="foo">
  <li data-order="0">Hello 0</li>
  <li data-order="2">Hello 2</li>
  <li data-order="3">Hello 3</li>
  <li data-order="4">Hello 4</li>
  <li data-order="6">Hello 6</li>
</ul>

Adding an element in the descending direction

If this is in your DOM:

<ul id="foo">
  <li data-order="6">Hello 6</li>
  <li data-order="4">Hello 4</li>
  <li data-order="2">Hello 2</li>
  <li data-order="0">Hello 0</li>
</ul>

And you run:

$('#foo').insertinorder('<li data-order="3">Hello 3</li>', 3, { direction: 'desc' })

You get:

<ul id="foo">
  <li data-order="6">Hello 6</li>
  <li data-order="4">Hello 4</li>
  <li data-order="3">Hello 3</li>
  <li data-order="2">Hello 2</li>
  <li data-order="0">Hello 0</li>
</ul>

From scratch

If this is in your DOM:

<ul id="foo">
</ul>

And you do:

$('#foo').insertinorder('<li data-order="3">Hello 3</li>', 3)
$('#foo').insertinorder('<li data-order="1">Hello 1</li>', 3)
$('#foo').insertinorder('<li data-order="5">Hello 5</li>', 3)
$('#foo').insertinorder('<li data-order="2">Hello 2</li>', 3)

You get:

<ul id="foo">
  <li data-order="1">Hello 1</li>
  <li data-order="2">Hello 2</li>
  <li data-order="3">Hello 3</li>
  <li data-order="5">Hello 5</li>
</ul>

Releases

Check out our release history on GitHub.

History of the plugin

I needed the plug-in while building an open-source project called "NowSpeak" (that yet has to be released), in order to be used with Firebase.

As a synchronized approach to cloud data, you get to retrieve data in Firebase by setting listeners. If you want to retrieve a list of Firebase references (that's how they call their stored "objects"), you listen to the child_added event on the parent reference, and insert in the DOM each received data. This allows to immediately synchronize everything with the current state of the data, but also to keep the data current, if new bits of data (references) are added by someone else.

However, it is impossible to predict in which order the references will arrive. There is an ordering feature in Firebase, but it didn't match my use case: I needed to update the order of elements (in Firebase's feature, the reference's priority is set at its creation, and cannot be changed later without removing the reference and re-creating it, including its sub-references).

The most relevant solution was therefore to leave the references unordered in the model, make sure to store their order field properly for each one, and simply insert each reference properly into the DOM when it is received by the application.