Specializes Montage

Properties

application :Application source

Convenience to access the application object.

childComponents :Array.<Component> <readonly> source

The child components of the component. This property is readonly and should never be changed.

classList :Set source

The classList of the component's element, the purpose is to mimic the element's API but to also respects the draw cycle.

It can also be bound to by binding each class as a property. example to toggle the complete class:

"classList.has('complete')" : { "<-" : "@owner.isComplete"}

Default Value:	null

delegate :Object source

A delegate is an object that has helper methods specific to particular components. For example, a TextField may consult its deletate's shouldBeginEditing() method, or inform its delegate that it didBeginEditing(). Look for details on the documentation of individual components' delegate properties.

Default Value:	null

element :DOMElement source

The element of the component as defined in the template.

{
   "component": {
       "properties": {
           "element": {"#": "dataMontageId"}
       }
   }
}

DOM arguments can be passed to the component as direct children of the element. By default the entire content of the element is considered the single DOM argument of the component. Multiple arguments can be given by assigning a data-arg attribute to each element that represents an argument.

<div data-montage-id="component">
    <h1 data-arg="title"></h1>
    <div data-arg="content">
        <span data-montage-id="text"></span>
    <div>
</div>

If the component has a template then this element is replaced by the element that is referenced in its template just before the component enters the document.

{
   "owner": {
       "properties": {
           "element": {"#": "dataMontageId"}
       }
   }
}

The component element has a component property that points back to the component. This property is specially useful to extrapolate the component tree from the DOM tree. It can also be used for debugging purposes, on the webkit inspector when an element is selected it's possible to find its component by using the $0.component command on the console.

The element of a component can only be assigned once, it's not possible to change it.

Default Value:	null

eventManager :EventManager source

Convenience to access the defaultEventManager object.

getTemplateArgumentElement source

TemplateArgumentProvider implementation

hasTemplate :boolean source

Specifies whether the component has an HTML template file associated with it.

Default Value:	true

localizer :Localizer source

The localizer for this component

Default Value:	null

needsDraw :boolean source

The purpose of this property is to trigger the adding of the component to the draw list. The draw list consists of all the components that will be drawn on the next draw cycle.

The draw cycle itself is triggered by the requestAnimationFrame API where available, otherwise a shim implemented with setTimeout is used.

When it happens, the draw cycle will call, in succession, and when they exist, the methods: willDraw, draw, and didDraw.

At the end of the draw cycle this property is set back to false.

Default Value:	false

nextTarget :Target source

The next Target to consider in the event target chain

Currently, components themselves do not allow this chain to be broken; setting a component's nextTarget to a falsy value will cause nextTarget to resolve as the parentComponent.

To interrupt the propagation path a Target that accepts a falsy nextTarget needs to be set at a component's nextTarget.

ownerComponent :Component source

The owner component is the owner of the template form which this component was instantiated.

Default Value:	null

parentComponent :Component source

The parent component is the component that is found by walking up the DOM tree, starting at the component's element. Each component element has a component property that points back to the component object, this way it's possible to know which component an element represents.

This value is null for the RootComponent.

rootComponent :RootComponent source

Convenience to access the rootComponent object.

template :Template source

The template object of the component.

Default Value:	null

templateObjects :Object source

This property is populated by the template. It is a map of all the instances present in the template's serialization keyed by their label.

Default Value:	null

waitForLocalizerMessages :boolean source

Whether to wait for the localizer to load messages before drawing. Make sure to set the localizer before setting to true.

Default Value:	false

Example

// require localizer
var defaultLocalizer = localizer.defaultLocalizer,
    _ = defaultLocalizer.localizeSync.bind(defaultLocalizer);

exports.Main = Component.specialize( {

    constructor: {
        value: function() {
            this.localizer = defaultLocalizer;
            this.waitForLocalizerMessages = true;
        }
    },

    // ...

    // no draw happens until the localizer's messages have been loaded
    enterDocument: {
        value: function(firstTime) {
            if (firstTime) {
                this._greeting = _("hello", "Hello {name}!");
            }
        }
    },
    draw: {
        value: function() {
            // this is for illustration only. This example is simple enough that
            // you should use a localizations binding
            this._element.textContent = this._greeting({name: this.name});
        }
    }
}

Methods

addBeforeOwnPropertyChangeListener(name, handler) → {function} source

Adds a listener that will be notified before a property changes. See addOwnPropertyChangeListener for details.

Parameters:

Name	Type	Description
name	string
handler	object | function

Inherited From:	Montage#addBeforeOwnPropertyChangeListener
See:	Montage#addOwnPropertyChangeListener

Returns: function

cancel

addBeforePathChangeListener(path, handlerMethodName) source

Establishes an observer such that the handler will receive a notification when the value of an FRB expression is about to change. See addPathChangeListener for details.

Parameters:

Name	Type	Description
path	string
	object | function
handlerMethodName	string

Inherited From:	Montage#addBeforePathChangeListener
See:	Montage#addPathChangeListener

addComposer(composer) source

Adds the passed in composer to the component's composer list.

Parameters:

Name	Type	Description
composer	Composer

addComposerForElement(composer, element) source

Adds the passed in composer to the component's composer list and sets the element of the composer to the passed in element.

Parameters:

Name	Type	Description
composer	Composer
element	Element

addOwnPropertyChangeListener(name, handler, beforeChange) → {function} source

Adds a change listener for the named property of this instance. The handler may be a function or an object with a handler method. When the property changes on this object, the handler will be notified on the stack.

The dispatcher will try to dispatch to only the most specific handler method available, from handle + PropertyName (bactrian camel case) + Change, to handlePropertyChange, or if the beforeChange flag is set, handle + PropertyName + WillChange then handlePropertyWillChange. The arguments to the handler are value, name, and this.

Parameters:

Name	Type	Description
name	string	The name of the property to observe.
handler	object | function	On which to dispatch change notifications.
beforeChange	boolean	Whether to observer changes before they occur. To avoid the boolean trap, try to use addBeforeOwnPropertyChangeListener instead, unless beforeChange is truly variable.

Inherited From:	Montage#addOwnPropertyChangeListener
See:	Montage#addBeforeOwnPropertyChangeListener

Returns: function

cancel, useful for removing the change listener without having to retain and reconstruct all of the arguments.

addPathChangeListener(path, handler, handlerMethodName, beforeChange) source

Creates an observer for the value of an FRB expression. The observer will immediately dispatch a notification to the handler of the initial value of the expression, before returning.

If the expression's value is an array, this will be the final notification and all subsequent changes will be reflected by the content of the array. Use addRangeAtPathChangeListener if you want discrete notifications for changes to the content of an expression that evaluates to an array.

Use removePathChangeListener to cancel all involved change listeners.

Parameters:

Name	Type	Description
path	string	an FRB expression.
handler	object | function	an object with a handler method, or a function. The handler will be called with value, path, and this as arguments.
handlerMethodName	string	the method name on the handler on which to dispatch change notifications, if the handler is not a function.
beforeChange	boolean	instructs the path change listener to dispatch before the change has occurred. Avoid using this boolean trap by making use of the named method addBeforePathChangeListener. Using this flag remains desireable only if beforeChange is indeed variable.

Inherited From:	Montage#addPathChangeListener

addRangeAtPathChangeListener(path, handler, methodName) → {function} source

Observes changes to the content of the value for an FRB expression. The handler will receive “ranged content change” messages. When a change listener is added, the handler will be immediately invoked with the initial content added at index 0 for the expression.

Parameters:

Name	Type	Argument	Description
path	string		an FRB expression that produces content changes
handler			a function that accepts plus, minus, and index arguments, or a handler object with a designated method by that signature. plus and minus are arrays of values that were added or removed. index is the offset at which the minus was removed, then the plus was added.
methodName	string	<nullable>	the name of the method on the handler object that should receive change messages.

Inherited From:	Montage#addRangeAtPathChangeListener

Returns: function

cancel function for removing the range at path change listener. Until removeRangeAtPathChangeListener is implemented, this is the only way to disable this kind of observer.

callDelegateMethod(name) source

This method calls the method named with the identifier prefix if it exists. Example: If the name parameter is "shouldDoSomething" and the caller's identifier is "bob", then this method will try and call "bobShouldDoSomething"

Parameters:

Name	Type	Description
name	string

Inherited From:	Montage#callDelegateMethod

cancelBinding(targetPath) source

Cancels a binding and removes its descriptor from the object's binding descriptor index. This will in turn cause any change listeners needed on far reaching objects for the binding to be canceled. A component should call this if the binding reaches into objects it does not itself own to ensure that they are available for garbage collection.

Parameters:

Name	Type	Description
targetPath	string	The target path used to establish the binding.

Inherited From:	Montage#cancelBinding

cancelBindings() source

Cancels all registered bindings on this object.

Inherited From:	Montage#cancelBindings

clearAllComposers() source

A convenience method for removing all composers from a component. This method is responsible for calling unload on each composer before removing it.

createActionEvent() source

Convenience to create a custom event named "action"

Returns:

and event to dispatch upon interaction

defineBinding(targetPath, descriptor) source

Establishes a binding between two FRB expressions. See the FRB documentation for information about FRB paths/expressions. There can only be one binding per target path on an object.

Parameters:

Name	Type	Description
targetPath	string
descriptor	object	A descriptor has at least an arrow property, "<-", "<->". The corresponding string is the sourcePath for the binding and the type of arrow determines whether the binding is one way (from source to target) or if data flows both directions. The descriptor may contain a converter or reverter object, or directly provide convert and revert functions. Converters and reverters have convert and revert methods. The convert function or method transforms data from the source to the target. The revert function or method transforms data from the target to the source and is necessary if there is a converter on a two-way binding. A reverter is the same as a converter, but the polarity is reversed. This is useful for reusing converters that were designed for data flowing the “wrong” way. The descriptor may also provide a trace flag for console debugging.

Inherited From:	Montage#defineBinding

defineBindings(descriptors, commonDescriptor) source

Establishes multiple bindings.

Parameters:

Name	Type	Argument	Description
descriptors	object		an object for which every property is a source path and every value is a binding descriptor as described by defineBinding.
commonDescriptor	object	<nullable>	a partial binding descriptor with properties intended to be shared by all of the established bindings.

Inherited From:	Montage#defineBindings
See:	Montage#defineBinding

didDraw() source

This method is part of the draw cycle and it provides the component an opportunity to query the DOM for any necessary calculations after drawing. If the execution of this method sets needsDraw to true on other components, those components will be added to the current draw cycle.

Components should not change the DOM during this phase of the draw cycle as it could force an unwanted reflow from the browser.

See:	http://montagejs.org/docs/Component-draw-cycle.html

dispatchBeforeOwnPropertyChange(name, value) source

Manually dispatches a notification that a property is about to change. See dispatchOwnPropertyChange.

Parameters:

Name	Type	Description
name	string
value

Inherited From:	Montage#dispatchBeforeOwnPropertyChange
See:	Montage#dispatchOwnPropertyChange

dispatchOwnPropertyChange(name, value, beforeChange) source

Manually dispatches a property change notification on this object. This can be useful if the property is a getter or setter and its value changes as a side effect of some other operation, like cache invalidation. It is unnecessary to dispatch a change notification in the setter of a property if it modifies its own value, but if changing celicius has a side effect on fahrenheit, they can manually dispatch changes to the other. Be sure to dispatch both the change and before the change.

Parameters:

Name	Type	Description
name	string
value
beforeChange	boolean	Avoid the boolean trap and use dispatchBeforeOwnPropertyChange. You are not likely to encounter a case where beforeChange is a named variable.

Inherited From:	Montage#dispatchOwnPropertyChange

draw() source

This method is part of the draw cycle and is the prescribed location for components to update its DOM structure or modify its styles.

Components should not read the DOM during this phase of the draw cycle as it could force an unwanted reflow from the browser.

See:	http://montagejs.org/docs/Component-draw-cycle.html

enterDocument(firstTime) source

This function is called when the component element is added to the document's DOM tree.

Parameters:

Name	Type	Description
firstTime	boolean	true if it's the first time the component enters the document.

equals(anObject) → {boolean} source

Returns true if two objects are equal, otherwise returns false.

Parameters:

Name	Type	Description
anObject	Object	The object to compare for equality.

Inherited From:	Montage#equals

Returns: boolean

Returns true if the calling object and anObject are identical and their uuid properties are also equal. Otherwise, returns false.

exitDocument() source

Lifecycle method called when this component is removed from the document's DOM tree.

extractDomArgument(name) source

This function extracts a DOM argument that was in the element assigned to the component. The star (*) argument refers to the entire content of the element when no data-arg was given.

When a DOM argument is extracted from a Component it is no longer available

Parameters:

Name	Type	Description
name	string	The name of the argument, or "*" for the entire content.

Returns:

the element

getBinding(targetPath) → {object} source

Gets the binding descriptor for a target path.

Parameters:

Name	Type	Description
targetPath	string

Inherited From:	Montage#getBinding
See:	Montage#defineBinding

Returns: object

the descriptor for the binding. See defineBinding for information on the descriptor type.

getBindings() → {object} source

Gets the binding descriptors for all target paths.

Inherited From:	Montage#getBindings
See:	Montage#defineBinding

Returns: object

an object that maps traget paths to binding descriptors. See defineBinding for information on the descriptor type.

getOwnPropertyChangeDescriptor(name) source

Produces the descriptor for a property change listener. The descriptor is an object that will contain two arrays, willChangeListeners and changeListeners. Each listener will be the handler given to establish the change listener on addOwnPropertyChangeListener or addBeforeOwnPropertyChangeListener.

Parameters:

Name	Type	Description
name	string

Inherited From:	Montage#getOwnPropertyChangeDescriptor
See:	Montage#addOwnPropertyChangeListener Montage#addBeforeOwnPropertyChangeListener

Returns:

the property change descriptor for this name, created if necessary.

getPath(path) source

Evaluates an FRB expression from this object and returns the value. The evaluator does not establish any change listeners.

Parameters:

Name	Type	Description
path	string	an FRB expression

Inherited From:	Montage#getPath

Returns:

the current value of the expression

getPathChangeDescriptor(path, handler, beforeChange) source

Gets the path change descriptor object for an observer established previously by addPathChangeListener or addBeforePathChangeListener.

Parameters:

Name	Type	Description
path	string	an FRB expression
handler		a function that will receive a value change notification, or an object with a method that will receive the change notifications
beforeChange	boolean

Inherited From:	Montage#getPathChangeDescriptor

Returns:

a path change descriptor. Such objects have path, handler, beforeChange, and cancel properties. The cancel method is for internal use only. It cancels the observer, but does not perform any book keeping on the index of path change descriptors.

getPathChangeDescriptors() source

Returns an internal index of all of the path change descriptors associated with this instance.

Inherited From:	Montage#getPathChangeDescriptors
See:	Montage#getPathChangeDescriptor

Returns:

an object that maps property names to an object with two Maps, changeListeners and willChangeListeners. Each of these maps handler objects to path change descriptors. See getPathChangeDescriptor for a description of that type.

hasOwnPropertyChangeDescriptor(name) source

Determines whether a property has ever been observed. Removing all property change listeners does not destroy this record.

Parameters:

Name	Type	Description
name	string

Inherited From:	Montage#hasOwnPropertyChangeDescriptor

makePropertyObservable(name) source

An overridable method for ensuring that changes to the named property dispatch notifications. The default behavior is to wrap the property with a getter and setter.

Parameters:

Name	Type	Description
name	string

Inherited From:	Montage#makePropertyObservable

observePath(path, emit) → {function} source

Observes changes to the value of an FRB expression. The content of the emitted value may react to changes, particularly if it is an array.

Parameters:

Name	Type	Description
path	string	an FRB expression
emit	function	a function that receives new values in response to changes. The emitter may return a cancel function if it manages event listeners that must be collected when the value changes.

Inherited From:	Montage#observePath

Returns: function

a canceler function that will remove all involved change listeners, prevent new values from being observed, and prevent previously emitted values from reacting to any further changes.

prepareForActivationEvents() source

Called by the EventManager before dispatching a touchstart or mousedown.

The component can implement this method to add event listeners for these events before they are dispatched.

removeBeforeOwnPropertyChangeListener(name, handler) source

Removes a change listener established by addBeforeOwnPropertyChangeListener or addOwnPropertyChangeListener with the beforeChange flag. Call with the same arguments used to set up the observer.

Parameters:

Name	Type	Description
name	string
handler	object | function

Inherited From:	Montage#removeBeforeOwnPropertyChangeListener
See:	Montage#addOwnPropertyChangeListener Montage#addBeforeOwnPropertyChangeListener

removeBeforePathChangeListener(path, handlerMethodName, beforeChange) source

Removes a path change listener previously established by a call to addBeforePathChangeListener. The given arguments must match the original. See addPathChangeListener for descriptions of their meaning.

Parameters:

Name	Type	Description
path	string
	object | function
handlerMethodName	string
beforeChange	boolean

Inherited From:	Montage#removeBeforePathChangeListener
See:	Montage#addBeforePathChangeListener Montage#addPathChangeListener

removeComposer(composer) source

Removes the passed in composer from this component's composer list. It takes care of calling the composers unload method before removing it from the list.

Parameters:

Name	Type	Description
composer	Composer

removeOwnPropertyChangeListener(name, handler, beforeChange) source

Cancels a change listener established with the same given parameters. For the meanings of the parameters, see addOwnPropertyChangeListener.

Parameters:

Name	Type	Description
name	string
handler	object | function
beforeChange	boolean

Inherited From:	Montage#removeOwnPropertyChangeListener
See:	Montage#addOwnPropertyChangeListener

removePathChangeListener(path, handlerMethodName, beforeChange) source

Removes a path change listener previously established by a call to addPathChangeListener. The given arguments must match the original. See addPathChangeListener for descriptions of their meaning.

Parameters:

Name	Type	Description
path	string
	object | function
handlerMethodName	string
beforeChange	boolean

Inherited From:	Montage#removePathChangeListener
See:	Montage#addPathChangeListener

scheduleComposer(composer) source

Adds the passed in composer to the list of composers which will have their frame method called during the next draw cycle. It causes a draw cycle to be scheduled iff one has not already been scheduled.

Parameters:

Name	Type	Description
composer	Composer

setPath(path, value) source

Assigns a value to the FRB expression from this object. Not all expressions can be assigned to. Property chains will work, but will silently fail if the target object does not exist.

Parameters:

Name	Type	Description
path	string	an FRB expression designating the value to replace
value		the new value

Inherited From:	Montage#setPath

surrenderPointer(pointer, demandingComponent) → {boolean} source

Ask this component to surrender the specified pointer to the demandingComponent.

The component can decide whether or not it should do this given the pointer and demandingComponent involved.

Some components may decide not to surrender control ever, while others may do so in certain situations.

Returns true if the pointer was surrendered, false otherwise.

The demandingComponent is responsible for claiming the surrendered pointer if it desires.

Parameters:

Name	Type	Description
pointer	string	The pointerIdentifier that the demanding component is asking this component to surrender
demandingComponent	Object	The component that is asking this component to surrender the specified pointer

Returns: boolean

true

willDraw() source

This method is part of the draw cycle and it provides the component an opportunity to query the DOM for any necessary calculations before drawing. If the execution of this method sets needsDraw to true on other components, those components will be added to the current draw cycle.

Components should not change the DOM during this phase of the draw cycle as it could force an unwanted reflow from the browser.

See:	http://montagejs.org/docs/Component-draw-cycle.html

Generated from v0.14.14