API Basics

Introduction

NodeFire is a stand-alone navigation widget focused library. The library currently includes a menu widget and lightbox. Optional modules with additional widgets are planned for future releases.

The menu widget enhances NodeFire Pure CSS drop down menus with scripted API control. Existing Pure CSS menus and HTML list structures may be converted to NodeFire Pure CSS by specifying classNames on your structure Nodes (see 'CSS Foundation' for more details).

We use the term 'Pure CSS' to describe the menus ability to function in the absence of JavaScript. The widget library is an enhancement add-on, vs. a replacement or DOM generated menu. If a browser has JavaScript enabled the library will seemlessly take control of the pure CSS menu and apply scripted enhancements.

The library includes a multitude of exposed API classes and methods required by the widgets. The classes may be used to simplify and enhance other scripts and elements on your page. NodeFire is contained in a single namespace and is compatible with popular base libraries such as JQuery, YUI, prototype, and others.

Loading The API

The download includes uncompressed, and Gzipped versions of the library. Include a reference to the library JS file in the head of your documents in the standard way. If your server compresses and delivers GZipped files, the total library will run around 30K, if you are only using the lightbox, menu, etc..., the size will drop further.

Library Namespace

The NodeFire library is contained within a single namespace using the global object name 'NF'. The only exception is the '$' shortcut, this is identical to calling getElementByID. The shortcut is included for user familiarity with jQuery type libraries. Note: without jQuery present the $ does not have the ability to do anything other than act as a shortcut to 'getElementByID. If you are using NodeFire with another '$' library, place the NodeFire script reference last.

All API calls start with 'NF'. Below is an example API call which creates a menu object.

Creating Menu Objects

Applying API script to a NodeFire Pure CSS menu already on the page simply requires creating and activating a new menu object.

A new menu menu object may also be instantiated from a string containing an HTML structure. The example below creates a new menu after the document loads in response to a button click event.

Menu Config Properties

The menu object constructor accepts optional configuration properties which define the delay timers and events which will hide and show sub menus.

Options for the triggers include 'mouseover' or 'click'. The 'itemTrigger' can be a single string or array of strings where each item cooresponds with a menu level starting at the main. In the example below the main menu trigger is 'click' while the subs and documentTriggers use 'mouseover'.

Adding Items

Items can be added to an existing active menu object at any time. The example code below is handled by a function attached to a buttons click event.

Items can also be created using an object literal with optional properties defining the contents of the item.

Any child subs of items defined by string, object literal, or node references will be included. In the example below a main item with child subs is added using a string. The childs subs are are made visible for the user with setActivePath.

Adding a Sub Menu

Sub menus may be added to an existing active menu object at any time. The example code below is handled by a function attached to a buttons click event.

Object literals may also be used to create sub menus and items. The example below create a sub with a title item and items with links.

Removing A Menu Node

Removing a sub menu, item, or other menu node may be done with the standard DOM removeChild method or the menuManagers removeChild. The menuManger supports multiple Node removal by passing it an array.

You can move a node by adding the removed item to a new location. In some situations you can achieve the same results in less code space using the standard DOM JavaScript methods. Just remember to re-activate the menu if you need to.

Getting Node References

The API includes a multitude of methods for quickly retrieving references to menu items, subs, and other nodes. The NF.widget.hierStructure and NF.widget.menuManager classes include methods containing most of the functionality required to quickly access specific items in your menu.

The example below shows how to get all of a menu structures 1st level links, and then applies a red color to the text as an inline style. To show the user the change we then find the first child sub and set a visible path.

Similar API methods have the ability to reference specific sub menus, items, links, or elements based on class names. The example below evaluates an expression to get all the sub menus equal to or greater than level 0. We then apply a thicker border and show the user by setting an active path.

The final example shows how to use the NF.util.dom class to get a reference to all parent items based on className. We then apply a distinct background color to help identify which items have child subs.

Animation Basics

The NodeFire library includes a robust animation class (NF.anim) capable of applying effects to any elements numeric or color based style properties. The styleAnim, clip, track, timeline, player, and playerSynchronizer classes offer complete movie like production capabilites to the rendering and playing of your node effects.

The basic process used to apply animation effects to a document node is to create clips containing styleAnim objects. The player class acts like a VCR (or DVR) and controls the clip rendering with the typical play, stop, pause, reverse, and step features.

The example below uses styleAnim, Clip, and Player objects to move a nodes 'style.left' property a specified number of frames.

The above example code can be simplified with short cuts.

The styleAnim class animates any numeric or color based style setting from a start to end value in a specified number of frames. Animate top, left, width, height, clip, opacity, border, margin, padding, color, and other styles. Any valid CSS unit of measure is supported (e.g. px, em, cm, etc.). The example below animates the fontSize of a node using 'em' units.

Custom frame delay timers are passed as the second paramter argument to a new player object. The third argument optionally tells the player how many times to loop the animation. The example below slows down the frame rate a bit and loops a 'backgroundColor' animation.

Timeline Fundamentals

Timelines combine tracks containing single or multiple clips into animation effects which play simultaneously. A timeline may be passed to a new player object in the same way a clip is passed. The NodeFire timeline concept works in a traditional fasion similar to Flash and video production software such as Sony Vegas Pro.

Each player object may reference a single timeline consisting of any number of tracks. Each track may contain any number of clips which may be associated with any number of styleAnim objects. The styleAnim objects can further render any number of style property effects.

Individual clips, represent and apply styleAnim effects to a single document Node. Virtually any animation effect is possible, and synchronized by the player object when clips referencing different nodes combined with multiple tracks are rendered.

The example below adds two clips to a new timeline. The clips are by default added as sequential clips in a single track and will be played back to back.

In the next example each clip is added as a separate track which will play simultaneously.

Since styleAnim objects may contain multiple start to end style properties, the example above may be simplified with a single clip.

The example below overlays 30 frame clips across two 15 frame clips with multiple tracks. This more complex example illustrates how combining tracks is used to render animation effects simultaneously. The box position (left to right, then right to left), font size (small to large), and background color (red to orange) changes simultaneously using the palyer objects sychronized frame timer.

Below is an example of multiple nodes animating. Each moves diagonally to the same central position while changing color and growing by animating the padding.

Animating Menus

Animation clips and timelines can be applied as a transition to the menu widget through the transition class. Specifying a clip hook will tell the menu when to trigger the animation transition. Below are the available hooks.

  • 'NFplayOnSubShow' - Plays on the sub Node ('nfSubC') when made visible.
  • 'NFplayOnSubHide' - Plays on the sub Node ('nfSubC') before hiding.
  • 'NFplayOnLinkActiveShow' - Plays on a link Node ('nfLink') when it's associated child sub is made visible.
  • 'NFplayOnLinkActiveHide' - Plays on a link Node ('nfLink') before it's associated child sub is hidden.
  • 'NFplayOnLinkHoverShow' - Plays on a link Node ('nfLink') when hovered over with the mouse.
  • 'NFplayOnLinkHoverHide' - Plays on a link Node ('nfLink') when the mouse leaves the Node.
  • 'NFplayOnLinkFocusShow' - Plays on a link Node ('nfLink') when receiving focus through a click or keyboard event.
  • 'NFplayOnLinkFocusHide' - Plays on a link Node ('nfLink') when focus is lost through a click or keyboard event..

The following example uses the 'NFplayOnSubShow' and 'NFplayOnSubHide' hooks combined with clips animating the opacity style. Typically clips animate a single node, however the transition class will dynamically apply nodes based on the clips hook property.

Any number and combination of clips, tracks, and styleAnims may be included in a timeline applied to a transition. Advanced features of the styleAnim and clip classes allow for start and end values to be relative to specific nodes, child or parent nodes may be targeted for animation, and style properties may be applied at the beginning and end of a clip. See the API Documentation or the advanced section for additional details.

The example below utilizes some of the more advanced features of the styleAnim class to target clip and top styles relative to the animating node. Multiple clips are combined into timelines with separate tracks. The example show animation quickly moves the sub nodes down while clipping the size of the node from the center out.

The following example applies trasition animations to items with child subs. It animates a background image arrow from outside the node into a visible position.

Set a Visible Path

Setting a sub visible simply requires passing the menuManagers setActivePath method the node to activate. The menuManager will activate and display all ancestor subs up to the root menu node. All animation effects and active item styling is applied. The example below uses an id ('mySubRef') attached to a sub to get the node.

The 'holdSubsUntilInteraction' property is optional and forces the path to stay visible until the user interacts with the menu or clicks the document. The method is handy for showing a starting menu location when the menu first loads.