harvard-lil/stackview — pull request #13 by imakewebthings (2012-03-07 06:46:21+00:00)
Title: API additions

This pull is for issue #5. If these additions all look good I think we may be able to close #5, and if any other methods should be added we can open individual tickets. Here's a rundown of what's new:

### `add([index, ] item)

```js
$('#stack').stackView('add', { /* book object */ }); // adds to end of stack
$('#stack').stackView('add', 0, { /* book object */ }); // adds to beginning of stack
```

When an item is added the stack element fires an event, `stackview.itemadded`.

### `remove(index | item | element | jQuery)`

Remove takes either an index, a book object, the raw HTML element of the book, or a jQuery wrapped object of that element. So each of the following are valid:

```js
$('#stack').stackView('remove', 2); // Remove book at index 2
```

```js
$('#stack').stackView('remove', { /* book object */ }); // Remove this book
```

```js
var el = document.getElementById('#pretendBooksHaveIds');
$('#stack').stackView('remove', el);
```

```js
var $el = $('#pretendBooksHaveIds');
$('#stack').stackView('remove', $el);
```

Remove also fires an event on the stack element, `stackview.itemremoved`. The event is passed the book data object from the removed element, should any handlers want to do something with that information.

```js
$('#stack').bind('stackview.itemremoved', function(event, item) {
console.log(item); // Same object that was part of the initial docs array
});
```

### `getData()`

Simple, returns an array of all the data objects in the stack.

```js
var bookObjects = $('#stack').stackView('getData');
```

### `zIndex(reverse)`

This was previously an internal method. Each of the books on the stack need a z-index lower than the book below it, so that lower books do not visually overlap higher books. I exposed this publicly in case a developer wanted to do something like move books around and needs to re-set the z-indexes. It doesn't need to be called when adding/removing or anything else built into Stack View.

The `reverse` parameter is a boolean. You can leave it blank to do what I just described, or pass `true` to "reverse" the z-indexes, effectively putting the books back into natural page flow order. Just threw this in in case somebody wanted to make an alternate visualization that didn't want the reversed flow order.