com.github.ilyes4j.gwt.mdl.components

Class ComponentHandler

java.lang.Object

com.github.ilyes4j.gwt.mdl.components.ComponentHandler

public final class ComponentHandler
extends Object

Exposes the functions provided by componentHandler.

On mdl components

An mdl component is an html DOM decorated with css selectors and enhanced with js behaviors. In order for the component to react to user input, listen to events and display effect and animations, it has to be "upgraded".
Behaviors that should be acquired by the component are defined in the component's js class. For example, MaterialMenu is the js class that contains the behaviors to be applied on menu and MaterialButton is the js class that operates on buttons. In general, a component class definess :

• The transformations to be applied on the DOM of the component
• The events to be setup on the DOM tree of the component
• The actions to be performed in response to these events

Declarative mdl components

When the page is loaded, componentHandler is initiated. The components classes are then defined. Each defined component registers itself to componentHandler and is mapped to a css selector. For example, MaterialMenu is mapped to mdl-js-menu when it is registered in componentHandler .

For each registered class, componentHandler will retrieve the mapped css and scan the DOM looking for elements decorated with that css selector. The matched elements are to be upgraded using instances of the component's class. Again, with the menus example, when componentHandler finds an element in the DOM containing the css selector mdl-js-menu, it sets up a new instance of MaterialMenu and feeds it with the element node of the menu.

The created instance of MaterialMenu will then "upgrade" the menu. It detaches the node from the DOM and puts a container in its place. Then, it puts back the menu node inside the container and puts a background node just before the menu node. The background node is of animation use when the menu is opened.

If the menu contains a ripple css selector mdl-js-ripple-effect, the MaterialMenu instance will add a ripple container in each item of the menu.

The MaterialMenu instance then retrieves the for attribute from the menu element. That attributes holds the id of the action button that will show the menu when it is clicked. It, then, locates the button in the DOM and adds a click listener to it. It then adds the appropriate event handlers to close the menu.

All these behaviors occur without the intervention of the developer who simply includes the mdl script into the page header and setup the DOM of the required components.

Dynamically generated components

Sometimes, components are setup and added to the the DOM after componentHandler scans the DOM looking for components to be upgraded. In that case, componentHandler will not find the dynamically generated components because they are not attached to the DOM yet. To handle this use case, componentHandler exposes a set of functions to deal with dynamically generated components.

Depending on the the Material JS Class that will manage the upgrade process, it might be required that the Element to be upgraded is attached to the DOM before firing the upgrade. For instance MaterialMenu require that the to-be-upgraded component is already attached to the DOM and since MaterialMenu also scans the DOM looking for the action button related to the menu it also requires that this button is itself attached to the DOM.

These requirements are enforced by GWT-MDL itself whenever possible to prevent the developer from having to deal with the details and requirements of each component.

Author:

Mohamed Ilyes DIMASSI

Method Summary

Methods

Modifier and Type	Method and Description
static void	downgradeElement(com.google.gwt.dom.client.Element element) Intuitively, one could think that the downgrade function symetrically does the exact opposite of what the upgrade function does but in fact it does not.
static void	upgradeElement(com.google.gwt.dom.client.Element element) Upgrade a specific component rather than all components of the DOM.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

upgradeElement

public static void upgradeElement(com.google.gwt.dom.client.Element element)

Upgrade a specific component rather than all components of the DOM. To upgrade a component, its DOM Element must be provided as input. The Element node to be provided is the node decorated with the mdl-js-xxx css selector.The DOM tree of the component must follow the guidelines enforced on declarative components regarding the expected html and css styling.

Parameters:

element - the target html node of the component to be upgraded.

downgradeElement

public static void downgradeElement(com.google.gwt.dom.client.Element element)

Intuitively, one could think that the downgrade function symetrically does the exact opposite of what the upgrade function does but in fact it does not. Downgrading an MDL component just means remove the javascript object of the related MDL component from the MDL dictionary of referenced components. It simply doesn't do more than that.

Parameters:

element - the DOM node to downgrade