Data

The Data

Reel stores all its inner state values with the standard DOM data interface interface while adding an additional change-detecting event layer, which makes Reel entirely data-driven.

For all data access you use .reel( key, [ value ] ) function. For example let's say you want to find out on what frame the Reel instance currently is:

.reel('frame') // Returns the frame number

Think of .reel() as a synonym for .data(). Note, that you can therefore easily inspect the entire datastore with .data() (called without arguments). Use it only for inspection though.

Storing Values

You can store any value the very same way by passing the value as the second function argument. For example let's say you want to jump to frame 12:

.reel('frame', 12)

Only a handful of data keys is suitable for external manipulation. These include area, backwards, brake, fraction, frame, playing, reeling, row, speed, stopped, velocity and vertical. Use the rest of the keys for reading only, you can mess up easily changing them.

Until now, reading and writing the value was a usual business just like using jQuery .data() and this is where Reel takes an enhanced approach of detecting a new value for you.

Changes

Any value that does not equal (===) the old value is considered new value and in such a case Reel will trigger a change event to announce the change. The event type/name takes form of keyChange, where key will be the data key/name you've just assigned. For example, setting "frame" to 12 in the above example will trigger "frameChange".

Some of these change events (like frame or fraction) have a default handler attached.

You can easily bind to any of the data key change with standard event binding methods. For example, let's say you want to react on instance being manipulated by the user - whether it is reeling:

.bind('reelingChange', function(evnt, nothing, reeling){
  if (reeling) console.log('Rock & reel!')
  else console.log('Not reeling...')
})

The handler function will be executed every time the value changes and it will be supplied with three arguments. First one is the event object as usual, second is undefined and the third will be the actual value. In this case it was a boolean type value.

If the second argument is not undefined it is the backward compatible "before" event triggered from outside Reel.

Backward Compatibility

In 1.2 you don't have to manually trigger change events anymore.

Things were a bit different though in 1.1 - the change event was not triggered automatically and you needed to trigger it yourself in order to actually set the value. For example let's say you wanted to jump to the 12th frame, you had to do:

.trigger('frameChange', 12)

This way of setting a value of frame, row or fraction is still supported in order to not break your code right away and it will still work. However this approach is now deprecated and is strongly discouraged.

Note, that in 1.3 this backward compatibility with 1.1 will be removed.