Behavior Definition

You’ll sometimes need a behavior that hasn’t been packaged up for you already. Here’s what that looks like:

{
  priority: 0,
  helpers: {
    handy: function() {}
  },
  transform: function(elem) {
    ...
    returns elem
  },
  events: {
    click: function(event) {
      ... this.element ...
    },
    mouseover: ...,
    ...
  }
}

A behavior has two major parts: at most one transform and some event methods.

The transform is a method takes an element – which is the target of the behavior – and returns an element (which can be the same element). If you’re going to be replacing elements in the DOM, do it here and return the one you put in.

The event handlers will get bound to the resulting element. They’re a slightly different API than the usual “onevent” handlers.

Important to the way the behavior operates is that there is a unique behavior object for each behavior application, so the transform method can store data on this and the event handlers will be able to retreive it. Or, event handlers can store their own data.

Behaviors can also have helpers, which will be made available to the transform function and all the event handlers. Generally, they’re just code that’s handy to reuse for this particular behavior.

Finally, a Behavior can be assigned a priority which is used in Behavior Composition.

Behavior tools

There are a lot of tools available within a behavior: this is merely a cheatsheet for some of them.

this.fireMutationEvent()

NinjaScript works by watching for MutationEvents and applying behaviors in response. Certain browsers that will remain nameless do not implement this DOM Event interface in any form. There’s a whole other discussion there… As a result, if you do modify the DOM, you’ll need to call this to signal the change. Behavior application triggers one, so transforms don’t need to call this, and event handlers can be tagged to do this automatically, but sometimes you want to make it conditional.

this.copyAttributes(from, to, which)

Especially in transforms, it’s useful to copy attributes in bulk between elements.

from	the source element
to	the destination element
which	an array of strings (RegExp syntax accepted) that name or match the attributes to be copied

this.cantTransform()

Raises an exception – use this in a transform method if you’re passed an element that you can’t process. There’ll be a nice log message to let you know, and this behavior will be cancelled for the element.

this.applyBehaviors(element, behaviorList)

Apply behaviors while transforming or during an event handler. Really good for behaviors that only make sense together.

element	the behavior target
behaviorList	an array of actual Behavior objects – simply resolving to a behavior isn’t enough

this.message(text)

Send a message to the user – you’ll need to make sure the Ninja is configured to target an element to insert messages into

this.ajaxSubmitter()

Gets an XMLHTTPRequest wrangler object. Has a nice, uniform interface for handling events, and some conveniences like a default fireMutationEvent() – since we assume that by the time you’re done processing a response, you will have modified the DOM.

this.busyOverlay()

Real crowd pleaser: create an overlay for an element (or list of elements), complete with spinner. The result has two important methods: affix() which will display the overlays and prevent interaction with the elements, and remove() which will remove the overlay.

this.stash(element) this.cascadeEvent(name)

stash() puts an element in a behavior-local list. cascadeEvent() sends an event to the elements in that list. This is superior to saving a removed element in a field and sending the event directly for two reasons:

It’s a well known location, so multiple behaviors can each have a crack at each other’s transformed elements and still know where to find them
The targeted elements will be stuck back in the DOM in a hidden div, so we can be sure that the browser will honor the event.