Wrangle jQuery Plugin

How to Use It

First, get the code by cloning the GitHub repository or directly downloading the files. (What—you didn't do that yet? Just click here.)

Include the plugin at the bottom of your page, before the closing body tag and after you've included jQuery.

<script src="//ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>
<script src="js/jquery.wrangle.min.js"></script>

jQuery 1.8.3 is about as far back as we recommend going for this plugin. It also works just great with jQuery 2!

<div data-wrangle>
</div>

<div data-wrangle>
  <!-- This container responds to all mouse, touch, and pointer events -->
  <div data-selectarea>
    <!-- Your list should be a ul or ol -->
    <ul data-list>
      <li><img src="http://placekitten.com/400/300" alt="Kittens"></li>
    </ul>
    <!-- The canvas doesn't need a width and height set--we'll handle that -->
    <canvas data-canvas></canvas>
  </div>
</div>

<div data-wrangle>
  <div data-selectarea>
    <ul data-list>
      <li><img src="http://placekitten.com/400/300" alt="Kittens"></li>
    </ul>
    <canvas data-canvas></canvas>
  </div>

  <!-- Selects all items -->
  <a data-all>Select all</a>
  <!-- Deselects everything -->
  <a data-clear>Select none</a>
  <!-- Toggles drawing on and off (more on that later!) -->
  <a data-edit data-alttext="Cancel">Edit</a>
  <!-- Define a custom action (more on THAT later also!) -->
  <a data-action="delete">Delete</a>
</div>

[data-selectarea] {
  position: relative;
  -webkit-user-select: none;
     -moz-user-select: none;
      -ms-user-select: none;
          user-select: none;
  -ms-touch-action: none;
}
[data-canvas] {
  position: absolute;
  top: 0;
  left: 0;
  background: transparent;
  z-index: 10;
}
[data-list] {
  width: 100%;
  background: transparent;
  padding: 1em;
  position: relative;
  z-index: 5;
}
  [data-list] li {
    pointer-events: none;
  }

$(window).on('load', function() {
  $(document).wrangle();
});

{
  // Line styles
  lineColor: '#000000',
  lineWidth: 5,
  // CSS classes
  editableClass: 'editable',
  drawingClass: 'drawing',
  selectedClass: 'selected',
  // Ability to toggle selections
  selectToggle: false,
  // Different ways to interact with touch
  touchMode: 'auto',
  multiTouch: false,
  clearOnCancel: true,
}

How Does it Work?

This was a tricky piece of tech to build. Let's delve into the web standards that made it possible.

Handling input

There are three main ways the user can directly interact with an interface: a mouse, a finger or a stylus. In JavaScript, these are represented as MouseEvent and TouchEvent objects. Most modern touch devices support touch events in JavaScript. Some browsers will still trigger mouse events on top of touch events for the sake of backwards-compatibility, which we have to watch out for.

The vast majority of browsers these days support the basic drawing we're doing with Canvas, but touch support is a bit more spotty (just look at this compatability chart). On desktop browsers, standard touch events are supported in Firefox 6+, Chrome 22+, and Opera 15+. On mobile devices, touch is supported by Android 2.3+ and iOS 3.2+. Android 2.3 only supports single touch events; 3.0 is the first version to support multi-touch events. Windows Phone 7 does not support touch events. Windows Phone 8 and IE10 do, but they use Microsoft's custom Pointer event model (which has since been submitted to the W3C as a potential future standard). This implementation funnels all mouse, pen, and touch input into one MSPointerEvent object.

Wrangle supports mouse, touch and MSPointer events, but your mileage will vary depending on the device and browser. iOS provides the best experience in terms of standards and smoothness.

To keep the codebase simple and streamlined, the coordinates of all input events are funneled into one master of array of coordinates, regardless of how many and what type. This keeps other parts of the plugin from having to worry about where the coordinates came from or how they were delivered.

Drawing

To draw on the interface itself, we just layered an HTML5 Canvas on top of the list of items. A canvas is transparent by default. The drawing area has to account for a few things:

• Its position relative to the document: mouse and touch events send coordinates relative to the document, not the specific element, so we need to account for that.
• The size of the list area: When the window is resized, the size of the list area is checked, and the canvas is resized to match it. We can't simply scale the canvas with a percentage width. This causes the coordinate system of the canvas to scale proportionally, which will misalign the line with the user's input.
• Preventing default input: The default behavior on most all touch-enabled browsers is to scroll the page when a finger is dragged. We can counteract this with a combination of JavaScript and CSS.

To prevent the browser from dragging an image as a file reference when using a mouse, we set pointer-events to none on the list items:

[data-list] > li {
  pointer-events: none;
}

pointer-events: none instructs the browser to ignore any clicking on the element. Interactions will "pass through" this element to any elements directly underneath it.

Next, to make sure the drawing area works as intended, we add a bevy of prefixed properties to the CSS:

[data-selectarea] {
  position: relative;
  -webkit-user-select: none;
     -moz-user-select: none;
      -ms-user-select: none;
          user-select: none;
  -ms-touch-action: none;
}

user-select: none prevents the highlighting effect of selecting text to occur within the drawing area. This is mostly for cosmetic purposes; user-select: none doesn't actually prevent the user from selecting text, it just removes the visual element.

If you're a fan of Compass or Bourbon, both of these libraries include mixins to output the prefixed versions of user-select for you:

// Compass
@import "compass/css3";
@import "compass/css3/user-interface"

[data-selectarea] {
  @include user-select(none);
}

// Bourbon
@import "bourbon";

[data-selectarea] {
  @include user-select(none);
}

-ms-touch-action: none is a property specific to Internet Explorer 10. It instructs the browser to ignore actions like panning, pinch to zoom, or other gestures on the element. This prevents the viewport from scrolling when the user wants to draw.

Making Selections

Now for the big time. Let's break down the selection process from start to finish.

// This code runs when Wrangle is initialized
this.$container  = elem;
this.canvas      = this.$container.find('canvas')[0];

// We're just drawing flat lines, so we ask for a 2D context
this.draw        = this.canvas.getContext('2d');

Wrangle.prototype.drawLine = function(from, to, context) {
  // You, the developer, can specify the size and color of the line
  context.strokeStyle = this.settings.lineColor;
  context.lineWidth   = this.settings.lineWidth;

  // These settings give the lines a smooth appearance
  context.lineJoin    = 'round';
  context.lineCap     = 'round';

  // This instructs the canvas to begin a path
  context.beginPath();
  // The line starts at these coordinates...
  context.moveTo(from.x, from.y);
  // ...and it ends at these coordinates
  context.lineTo(to.x, to.y);
  // We're done drawing the path, so now we close it
  context.closePath();
  // However, the line won't actually be visible until we stroke it with the given color and stroke size
  context.stroke();
}

Wrangle.prototype.checkCollision = function(coords, prev) {
  // The defenition of "this" changes inside $.each, so let's store a reference to it here
  var self = this;

  // Iterate through each item's bounding box
  $.each(self.itemBoxes, function(index) {
    // If this === window, then we're inside an empty part of the array
    if (this === window) return;

    // "this" refers to the item's bounding box
    var rect = this;

    // Now that we've got a bounding box, iterate through every coordinate we have
    $.each(coords, function(i) {

      // If the two intersect...
      if (rect.intersects(this.x, this.y)) {
        var elem = self.$items.eq(index);
        // ...select it!
        self.select(elem, index);
        // The select method will only add an item that isn't already selected
      }
    });
  });
}