Hemi JavaScript Framework
Hemi.app.comp
Description
The Application Component is a portable and reusable set of code that can act as code-behind for HTML elements, quickly instrument event handling, and quickly load external templates within their own Application Space.
Class Index
static Hemi.app.comp.ApplicationComponent
version 3.1.0
Static initializer for ApplicationComponentInstance objects.
Index
Method Index
- public bindComponent: Binds the specified HTML Node or XHTMLComponent object to the specified Application Component, and returns the Application Component.
- public newInstance: Creates a new ApplicationComponentInstance object.
Methods
bindComponent
Binds the specified HTML Node or XHTMLComponent object to the specified Application Component, and returns the Application Component.
Syntax
a = bindComponent(
o, i, c, p, a
)
Parameters
- o as variant : HTML DOM Node or String id of registered XHTMLComponent.
- i as String : Identifier of the component to bind to.
- c as String : Path to the external XML file containing the component definition.
- p as String (optional): Participant id.
- a as boolean (optional): Load synchronously.
Returns
a as ApplicationComponentInstance: Instance of an ApplicationComponent.
newInstance
Creates a new ApplicationComponentInstance object.
Syntax
a = newInstance(
i, o, c, f, p, b
)
Parameters
- i as String : Identifier of the component to create.
- o as variant : XHTML/HTML Node or function pointer.
- c as String (optional): Container identifier.
- f as function (optional): Load handler. Handler is invoke with two parameters: The string "onloadappcomp", and the ApplicationComponentInstance object that was loaded.
- p as String (optional): Participant id.
- b as boolean (optional): Bit indicating whether the application component should bind to its XHTMLComponent container.
Returns
a as ApplicationComponentInstance: Instance of an ApplicationComponent.
Hemi.app.comp.ApplicationComponentInstance
version 3.1.0
A code fragment in a private scope that may be bound to HTML Nodes, and/or XHTMLComponent objects, and which provides a controlled environment for code execution and management.
Index
Example Index
Property Index
- public object_config (internal): Object API structure for storing sub structures: object_config.pointers and object_config.status.
- public object_id (internal): Unique instance identifier.
- public object_type (internal): The type of this object.
- public object_version (internal): Version of the object class.
- public ready_state (internal): Object load and execution state. Follows: 0 unitialized, 1 through 3 variant, 4 ready, 5 destroyed.
Method Index
- virtual _handle_event: Handler for a specific event, where event is one of the following: change, focus, blur, mouseover, mouseout, click. When binding a component with one of these handlers, the event instrumentation is done automatically.
- public _handle_template_processor (internal): Buffered handler for Space Processor override.
- public _handle_xhtml_token: Token pre-processor. Tokens include: ${this} returns a string representing a request to the registry for the context object, ${this.id} represents the running object id, and ${hemi.hemi_base}.
- public cleanTemplate: Invokes virtual template_destroy and embedded_destroy methods, and removes embedded script that had been loaded. This will not remove any XHTMLComponent or Space objects, or clear the XHTML contents.
- virtual component_destroy: Invoked when the ApplicationComponent destroy method is invoked, but before internal references are removed or cleaned up.
- virtual component_init: Invoked when the component has been initialized and is ready to be used.
- virtual component_post_init: Invoked after the component and any children have been initialized.
- public destroy: Prepares the ApplicationComponent to be destroyed. Removes all tokens created for this object, removes this object from participating in any transactions, removes it from the registry, and invokes the component_destroy method.
- virtual embedded_destroy: Invoked prior to a template being loaded, or the containing object being destroyed. This method is automatically removed after invocation, so each embedded-script must define it in order for it to be invoked. Where the template_destroy method is unique to the object, there can be any number of embedded_destroy declarations.
- virtual embedded_init: Invoked when a template is loaded via the loadTemplate method. This method is automatically removed after invocation, so each embedded-script must define it in order for it to be invoked. Where the template_init method is unique to the object, there can be any number of embedded_init declarations.
- public evaluateWireReference: Evaluates the wire reference.
- public getBindingEnabled: Bit indicating whether the component should bind to an XHTMLComponent. Binding is used to automatically instrument event handlers with the corresponding DOM Node represented by the XHTMLComponent.
- public getComponentName: Returns the container name.
- public getContainer: Returns the object that contains the application component.
- public getContainerComponentId: Returns the specified identifier of the component's container component.
- public getContainerId: Returns the container id, which is the object to which the component belongs.
- public getDataStack: Returns the StackStack used by this component.
- public getDefinitionId: Returns the definition id, which is the code executed to construct the component.
- public getObjectId: Returns the unique id of the object.
- public getObjectType: Returns the type of the object.
- public getObjectVersion: Returns the version of the object.
- public getPointers: Returns the object_config.pointers sub structure.
- public getReadyState: Returns the state of the object.
- public getReferenceId: Returns the specified identifier of the component container, such as the containing Space identifier.
- public getStatus: Returns the object_config.status sub structure.
- virtual getTemplateContainer: Returns the XHTML object into which a template is copied.
- virtual getTemplateObjectByName: Returns an object reference from the current template. Used when setTemplateIsSpace is set to true.
- public getTemplateSpace: Returns the engine object created for the template container. Used when setTemplateIsSpace is set to 1.
- public importComponentDefinition (internal): Imports the definition node. Invokes the handler specified in newInstance with the String "onloadappcomp" and the ApplicationComponentInstance object. Invokes the component_init method if it was defined.
- public importEmbeddedScript: Imports embedded-script elements from an XML document.
- public importNodeDefinition (internal): Imports the definition node.
- public init (internal): Initializes the Application Component with the specified definition node.
- public loadComponent: Loads the specified component definition.
- public loadTemplate: Loads the specified template into the component container, or, if specified, into the object returned by the optional getTemplateContainer function defined on the component.
- public loadTemplateFromNode: Loads the specified template node into the component container, or, if specified, into the object returned by the optional getTemplateContainer function defined on the component.
- virtual local_handle_xhtml_token: Virtual token pre-processor to be implemented as needed for substituting tokenized values (eg: ${this})
- virtual local_template_init: Invoked after template_init and all embedded_init functions. Used for specifying load handlers.
- public post_init (internal): Invokes a post initialization after the component has been initialized, and after any child content and objects have been added and initialized. Automatically invoked by Space servire through XHTMLComponent. Or, can be manually invoked as needed. Causes any virtual component_post_init function to be invoked.
- public release: Releases the ApplicationComponent object so that it can be reinitialized with another definition.
- public setAsync: Specify whether load operations should be handled asynchronously.
- public setBindingEnabled: Specify whether the component should bind to an XHTMLComponent. Binding is used to automatically instrument event handlers with the corresponding DOM Node represented by the XHTMLComponent.
- public setContainerId: Specifies the container id, which is the object to which the component belongs.
- public setTemplateIsSpace: Specifies whether to instrument a template container as an engine. Note: When a component is set as a space, the space-id attribute artifact is stripped. The space-id attribute is used as a processing boundary by the Application Space service. If the marker is not removed, the spaces will overlap and may result in errors due to expected objects not existing in the expected spaces.
- virtual setTitle (internal): Invoked by _handle_load_template, and sets a title for a component based on a loaded template.
- public sigterm: Sends a termination signal to the ApplicationComponent.
- virtual template_destroy: Invoked prior to a template being loaded, or the containing object being destroyed.
- virtual template_init: Invoked when a template is loaded via the loadTemplate method. This method is automatically removed after invocation, so each template must define it in order for it to be invoked.
Message Index
- public oncomponentload: Message published to all subscribers when a component has been loaded.
- public ontemplateload: Message published to all subscribers when a template has been loaded.
Examples
Bind HTML Node to Application Component #1
Demonstrate how an ApplicationComponent can be used to bind an HTML Node to a external code.
Example Code
<!-- XML Component File -->
<application-components>
<application-component id = "demo_ac1">
<![CDATA[
component_init:function(){
alert('loaded');
},
component_destroy:function(){
},
_handle_click:function(e){
alert('click');
}
]]>
</application-component>
</application-components>
<!-- HTML Page -->
<p id = "oTest">This is a test</p>
<script type = "text/javascript">
window.onload = init;
function init(){
var oAC = Hemi.app.comp.ApplicationComponent;
var oComponent = oAC.bindComponent(document.getElementById("oTest"),"demo_ac1","/path/to/file.xml");
}
</script>Properties
object_config
Object API structure for storing sub structures: object_config.pointers and object_config.status.
Syntax
object = object.object_config
object_id
Unique instance identifier.
Syntax
String = object.object_id
object_type
The type of this object.
Syntax
String = object.object_type
object_version
Version of the object class.
Syntax
String = object.object_version
ready_state
Object load and execution state. Follows: 0 unitialized, 1 through 3 variant, 4 ready, 5 destroyed.
Syntax
int = object.ready_state
Methods
_handle_event
Handler for a specific event, where event is one of the following: change, focus, blur, mouseover, mouseout, click. When binding a component with one of these handlers, the event instrumentation is done automatically. Method is virtual and can be overridden.
Syntax
void _handle_event(
e
)
Parameters
- e as event : Event object. This is determined cross browser, so there should be no need to query for the global event object in browsers such as Internet Explorer.
_handle_template_processor
Buffered handler for Space Processor override.
Syntax
void _handle_template_processor(
o, v
)
Parameters
- o as Space : A Space object.
- v as variant : An XHTML Node, or string.
_handle_xhtml_token
Token pre-processor. Tokens include: ${this} returns a string representing a request to the registry for the context object, ${this.id} represents the running object id, and ${hemi.hemi_base}.
Syntax
r = _handle_xhtml_token(
i, s
)
Parameters
- i as int : Integer representing the nodeType.
- s as String : String value provided by HemiEngine.xml.setInnerXHTML, when this method is provided as the callback argument.
Returns
r as String: The substituted value
cleanTemplate
Invokes virtual template_destroy and embedded_destroy methods, and removes embedded script that had been loaded. This will not remove any XHTMLComponent or Space objects, or clear the XHTML contents.
Syntax
void cleanTemplate(
)
component_destroy
Invoked when the ApplicationComponent destroy method is invoked, but before internal references are removed or cleaned up. Method is virtual and can be overridden.
Syntax
void component_destroy(
)
component_init
Invoked when the component has been initialized and is ready to be used. Method is virtual and can be overridden.
Syntax
void component_init(
)
component_post_init
Invoked after the component and any children have been initialized. Method is virtual and can be overridden.
Syntax
void component_post_init(
)
destroy
Prepares the ApplicationComponent to be destroyed. Removes all tokens created for this object, removes this object from participating in any transactions, removes it from the registry, and invokes the component_destroy method.
Syntax
void destroy(
)
embedded_destroy
Invoked prior to a template being loaded, or the containing object being destroyed. This method is automatically removed after invocation, so each embedded-script must define it in order for it to be invoked. Where the template_destroy method is unique to the object, there can be any number of embedded_destroy declarations. Method is virtual and can be overridden.
Syntax
void embedded_destroy(
)
embedded_init
Invoked when a template is loaded via the loadTemplate method. This method is automatically removed after invocation, so each embedded-script must define it in order for it to be invoked. Where the template_init method is unique to the object, there can be any number of embedded_init declarations. Method is virtual and can be overridden.
Syntax
void embedded_init(
)
evaluateWireReference
Evaluates the wire reference.
Syntax
w = evaluateWireReference(
b, n, a
)
Parameters
- b as boolean : Bit indicating whether only the wire action should be evaluated.
- n as String (optional): Wire name to supercede the hardcoded definition.
- a as array (optional): Argument array.
Returns
w as boolean: Returns true if the wire was evaluated, false otherwise.
getBindingEnabled
Bit indicating whether the component should bind to an XHTMLComponent. Binding is used to automatically instrument event handlers with the corresponding DOM Node represented by the XHTMLComponent.
Syntax
b = getBindingEnabled(
)
Returns
b as boolean: Bit indicating whether the component should bind to any specified XHTMLComponent.
getComponentName
Returns the container name.
Syntax
i = getComponentName(
)
Returns
i as String: The name of the component.
getContainer
Returns the object that contains the application component.
Syntax
o = getContainer(
)
Returns
o as object: The object that contains the application component.
getContainerComponentId
Returns the specified identifier of the component's container component.
Syntax
s = getContainerComponentId(
)
Returns
s as String: Identifier of the component's container component.
getContainerId
Returns the container id, which is the object to which the component belongs.
Syntax
i = getContainerId(
)
Returns
i as String: Identifier of the registered object to which this application component belongs.
getDataStack
Returns the StackStack used by this component.
Syntax
t = getDataStack(
)
Returns
t as StackStack: DataStack object.
getDefinitionId
Returns the definition id, which is the code executed to construct the component.
Syntax
i = getDefinitionId(
)
Returns
i as String: Application component definition id.
getObjectId
Returns the unique id of the object.
Syntax
i = getObjectId(
)
Returns
i as String: The unique object instance id.
getObjectType
Returns the type of the object.
Syntax
t = getObjectType(
)
Returns
t as String: The type of the object instance.
getObjectVersion
Returns the version of the object.
Syntax
v = getObjectVersion(
)
Returns
v as String: The version of the object instance.
getPointers
Returns the object_config.pointers sub structure.
Syntax
o = getPointers(
)
Returns
o as object: The object_config.pointers substructure.
getReadyState
Returns the state of the object.
Syntax
s = getReadyState(
)
Returns
s as int: The object ready state.
getReferenceId
Returns the specified identifier of the component container, such as the containing Space identifier.
Syntax
s = getReferenceId(
)
Returns
s as String: Identifier of the component container.
getStatus
Returns the object_config.status sub structure.
Syntax
o = getStatus(
)
Returns
o as object: The object_config.status substructure.
getTemplateContainer
Returns the XHTML object into which a template is copied. Method is virtual and can be overridden.
Syntax
o = getTemplateContainer(
)
Returns
o as object: XHTML object.
getTemplateObjectByName
Returns an object reference from the current template. Used when setTemplateIsSpace is set to true. Method is virtual and can be overridden.
Syntax
o = getTemplateObjectByName(
)
Returns
o as object: XHTML object.
getTemplateSpace
Returns the engine object created for the template container. Used when setTemplateIsSpace is set to 1.
Syntax
e = getTemplateSpace(
)
Returns
e as EngineObject: Engine object created for the template container.
importComponentDefinition
Imports the definition node. Invokes the handler specified in newInstance with the String "onloadappcomp" and the ApplicationComponentInstance object. Invokes the component_init method if it was defined.
Syntax
void importComponentDefinition(
s, i, pn
)
Parameters
- s as String : The Application Component code.
- i as String : The component identifier.
- pn as String (optional): The transaction name this component should participate in.
importEmbeddedScript
Imports embedded-script elements from an XML document.
Syntax
void importEmbeddedScript(
n, b
)
Parameters
- n as XML node : An XML node.
- b as bool : Bit indicating whether the embedded script element should be preserved in the parent node. The default action is to remove it.
importNodeDefinition
Imports the definition node.
Syntax
void importNodeDefinition(
o
)
Parameters
- o as object : Application Component definition node. This should be an XML node.
init
Initializes the Application Component with the specified definition node.
Syntax
void init(
o
)
Parameters
- o as object : Application Component definition node. This should be an XML node.
loadComponent
Loads the specified component definition.
Syntax
void loadComponent(
l, c
)
Parameters
- l as String : The identifier of the component to load.
- c as String : Path to the external XML file containing the component definitions.
loadTemplate
Loads the specified template into the component container, or, if specified, into the object returned by the optional getTemplateContainer function defined on the component.
Syntax
void loadTemplate(
s, i
)
Parameters
- s as String : Path to the XML file containing the template data.
- i as String (optional): Optional id of the template to load.
loadTemplateFromNode
Loads the specified template node into the component container, or, if specified, into the object returned by the optional getTemplateContainer function defined on the component.
Syntax
void loadTemplateFromNode(
o
)
Parameters
- o as Node : Xml node representing the template to load.
local_handle_xhtml_token
Virtual token pre-processor to be implemented as needed for substituting tokenized values (eg: ${this}) Method is virtual and can be overridden.
Syntax
r = local_handle_xhtml_token(
i, s
)
Parameters
- i as int : Integer representing the nodeType.
- s as String : String value provided by HemiEngine.xml.setInnerXHTML, when this method is provided as the callback argument.
Returns
r as String: The substituted value
local_template_init
Invoked after template_init and all embedded_init functions. Used for specifying load handlers. Method is virtual and can be overridden.
Syntax
void local_template_init(
o
)
Parameters
- o as ApplicationComponent : The application component.
post_init
Invokes a post initialization after the component has been initialized, and after any child content and objects have been added and initialized. Automatically invoked by Space servire through XHTMLComponent. Or, can be manually invoked as needed. Causes any virtual component_post_init function to be invoked.
Syntax
void post_init(
x, ri
)
Parameters
- x as XHTMLComponent : XHTMLComponent object representing an HTML Form Element.
- ri as String (optional): Reference id for field containment.
release
Releases the ApplicationComponent object so that it can be reinitialized with another definition.
Syntax
void release(
)
setAsync
Specify whether load operations should be handled asynchronously.
Syntax
void setAsync(
b
)
Parameters
- b as boolean : Bit indicating whether load operations should be asynchronous.
setBindingEnabled
Specify whether the component should bind to an XHTMLComponent. Binding is used to automatically instrument event handlers with the corresponding DOM Node represented by the XHTMLComponent.
Syntax
void setBindingEnabled(
b
)
Parameters
- b as boolean : Bit indicating whether the component should bind to any specified XHTMLComponent.
setContainerId
Specifies the container id, which is the object to which the component belongs.
Syntax
void setContainerId(
i
)
Parameters
- i as String : Identifier of the registered object to which this application component belongs.
setTemplateIsSpace
Specifies whether to instrument a template container as an engine. Note: When a component is set as a space, the space-id attribute artifact is stripped. The space-id attribute is used as a processing boundary by the Application Space service. If the marker is not removed, the spaces will overlap and may result in errors due to expected objects not existing in the expected spaces.
Syntax
void setTemplateIsSpace(
b
)
Parameters
- b as boolean : Bit indicating whether to treate the template container as an engine.
setTitle
Invoked by _handle_load_template, and sets a title for a component based on a loaded template. Method is virtual and can be overridden.
Syntax
void setTitle(
s
)
Parameters
- s as String : Text of the title.
sigterm
Sends a termination signal to the ApplicationComponent.
Syntax
void sigterm(
)
template_destroy
Invoked prior to a template being loaded, or the containing object being destroyed. Method is virtual and can be overridden.
Syntax
void template_destroy(
)
template_init
Invoked when a template is loaded via the loadTemplate method. This method is automatically removed after invocation, so each template must define it in order for it to be invoked. Method is virtual and can be overridden.
Syntax
void template_init(
)
Messages
oncomponentload
Message published to all subscribers when a component has been loaded.
Syntax
// User-specified script to subscribe to message
org.cote.js.message.MessageService.subscribe("oncomponentload",_handle_message);
// Internal: how the message is published to subscribers
org.cote.js.message.MessageService.publish("oncomponentload"
, o
);
// User-specified script to handle the message subscription
function _handle_message("oncomponentload"
, o
){
// message handler code
}
Parameters
- o as ApplicationComponent : The application component that was just loaded.
ontemplateload
Message published to all subscribers when a template has been loaded.
Syntax
// User-specified script to subscribe to message
org.cote.js.message.MessageService.subscribe("ontemplateload",_handle_message);
// Internal: how the message is published to subscribers
org.cote.js.message.MessageService.publish("ontemplateload"
, o
);
// User-specified script to handle the message subscription
function _handle_message("ontemplateload"
, o
){
// message handler code
}
Parameters
- o as ApplicationComponent : The application component for which the template was recently loaded and initialized.
[ Hemi JavaScript Framework - Stephen W. Cote, 2002 - 2009. ]