The entire interface for the Uize.Widget.HoverFader class is exposed through its set-get properties.

There are no special methods for this class. All methods and other properties are inherited from the Uize.Widget base class. All that one does in order to utilize this widget is to instantiate it with the desired settings.

The Uize.Widget.HoverFader class is flexible enough to enable a healthy array of CSS style property fade effects.

Many of the CSS style properties can be faded using this class, including...

	color style properties: color, background, backgroundColor, borderColor, borderTopColor, borderRightColor, borderBottomColor, borderLeftColor
	position style properties: top, right, bottom, left, backgroundPosition
	padding and margin style properties: padding, paddingTop, paddingRight, paddingBottom, paddingLeft, margin, marginTop, marginRight, marginBottom, marginLeft
	dimension style properties: width, height, maxWidth, maxHeigh, borderWidth, borderTopWidth, borderRightWidth, borderBottomWidth, borderLeftWidth
	font style properties: fontSize, letterSpacing, wordSpacing, lineHeight, textIndent

NOTES

	values for color style properties can be specified in single digit, three digit, or six digit hex RGB format - with or without the "#" (hash / pound sign) prefix
	values for position and dimension style properties can be specified as strings with the "px" suffix (eg. '100px') or simply as numbers (eg. 100)

Configurable fade properties let you control the rate of the fade-in independently of the rate of the fade-out, and any other set-get properties of the Uize.Fade class (such as acceleration and deceleration) can be specified for both the fade-in and fade-out.

The nodes that you wire up with this widget can be of any type: links, divs, spans, etc.

Each instance of the Uize.Widget.HoverFader class manages the hover fade effect for a set of nodes. The class doesn't much care what the relationship between the nodes is. They can be clumped together in the layout in the form of a set of menu links, or they can be inline links interspersed throughout a paragraph, or just plain old anywhere. To supply the class with your nodes, you can use any means for gathering those nodes. One approach would be to use the Uize.Node.find static method to find nodes that match given criteria - such as class name, or tag type, or a combination thereof.

The Uize.Widget.HoverFader widget class falls into the category of Progressive Enhancement (or "unobtrusive JavaScript") widgets.

HTML that is enhanced with this widget will still function if the widget fails to wire, some library module fails to load, or JavaScript is disabled. The widget instance becomes essentially a vehicle for storing the effect configuration for the group of nodes that it manages, and doesn't present its own UI. Using the widget architecture also allows the behavior to be unwired using the unwireUi instance method.

The example below demonstrates how a set of menu links could be wired with a hover color fade effect.

EXAMPLE

page.addChild (
  'menuHoverFader',
  Uize.Widget.HoverFader,
  {
    nodes:Uize.Node.find ({root:'menu',className:/\bmenuLink\b/}),
    defaultStyle:{color:'bbb',backgroundColor:'000',borderColor:'555'},
    hoverStyle:{color:'fff',backgroundColor:'77a',borderColor:'000'},
    fadeIn:{duration:500,deceleration:1},
    fadeOut:{duration:750,acceleration:1}
  }
);

In the above example, the Uize.Widget.HoverFader instance is being added as a child widget to a page widget instance, so the effect will be wired up when the page widget instance is wired. The value for the nodes set-get property specifies the nodes that should be wired up with the effect. The nodes being supplied in this case are obtained through a call to the Uize.Node.find static method. Based on the options specified in the call, the Uize.Node.find method will find all nodes with a class name of "menuLink" that are in a node tree with a node of the id "menu" at its root.

The defaultStyle set-get property specifies the color style property values for the default state of the nodes (ie. when not mousing over them), in this case light gray text on a black background with a dark gray border. The hoverStyle set-get property specifies the color style property values for the hover state of the nodes (ie. when mousing over them), in this case white text on a pastel blue background with a black border.

The fadeIn set-get property specifies properties for the fade process that is used to fade the node that is currently being moused over from the defaultStyle styling to the hoverStyle styling, in this case with a duration of 500 milliseconds and accelerating through the entire fade. The fadeOut set-get property specifies properties for the fade process that is used to fade the node that is currently being moused out of from the hoverStyle styling back to the defaultStyle styling, in this case with a duration of 750 milliseconds and accelerating through the entire fade. A greater duration for the fade-out will result in a lingering trail, and the acceleration will accentuate this quality.

Lets you initiate a "tickling" of the nodes of the instance, emulating the effect of the user moving their mouse across the nodes.

SYNTAX

myInstance.tickle (intervalINT);

The intervalINT parameter lets you specify an interval, measured in milliseconds, between triggering of the fade-outs for the different nodes of the instance.

VARIATION 1

myInstance.tickle ();

When no intervalINT parameter is specified, then its value will be defaulted to 100.

VARIATION 2

myInstance.tickle (fadePropertiesOBJ);

When the fadePropertiesOBJ parameter is specified in place of the intervalINT parameter, then an object containing fade properties (ie. set-get properties of the Uize.Fade class) can be specified to configure the fade that drives the tickling of the nodes.

Among other things, this allows one to specify a curve property for the fade, so that the timing of the triggering of the fade-outs for the different nodes of the instance is not uniform. In addition, one can use the reverse fade property to control the order in which the tickling occurs. Specifying the value true for the reverse fade property will cause the tickling to start with the last node and end at the first node.

When using this parameter, it is not possible to specify an interval between triggering the different nodes. Instead, one specifies the duration of the overal tickling process in the duration fade property. Because a non-linear curve can be specified, a single interval value is not meaningful, anyway.

EXAMPLE 1

myHoverFader.tickle ({duration:1000});

In the above example, the nodes of the instance myHoverFader are being tickled over a period of 1000 milliseconds (1 second). Specifying the fadePropertiesOBJ parameter in place of the intervalINT parameter lets you control the overal duration of the tickling process with the duration fade property. The number of nodes can change, but the overal duration of the tickling will remain the same. By contrast, the overal duration would change as the number of nodes changes when using the intervalINT paramter.

EXAMPLE 2

myHoverFader.tickle ({duration:1000,reverse:true,curve:Uize.Curve.resolve (-3)});

In the above example, the nodes of the instance myHoverFader are being tickled over a period of 1000 milliseconds (1 second), starting from the last node and ending at the first node, and starting out slowly and accelerating towards the end (the expression Uize.Curve.resolve (-3) creates a cubic ease-in curve function).

An object, whose properties specify the values for CSS style properties at the start of the hover fade-in (and also the end of the hover fade-out).

EXAMPLE VALUE

{
  width:'110px',
  borderLeftWidth:'1px',
  color:'bbb',           // light gray
  backgroundColor:'000', // black
  borderColor:'555'      // dark gray
}

The defaultStyle object may contain values for any of the supported CSS style properties (see the section Fading CSS Style Properties). The structure of the object should match the structure of the companion hoverStyle set-get property's value, or the effect will not work correctly. In other words, if the defaultStyle object contains a value for borderColor, then the hoverStyle object must also contain a value for this style property.

For a more complete example of how this set-get property is used in conjunction with other set-get properties, consult the section An Example.

NOTES

	for best effect, style property values specified in this property should match the initial style property values for the nodes (as determined by stylesheet rules for your page)
	see the companion hoverStyle set-get property
	the initial value is {color:'fff',backgroundColor:'000'}

An object, specifying fade properties for the fade-in phase (ie. when mousing over a node) of the hover fade effect.

If the default fade-in duration does not suit your needs, you should at least use this property to configure a suitable duration. Any valid set-get properties of the Uize.Fade class (such as acceleration and deceleration) can be specified in the fadeIn object, and these values will be applied when the fade-in starts.

EXAMPLE VALUE

{
  duration:500,
  acceleration:1
}

NOTES

	see the companion fadeInOut and fadeOut set-get properties
	the initial value is {duration:250}

An object, specifying fade properties that are common to both the fade-in phase (ie. when mousing over a node) and the fade-out phase (ie. when mousing out of a node) of the hover fade effect.

EXAMPLE

page.addChild (
  'menuHoverFader',
  Uize.Widget.HoverFader,
  {
    defaultStyle:{color:'b',backgroundColor:'0'},
    hoverStyle:{color:'0',backgroundColor:'f'},
    fadeInOut:{
      curve:{
        backgroundColor:[
          Uize.Curve.Mod.band (1,.5,0),
          Uize.Curve.Mod.band (1,.5,.5),
          Uize.Curve.Mod.band (1,.5,1)
        ]
      }
    },
    fadeIn:{duration:500},
    fadeOut:{duration:1250}
  }
);

In the above example, a Uize.Widget.HoverFader instance is being added to the page widget as a child widget named menuHoverFader. The fadeInOut set-get property is being used to specify fade properties that are common to both the fade-in and fade-out phases of the hover fade effect.

These settings achieve a "hot" fade from black to white (and vice versa), where the background color transitions through shades of reds and yellows. This is accomplished by specifying different curve functions for the red, green, and blue components of the color tuple for the backgroundColor CSS style property. Now, because we want the fade-in to be faster than the fade-out, we are using the fadeIn and fadeOut set-get properties as well to provide the fade properties that are different for the two phases - in this case, the duration fade property values.

3.3.1. Common Duration

3.3.2. Special Handling of reverse Fade Property

NOTES

	see the companion fadeIn and fadeOut set-get properties
	the initial value is undefined

An object, specifying fade properties for the fade-out phase (ie. when mousing out of a node) of the hover fade effect.

If the default fade-out duration does not suit your needs, you should at least use this property to configure a suitable duration. Any valid set-get properties of the Uize.Fade class (such as acceleration and deceleration) can be specified in the fadeOut object, and these values will be applied when the fade-out starts.

EXAMPLE VALUE

{
  duration:1000,
  acceleration:.5
  deceleration:.5
}

NOTES

	see the companion fadeIn and fadeInOut set-get properties
	the initial value is {duration:350}

An object, whose properties specify the values for CSS style properties at the end of the hover fade-in (and also the start of the hover fade-out).

EXAMPLE VALUE

{
  width:'100px',
  borderLeftWidth:'11px',
  color:'fff',           // white
  backgroundColor:'77a', // pastel blue
  borderColor:'000'      // black
}

The hoverStyle object may contain values for any of the supported CSS style properties (see the section Fading CSS Style Properties). The structure of the object should match the structure of the companion defaultStyle set-get property's value, or the effect will not work correctly. In other words, if the hoverStyle object contains a value for borderColor, then the defaultStyle object must also contain a value for this style property.

For a more complete example of how this set-get property is used in conjunction with other set-get properties, consult the section An Example.

NOTES

	for best effect, style property values specified in this property should match the hover style property values for the nodes (as determined by stylesheet rules for your page)
	see the companion defaultStyle set-get property
	the initial value is {color:'000',backgroundColor:'fff'}

An array or collection of nodes or a find expression object, specifying the nodes that should be wired up with the hover fade effect.

The value of this property can be...

	a string, being the id of a single node to wire up
	a node reference to a single node to wire up
	an array of nodes to wire up, where each element can be a string, or node reference
	an object, being a find expression (see the Uize.Node.find static method)

EXAMPLE 1

var hoverFader = new Uize.Widget.HoverFader ({
  nodes:['link1Id','link2Id','link3Id']
});

EXAMPLE 2

var hoverFader = new Uize.Widget.HoverFader ({
  nodes:document.getElementsByTagName ('A')
});

EXAMPLE 3

var hoverFader = new Uize.Widget.HoverFader ({
  nodes:{tagName:'A',className:'hoverFadeLink'}
});

Each instance of the Uize.Widget.HoverFader class manages a set of nodes. For more information on the types of nodes that can be wired up and how they can be obtained, consult the section Any Nodes.

NOTES

the initial value is undefined