Provides the base class for most visual objects the user will interact with. A component encapsulates a DOM element and provides methods to handle a hierarchy of components.
Initialization
Syntax:
var component = new Moobile.Component([element], [options], [name]);
Parameters:
Name | Type | Description |
---|---|---|
element Optional |
Element | The component’s element, element id or html string. |
options Optional |
Object | The component’s options, see below. |
name Optional |
String | The component’s name. |
Options:
Name | Type | Description |
---|---|---|
className |
String | The component’s extended CSS class name, defaults to null . |
styleName |
String | The component’s default style, defaults to null . |
tagName |
String | The component’s element tag name, defaults to div . |
Notes:
Upon initialization, a component builds its hierarchy using the element
given to the constructor. It will looks for elements with the data-role
attribute and execute their definitions recursively. The example section shows how to create components with complex hierarchies.
Subclassing Notes:
Don’t instantiate this class. Instead, extend it by creating subclasses for your own implementation.
Examples:
Creating an empty component:
var component = new Moobile.Component();
Creating a component with a single child:
var element =
'<div>' +
'<div data-role="button" data-name="my-button">Button</div>' +
'</div>';
var component = new Moobile.Component(element);
component.getChildComponent('my-button'); // returns a Moobile.Button instance
Creating a component with multiple children:
var element =
'<div>' +
'<img data-role="image" data-name="my-image" />' +
'<div data-role="button" data-name="my-button-1">Button 1</div>' +
'<div data-role="button" data-name="my-button-2">Button 2</div>' +
'</div>';
var component = new Moobile.Component(element);
component.getChildComponent('my-image'); // returns a Moobile.Image instance
component.getChildComponent('my-button-1'); // returns a Moobile.Button instance
component.getChildComponent('my-button-2'); // returns a Moobile.Button instance
Creating a component with a complex hierarchy:
var element =
'<div>' +
'<div data-role="button" data-name="my-button">' +
'<img data-role="image" data-name="my-button-image" />' +
'<div data-role="label">Button 2</div>' +
'</div>' +
'</div>';
var component = new Moobile.Component(element);
component.getChildComponent('my-button-image'); // returns null! The image is a child of the button.
component.getChildComponent('my-button').getChildComponent('my-button-image'); // returns a Moobile.Image instance.
Creating a component that passes options using element attributes:
var element =
'<div data-option-style-name="moo" data-option-some-option="value">' +
'</div>';
var component = new Moobile.Component(element);
Events
ready
Fired when this component becomes ready.
A component is ready when its hierarchy is assigned to a window and therefore in the DOM. Upon being ready, a component can access its window and perform tasks such as measuring.
tap
Fired when this component receives a touchend
event with only one touch. The tap
event is cancelled when the current touch moves more than 10
pixels.
tapstart
Fired when this component receives a touchstart
event with only one touch.
tapmove
Fired when this component receives a touchmove
event with only one touch.
tapend
Fired when this component receives a touchend
event with only one touch.
touchstart
Fired when this component receives a standard touchstart
event.
touchmove
Fired when this component receives a standard touchmove
event.
touchend
Fired when this component receives a standard touchend
event.
pinch
Fired when this component receives a pinch
event.
swipe
Fired when this component receives a swipe
event.
show
Fired when this component becomes visible.
hide
Fired when this component becomes hidden.
owntransitionend
Fired when a CSS transition finishes. The transition must be applied to this component’s root element.
ownanimationend
Fired when a CSS animation finishes. The animation must be applied to this component’s root element.
Members
element
The element managed by this component.
Type
Element
options
The component’s options.
Type
Object
Name | Type | Description |
---|---|---|
className |
String | The component’s extended CSS class name, defaults to null . |
styleName |
String | The component’s default style, defaults to null . |
tagName |
String | The component’s element tag name, defaults to div . |
Methods
addChildComponent(component, [where])
Adds the specified component at the top
or bottom
of this component. If where
is omitted, the specified component will be added at the bottom.
Parameters:
Name | Type | Description |
---|---|---|
component |
Moobile.Component | The component. |
where Optional |
String | The component’s location, either top or bottom , defaults to bottom . |
Returns:
Moobile.Component
This Moobile.Component instance.
Examples:
Adding a component at the top:
var componentOne = new Moobile.Component('<div class="component-one"><span>Lorem</span></div>')
var componentTwo = new Moobile.Component('<div class="component-two"></div>');
componentOne.addChildComponent(componentTwo, 'top');
Resulting element:
<div class="component-one">
<div class="component-two"></div>
<span>Lorem</span>
</div>
Adding a component at the botom:
var componentOne = new Moobile.Component('<div class="component-one"><span>Lorem</span></div>')
var componentTwo = new Moobile.Component('<div class="component-two"></div>');
componentOne.addChildComponent(componentTwo, 'bottom');
Resulting element:
<div class="component-one">
<span>Lorem</span>
<div class="component-two"></div>
</div>
addChildComponentInside(component, element, [where])
Adds the specified component at the top
or bottom
of this component’s element. If where
is omitted, the specified component will be added at the bottom
of this component’s element.
Parameters:
Name | Type | Description |
---|---|---|
component |
Moobile.Component | The component. |
element |
Mixed | The component’s element or a CSS selector. |
where Optional |
String | The component’s location, either top or bottom , defaults to bottom . |
Returns:
Moobile.Component
This Moobile.Component instance.
Example:
var componentOne = new Moobile.Component('<div class="component-one"><div class="me"></div></div>')
var componentTwo = new Moobile.Component('<div class="component-two"></div>');
componentOne.addChildComponentInside(componentTwo, '.me');
Resulting element:
<div class="component-one">
<div class="me">
<div class="component-two"></div>
</div>
</div>
addChildComponentAfter(component, after)
Adds the specified component after another child of this component.
Parameters:
Name | Type | Description |
---|---|---|
component |
Moobile.Component | The component. |
after |
Moobile.Component | The component will be placed after this component. |
Returns:
Moobile.Component
This Moobile.Component instance.
Example:
var componentOne = new Moobile.Component('<div class="component-one"></div>');
var componentTwo = new Moobile.Component('<div class="component-two"></div>');
var componentThree = new Moobile.Component('<div class="third"></div>');
componentOne.addChildComponent(componentTwo);
componentOne.addChildComponentAfter(componentThree, componentTwo);
Resulting element:
<div class="component-one">
<div class="component-two"></div>
<div class="third"></div>
</div>
addChildComponentBefore(component, before)
Adds the specified component before another child of this component.
Parameters:
Name | Type | Description |
---|---|---|
component |
Moobile.Component | The component. |
before |
Moobile.Component | The component will be placed before this component. |
Returns:
Moobile.Component
This Moobile.Component instance.
Example:
var componentOne = new Moobile.Component('<div class="component-one"></div>');
var componentTwo = new Moobile.Component('<div class="component-two"></div>');
var componentThree = new Moobile.Component('<div class="third"></div>');
componentOne.addChildComponent(componentTwo);
componentOne.addChildComponentBefore(componentThree, componentTwo);
Resulting element:
<div class="component-one">
<div class="third"></div>
<div class="component-two"></div>
</div>
getChildComponent(name)
Returns a component that matches the specified name.
Parameters:
Name | Type | Description |
---|---|---|
name |
String | The name of the component to search for. |
Returns:
Moobile.Component
The component ornull
if no components were found with that name.
Example:
var componentOne = new Moobile.Component('<div class="component-one"></div>');
var componentTwo = new Moobile.Component('<div class="component-two"></div>', null, 'my-second-component');
componentOne.addChildComponent(componentTwo);
componentOne.getChildComponent('my-second-component'); // returns componentTwo
getChildComponentOfType(type, name)
Returns a component of a specified type that matches the specified name.
Parameters:
Name | Type | Description |
---|---|---|
type |
Class | The component’s class. |
name |
String | The name of the component to search for. |
Returns:
Moobile.Component
The component ornull
if no components of that type were found with the name.
Example:
var component = new Moobile.Component();
var button = new Moobile.Button(null, null, 'foo');
var image = new Moobile.Image(null, null, 'foo');
component.addChildComponent(button);
component.addChildComponent(image);
component.getChildComponentOfType(Moobile.Image, 'foo'); // returns image
getChildComponentAt(index)
Returns a component at a specified index.
Parameters:
Name | Type | Description |
---|---|---|
index |
Number | The index location of the component. |
Returns:
Moobile.Component
The component ornull
if no components were found at the index.
Example:
var component = new Moobile.Component();
var button = new Moobile.Button();
var image = new Moobile.Image();
component.addChildComponent(button);
component.addChildComponent(image);
component.getChildComponentAt(0); // returns button
getChildComponentOfTypeAt(type, index)
Returns a component of a specified type at a specified index.
Parameters:
Name | Type | Description |
---|---|---|
type |
Class | The component’s class. |
index |
Number | The component’s index. |
Returns:
Moobile.Component
The component ornull
if no components of that type were found at the index.
Example:
var component = new Moobile.Component();
var button = new Moobile.Button();
var image = new Moobile.Image();
component.addChildComponent(button);
component.addChildComponent(image);
component.getChildComponentOfTypeAt(Moobile.Image, 0); // returns image
getChildComponentIndex(component)
Returns the index of a specified component or -1
if the component is not a child of this component.
Parameters:
Name | Type | Description |
---|---|---|
component |
Moobile.Component | The component to search for. |
Returns:
Number
The component index or-1
if the component is not present in this component.
Example:
var component = new Moobile.Component();
var button = new Moobile.Button();
var image = new Moobile.Image();
component.addChildComponent(button);
component.addChildComponent(image);
component.getChildComponentIndex(Moobile.Image); // returns 1
getChildComponents()
Returns all components in this component.
Returns:
Array
An array of all components in this component.
Example:
var component = new Moobile.Component();
var buttonOne = new Moobile.Button();
var buttonTwo = new Moobile.Button();
component.addChildComponent(buttonOne);
component.addChildComponent(buttonTwo);
component.getChildComponents(); // returns [buttonOne, buttonTwo]
getChildComponentsOfType(type)
Returns all components of a specified type in this component.
Parameters:
Name | Type | Description |
---|---|---|
type |
Class | The component’s class. |
Returns:
Array
An array of components of a specified type in this component.
Example:
var component = new Moobile.Component();
var buttonOne = new Moobile.Button();
var buttonTwo = new Moobile.Button();
var image = new Moobile.Image();
component.addChildComponent(buttonOne);
component.addChildComponent(buttonTwo);
component.addChildComponent(image);
component.getChildComponentsOfType(Moobile.Button); // returns [buttonOne, buttonTwo]
hasChildComponent(component)
Indicates whether a component is present in this component.
Parameters:
Name | Type | Description |
---|---|---|
component |
Moobile.Component | The component to search for. |
Returns:
Boolean
Whether the component is present in this component.
Example:
var component = new Moobile.Component();
var button = new Moobile.Button();
component.addChildComponent(button);
component.hasChildComponent(button); // returns true
hasChildComponentOfType(type)
Indicates whether this component has at least one component of the specified type.
Parameters:
Name | Type | Description |
---|---|---|
type |
Class | The component’s class. |
Returns:
Boolean
Whether this component has at least one component of that type.
Example:
var component = new Moobile.Component();
var button = new Moobile.Button();
var image = new Moobile.Image();
component.addChildComponent(button);
component.addChildComponent(image);
component.hasChildComponentOfType(Moobile.Image); // returns true
getDescendantComponent(name)
Returns a component that matches the specified name within all the child components recursively.
Parameters:
Name | Type | Description |
---|---|---|
name |
String | The name of the component to search for. |
Returns:
Moobile.Component
The component ornull
if no components were found with that name.
Example:
var componentOne = new Moobile.Component('<div class="component-one"></div>');
var componentTwo = new Moobile.Component('<div class="component-two"></div>', null, 'my-second-component');
var componentThree new Moobile.Component('<div class="component-two"></div>', null, 'my-third-component');
componentOne.addChildComponent(componentTwo);
componentTwo.addChildComponent(componentThree);
componentOne.getChildComponent('my-third-component'); // returns componentThree
replaceChildComponent(component, replacement, [destroy])
Replaces a component with another.
Parameters:
Name | Type | Description |
---|---|---|
component |
Moobile.Component | The component to remove. |
replacement |
Moobile.Component | The component to replace it with. |
destroy Optional |
Boolean | Whether to destroy the component upon removal. |
Returns:
Moobile.Component
This Moobile.Component instance.
Example:
var component = new Moobile.Component();
var buttonOne = new Moobile.Button();
var buttonTwo = new Moobile.Button();
component.addChildComponent(buttonOne);
component.replaceChildComponent(buttonOne, buttonTwo); // Replaces buttonOne with buttonTwo
removeChildComponent(component, [destroy])
Removes a component.
Parameters:
Name | Type | Description |
---|---|---|
component |
Moobile.Component | The component to remove. |
destroy Optional |
Boolean | Whether to destroy the component upon removal. |
Returns:
Moobile.Component
This Moobile.Component instance.
Example:
var component = new Moobile.Component();
var button = new Moobile.Button();
component.addChildComponent(button);
component.removeChildComponent(button); // Removes button
removeAllChildComponents([destroy])
Removes all components.
Parameters:
Name | Type | Description |
---|---|---|
destroy Optional |
Boolean | Whether to destroy the components upon removal. |
Returns:
Moobile.Component
This Moobile.Component instance.
removeAllChildComponentsOfType(type, [destroy])
Removes all components of a specified type.
Parameters:
Name | Type | Description |
---|---|---|
type |
Class | The component’s class. |
destroy Optional |
Boolean | Whether to destroy the components upon removal. |
Returns:
Moobile.Component
This Moobile.Component instance.
Example:
var component = new Moobile.Component();
var buttonOne = new Moobile.Button();
var buttonTwo = new Moobile.Button();
var image = new Moobile.Image();
component.addChildComponent(buttonOne);
component.addChildComponent(buttonTwo);
component.addChildComponent(image);
component.removeAllChildComponentsOfType(Moobile.Button); // Removes buttonOne, buttonTwo
removeFromParentComponent([destroy])
Removes this component from its parent.
Parameters:
Name | Type | Description |
---|---|---|
destroy Optional |
Boolean | Whether to destroy the component upon removal. |
Returns:
Moobile.Component
This Moobile.Component instance.
setParentComponent(parent)
Sets the parent of this component.
This method is handled by the Moobile.Component
class and should not be called manually.
Parameters:
Name | Type | Description |
---|---|---|
parent |
Moobile.Component | The parent. |
Returns:
Moobile.Component
This Moobile.Component instance.
getParentComponent()
Returns the parent of this component.
Returns:
Moobile.Component
The parent component.
hasParentComponent()
Indicates whether this component has a parent.
Returns:
Boolean
Whether this component has a parent.
setWindow(window)
Sets the window that contains this component.
This method is handled by the Moobile.Component
class and should not be called manually.
Parameters:
Name | Type | Description |
---|---|---|
window |
Moobile.Window | The window. |
Returns:
Moobile.Component
This Moobile.Component instance.
getWindow()
Returns the window that contains this component.
Returns:
- Moobile.Window The window.
hasWindow()
Indicates whether this component has a window.
Returns:
Boolean
Whether this component as a window.
setReady()
Sets whether this component is ready.
A component is ready when its element is assigned to a window and therefore in the DOM. Upon being ready, a component can access its window and perform tasks such as measuring.
This method is handled by the Moobile.Component
class and should not be called manually.
Returns:
Moobile.Component
This Moobile.Component instance.
isReady()
Indicates whether this component is ready.
A component is ready when its element is assigned to a window and therefore in the DOM. Upon being ready, a component can access its window and perform tasks such as measuring.
Returns:
Boolean
Whether this component is ready.
getName()
Returns this component’s name.
Returns:
String
This component’s name.
setStyle(name)
Sets the style of this component.
Parameters:
Name | Type | Description |
---|---|---|
name |
String | The style name. |
Returns:
Moobile.Component
This Moobile.Component instance.
getStyle()
Returns the current style name.
Returns:
String
The current style name ornull
if no style is set.
hasStyle(name)
Indicates whether the specified style is currently applied to this component.
Returns:
Boolean
Whether the specified style is currently applied to this component.
addClass(name)
Adds the specified CSS class to this component’s element.
Parameters:
Name | Type | Description |
---|---|---|
name |
String | The CSS class. |
Returns:
Moobile.Component
This Moobile.Component instance.
removeClass(name)
Removes the specified CSS class from this component’s element.
Parameters:
Name | Type | Description |
---|---|---|
name |
String | The CSS class. |
Returns:
Moobile.Component
This Moobile.Component instance.
toggleClass(name, force)
Adds or removes the specified CSS class from this component.
Parameters:
Name | Type | Description |
---|---|---|
name |
String | The CSS class. |
force Optional |
Boolean | Force the class to be either added or removed |
Returns:
Moobile.Component
This Moobile.Component instance.
getElement(selector)
Returns this component’s element or the first element within this component’s element that matches the specified selector.
Parameters:
Name | Type | Description |
---|---|---|
selector Optional |
String | An CSS selector. |
Returns:
Element
This component’s element or the first element that matches the selector.
getElements(selector)
Returns a collection of elements from this component’s element that matches the specified selector.
Parameters:
Name | Type | Description |
---|---|---|
selector |
String | The CSS selector. |
Returns:
Elements
A collection of elements.
hasElement(element)
Indicates whether the specified element is a child of this component’s element.
Parameters:
Name | Type | Description |
---|---|---|
element |
Element | The element. |
Returns:
Boolean
Whether the element exists.
getRoleElement(name)
Returns the first element within this component’s element that matches the specified role.
Parameters:
Name | Type | Description |
---|---|---|
name |
String | The role. |
Returns:
Element
The first element within this component’s element that matches the specified role.
Example:
var component = new Moobile.Component('<div><div data-role="button"></div></div>');
component.getRoleElement('button'); // Returns <div data-role="button"></div>
var component = new Moobile.Component('<div><div data-role="button"><div data-role="label"></div></div></div>');
component.getRoleElement('label'); // Returns null because the element with the 'label' role is inside an element with the 'button' role
getRoleElements(name, limit)
Returns a collection of elements from this component’s element that matches the specified role.
Parameters:
Name | Type | Description |
---|---|---|
name |
String | The role. |
limit Optional |
Number | The maximal amount of elements that can be returned. |
Returns:
Array
A collection of elements from this component’s element that matches the specified role.
getSize()
Returns this component’s size as an object with two keys, x
to indicate the width and y
to indicate the height.
The component must be ready when calling this method otherwise it won’t be measured.
Returns:
Object
This component’s size.
getPosition([relative])
Returns this component’s position relative to a specified element. If omitted, the position returned will be relative to its parent.
The component must be ready when calling this method otherwise it won’t be measured.
Parameters:
Name | Type | Description |
---|---|---|
relative |
Mixed | The position will be relative to this element or component |
Returns:
Object
This component’s position.
show()
Shows this component. This method will also remove the hidden
CSS class from this component’s element.
This method fires the show
event.
Returns:
Moobile.Component
This Moobile.Component instance.
hide()
Hides this component. This method will also add the hidden
CSS class from this component’s element.
This method fires the hide
event.
Returns:
Moobile.Component
This Moobile.Component instance.
willBuild()
Tells this component it’s about to be built. This method is called once this component’s element is set and before its roles are being processed.
Override this method to provide your own implementation.
didBuild()
Tells this component it has been built.
Override this method to provide your own implementation.
didBecomeReady()
Tells this component it has become ready.
A component is ready when its element is assigned to a window and therefore in the DOM. Upon being ready, a component can access its window and perform tasks such as measuring.
Override this method to provide your own implementation.
willAddChildComponent(component)
Tells this component a component is about to be added.
Override this method to provide your own implementation.
Parameters:
Name | Type | Description |
---|---|---|
component |
Moobile.Component | The component that is about to be added. |
didAddChildComponent(component)
Tells this component a component has been added.
Override this method to provide your own implementation.
Parameters:
Name | Type | Description |
---|---|---|
component |
Moobile.Component | The component that has been added. |
willRemoveChildComponent(component)
Tell this component a child component is about to be removed.
Override this method to provide your own implementation.
Parameters:
Name | Type | Description |
---|---|---|
component |
Moobile.Component | The component that is about to be removed. |
didRemoveChildComponent(component)
Tell this component a child component has been removed.
Override this method to provide your own implementation.
Parameters:
Name | Type | Description |
---|---|---|
component |
Moobile.Component | The component that has been removed. |
parentComponentWillChange(parent)
Tell this component it’s about to be moved to another component.
Override this method to provide your own implementation.
Parameters:
Name | Type | Description |
---|---|---|
parent |
Moobile.Component | The component this component will be moved to. |
parentComponentDidChange(parent)
Tell this component it has been moved to a new component.
Override this method to provide your own implementation.
Parameters:
Name | Type | Description |
---|---|---|
parent |
Moobile.Component | The component this component has been moved to. |
windowWillChange(window)
Tell this component it’s about to be moved to another window.
Override this method to provide your own implementation.
Parameters:
Name | Type | Description |
---|---|---|
window |
Moobile.Window | The window this component will be moved to. |
windowDidChange(window)
Tell this component it has been moved to a new window.
Override this method to provide your own implementation.
Parameters:
Name | Type | Description |
---|---|---|
parent |
Moobile.Window | The window this component has been moved to. |
willShow()
Tell thid component it’s about to become visible.
Override this method to provide your own implementation.
didShow()
Tell this component it became visible.
Override this method to provide your own implementation.
willHide()
Tell this component it’s about to become hidden.
Override this method to provide your own implementation.
didHide()
Tell this component it became hidden.
Override this method to provide your own implementation.
destroy()
Remove this component from its parent, destroy its hierarchy and prepare it for garbage collection.
If you override this method, make sure you call the parent method at the end of your implementation.
Returns:
Moobile.Component
This Moobile.Component instance.
Static Methods
Moobile.Component.defineRole(name, context, options, handler)
Define the process to execute upon finding an element with the given role.
Parameters:
Name | Type | Description |
---|---|---|
name |
String | The name. |
context |
Moobile.Component | The context component or null to define the role for all components. |
options |
Object | The options. |
handler |
Function | The function that handles this role. |
Options:
Name | Type | Description |
---|---|---|
traversable |
Boolean | Defines whether this component will go continue looking for element with roles within this element upon building, defaults to false . |
Examples:
For every element with the data-role="wrapped"
attribute found in all types of components, an element will be created and wrapped around it.
Moobile.Component.defineRole('wrapped', null, null, function(element) {
new Element('div.wrapped').wraps(element);
});
For every elements with the data-role="button"
attribute within a Moobile.ButtonGroup
control, a new Moobile.Button
instance will be created and added to the group as a child component.
Moobile.Component.defineRole('button', Moobile.ButtonGroup, null, function(element) {
var button = new Moobile.Button(element);
this.addChildComponent(button);
});
Moobile.Component.defineAttribute(name, context, handler)
Define the process to execute upon finding a specified attribute of the component’s element.
Name | Type | Description |
---|---|---|
name |
String | The name. |
context |
Moobile.Component | The context component or null to define the role for all components. |
handler |
Function | The function that handles this attribute. |
Example:
Moobile.Component.defineAttribute('data-style', null, function(value) {
this.options.styleName = value;
});
Moobile.Component.defineStyle(name, target, behavior)
Defines a style for a component or all components if target
is set to null
.
Parameters:
Name | Type | Description |
---|---|---|
name |
String | The style name. |
target |
Moobile.Component | The target component or null to define the role for all components. |
behavior |
Object | The style definition, which consists of an object with an attach and detach method. |
Example:
Moobile.Component.defineStyle('glowing', Moobile.Button, {
attach: function() {
this.addClass('glow');
},
detach: function() {
this.removeClass('glow');
}
});