Java Doc for Component.java in  » Ajax » zk » org » zkoss » zk » ui » Java Source Code / Java DocumentationJava Source Code and Java Documentation

There are two kind of lifecycles: one is page creations and the other is asynchronous updates.

The Page Creation

The page creation occurs when a page is about to render at the first time. The detailed phases can be found in the devloper's guide.

The Asynchronous Update

The asynchronous update occurs when users does something on the browser, such as changing the content of input, clicking buttons and so on. Such behaviors are packed as requests, queue in the browser, and then send to the server at the proper time. The detailed phases can be found in the developer's guide.

No Synchronization Required

To simplify the development of components and applications, invocations of methods of components and event listener are all serialized. In other words, application and component developers need not worry synchronization and other thread issues (unless you are developing background thread to handle long operations).

It also implies a limitation that you cannot access components belonging to other desktops when processing an event.
author:
   tomyeh

Default: no forward condition at all.

Once the condition is added, a event called targetEvent is posted to the target compoennt, when this component receives the orginalEvent event.
Parameters:
  originalEvent - the original event that was receivedby this component.

Note: the target component is retrieved from the path, each time the event is received.

When a component is created in an event listener, it is assigned to the current desktop automatically. If a component is created not in any event listener, it doesn't belong to any desktop and this method returns null. Once a component is attached to a desktop (thru Component.setPage or Component.setParent ), it belongs to the desktop.

Notice: there is no way to detach a component from a desktop, once it is attached as described above. In other words, you cannot move a component (or page) from one desktop to another.

In summary, there are only two ways to handle components.

1. Handle them all in event listeners and don't access any components from other desktops.

Exactly one namespace is allocated for each ID space. For example, if the space owner of this component is the page, then the returned namespace is the same as Page.getNamespace . Otherwise, it is the same as the namspace returned by the component owning this ID space.

Namspace is another part of an ID space.

When a component is created (aka., constructed), it doesn't belong to any page.

Each ID space defines an independent set of IDs.

You could use Component.setParent or Component.appendChild instead of this method, unless you want to control where to put the child.

Note: Component.setParent always calls back Component.insertBefore and/or Component.removeChild , while Component.insertBefore and Component.removeChild always calls back Component.setParent , if the parent is changed.

If AuResponse.getDepends is not null, the response depends on the existence of the returned componet. In other words, the response is removed if the component is removed. If it is null, the response is component-independent and it is always sent to the client.

Unlike Component.smartUpdate , responses are sent to client if it is component independent or it is not removed. In other words, it is sent even if Component.invalidate() was called. Typical examples include setting the focus, selecting the text and so on.

It can be called only in the request-processing and event-processing phases; excluding the redrawing phase.
Parameters:
  key - could be anything.The second invocation of this methodin the same execution with the same key will override the previous one.However, if key is null, it won't override any other.

Note: The attribute is removed (by Component.removeAttribute if value is null, while Component.setVariable considers null as a legal value.

If scope is Component.COMPONENT_SCOPE , it means custom attributes private to this component.

If scope is Component.SPACE_SCOPE , it means custom attributes shared by components from the same ID space as this one's.

If scope is Component.PAGE_SCOPE , it means custom attributes shared by components from the same page as this one's.

If scope is Component.DESKTOP_SCOPE , it means custom attributes shared by components from the same desktopas this one's.
Parameters:
  scope - Component.COMPONENT_SCOPE, Component.SPACE_SCOPE,Component.PAGE_SCOPE, Component.DESKTOP_SCOPE, Component.SESSION_SCOPE,Component.REQUEST_SCOPE or Component.APPLICATION_SCOPE,
Parameters:
  value - the value.

For child components, the page they belong is maintained automatically.

For child components, the page they belong is maintained automatically.

Note: Component.setParent always calls back Component.insertBefore and/or Component.removeChild , while Component.insertBefore and Component.removeChild always calls back Component.setParent , if the parent is changed.

This method is the same as getNamespace().setVariable(name, value, local).

Once a variable is set thru this method, it is visible to both the interpreter and EL.

Note: Exactly one namespace is allocated for each ID space. For example, if the space owner of this component is the page, then the returned namespace is the same as Page.getNamespace . Otherwise, it is the same as the namspace returned by the component owning this ID space.

When to use setVariable and setAttribute?

First, only the ID space support Component.setVariable and so. Second, the variables can be referenced directly in zscript and EL expressions, while attributes are referenced thru the scope, such as spaceScope. On the other hand, using attributes causes less name popultion. In general, if you could use attributes, don't use variable.
Parameters:
  local - whether not to search any of the ancestor namespace definesthe variable.

The second invocation with the same property will replace the previous call.

It is also known as the application attributes.

It is the same as WebApp.getAttributes .

It is also known as the component attributes.

It is the same as Component.getAttributes .

It is also known as the desktop attributes.

It is the same as Desktop.getAttributes .

It is also known as the page attributes.

It is the same as Page.getAttributes .

It is also known as the request attributes.

It is the same as Execution.getAttributes .

It is also known as the session attributes.

It is the same as Session.getAttributes .

It is also known as the ID space attributes.

You could register listener to all components in the same page by use of Page.addEventListener .
Parameters:
  evtnm - what event to listen (never null) whether the listener is added; false if it was added before
See Also:   Page.addEventListener

Default: no forward condition at all.

Once the condition is added, a event called targetEvent is posted to the target compoennt, when this component receives the orginalEvent event.
Parameters:
  originalEvent - the original event that was receivedby this component. If null, "onClick" is assumed.
Parameters:
  target - the target component to receive the event.If null, the space owner Component.getSpaceOwner is assumed.If null and the space owner is the page, the root component is assumed.
Parameters:
  targetEvent - the target event that the target componentwill receive.If null, it is the same as the original event. whether it is added successfully.It returns false if the conditioin was always added before.
since:
   3.0.0
See Also:   Component.removeForward(String,Component,String)

Note: the target component is retrieved from the path, each time the event is received. Thus, you can reference to a component that is created later.
Parameters:
  originalEvent - the original event that was receivedby this component. If null, "onClick" is assumed.
Parameters:
  targetPath - the target component's path related to this component.If ".", this component is assumed.If null, the space owner is assumed.If null and the space owner is the page, the root component is assumed.
Parameters:
  targetEvent - the target event that the target componentwill receive.If null, it is the same as the original event. whether it is added successfully.It returns false if the conditioin was always added before.
See Also:   Component.addForward(String,Component,String)
See Also:   Component.removeForward(String,String,String)
since:
   3.0.0

This method is invoked automatically if a component is created by evaluating a ZUML page, i.e., if it is specified as an elemnt of a ZUML page.

On the other hand, if it is created manually (by program), developer might choose to invoke this method or not, depending whether he wants to initializes the component with the properties and custom-attributes defined in the ZUML page ( org.zkoss.zk.ui.metainfo.PageDefinition ) and the language definition ( org.zkoss.zk.ui.metainfo.LanguageDefinition ).

Note: null is a valid value for variable, so this method is used to know whether a variable is defined. On the other hand, Component.setAttribute actually remove an attribute (by Component.removeAttribute if value is null.
Parameters:
  local - whether not to search its ancestor.If false and the current namespace doen't define the variable,it searches up its ancestor (via Component.getParent) to seeany of them has defined the specified variable.

If scope is Component.COMPONENT_SCOPE , it means attributes private to this component.

If scope is Component.SPACE_SCOPE , it means custom attributes shared by components from the same ID space as this one's.

If scope is Component.PAGE_SCOPE , it means custom attributes shared by components from the same page as this one's.

If scope is Component.DESKTOP_SCOPE , it means custom attributes shared by components from the same desktopas this one's.
Parameters:
  scope - Component.COMPONENT_SCOPE, Component.SPACE_SCOPE,Component.PAGE_SCOPE, Component.DESKTOP_SCOPE, Component.SESSION_SCOPE,Component.REQUEST_SCOPE or Component.APPLICATION_SCOPE,

If scope is Component.COMPONENT_SCOPE , it means custom attributes private to this component.

If scope is Component.SPACE_SCOPE , it means custom attributes shared by components from the same ID space as this one's.

If scope is Component.PAGE_SCOPE , it means custom attributes shared by components from the same page as this one's.

If scope is Component.DESKTOP_SCOPE , it means custom attributes shared by components from the same desktopas this one's.
Parameters:
  scope - Component.COMPONENT_SCOPE, Component.SPACE_SCOPE,Component.PAGE_SCOPE, Component.DESKTOP_SCOPE, Component.SESSION_SCOPE,Component.REQUEST_SCOPE or Component.APPLICATION_SCOPE,

When a component is created in an event listener, it is assigned to the current desktop automatically. If a component is created not in any event listener, it doesn't belong to any desktop and this method returns null. Once a component is attached to a desktop (thru Component.setPage or Component.setParent ), it belongs to the desktop.

Notice: there is no way to detach a component from a desktop, once it is attached as described above. In other words, you cannot move a component (or page) from one desktop to another.

In summary, there are only two ways to handle components.

1. Handle them all in event listeners and don't access any components from other desktops. This is simplest and clearest.
2. Creates components in another thread (other than event listener) and attach them to a page (and then desktop) upon an event is received.

Unlike Component.getFellowIfAny , it throws an exception if not found.
exception:
  ComponentNotFoundException - is thrown if fellow not found

Unlike Component.getFellow , it returns null if not found.

If a component belongs to an ID space (see IdSpace ), the ID must also be unique in the ID space it belongs. any its parent and ancestor implements IdSpace .

A page itself is also an ID space, so you could retrieve compnents in a page by use of Page.getFellow , unless the component is a descendant of another component that implements IdSpace . In this case, you have to retrieve the parent first (by use of Page.getFellow and then use Component.getFellow against the owner of the ID space.

In zscript and EL, a component with explicit ID can be accessed directly by the ID. In other word, a variable named by the ID is created automatically.
See Also:   Page

Default: "default"
See Also:   org.zkoss.zk.ui.metainfo.ComponentDefinition

Exactly one namespace is allocated for each ID space. For example, if the space owner of this component is the page, then the returned namespace is the same as Page.getNamespace . Otherwise, it is the same as the namspace returned by the component owning this ID space.

Namspace is another part of an ID space. It holds only variables defined thru Component.setVariable (and Namespace.setVariable .

Note: The namespace doesn't include any variable defined by executing zscripts. To retrieve them, use Page.getZScriptVariable .
See Also:   Component.getSpaceOwner

When a component is created (aka., constructed), it doesn't belong to any page. And, if a component doesn't belong to any page, they won't be displayed at the client.

When changing parent ( Component.setParent ), the child component's page will become the same as parent's. In other words, a component is added to a page automatically if it becomes a child of another component (who belongs to a page).

For root components, you have to invoke Component.setPage explicityly.
See Also:   Component.setParent
See Also:   Component.setPage

Each ID space defines an independent set of IDs. No component in the same ID space could have the same ID. To get any component in the same ID space, you could use Component.getFellow . See IdSpace for more details.

The ID space relevant methods include Component.getFellow , Component.getAttribute and Component.getVariable .
See Also:   Component.getNamespace

It is mainly used for communication between client and server and you rarely need to access it.

If org.zkoss.zk.ui.ext.RawId is implemented as part of a component, UUID is the same as Component.getId if Component.setId is ever called. It is designed to migrate HTML pages to ZK, such that the element ID could remain the same.

This method is the same as getNamespace().getVariable(name, local).

Differences between Component.getVariable and Page.getZScriptVariable

Component.getVariable returns only variables defined by Component.setVariable (i.e., a shortcut of Namespace.setVariable ). On the other hand, Page.getZScriptVariable returns these variables and those defined when executing zscripts.
Parameters:
  local - whether not to search its ancestor.If false and the current namespace doen't define the variable,it searches up its ancestor (via Component.getParent) to seeany of them has defined the specified variable.
See Also:   Component.getSpaceOwner
See Also:   Component.getNamespace

You could use Component.setParent or Component.appendChild instead of this method, unless you want to control where to put the child.

Note: Component.setParent always calls back Component.insertBefore and/or Component.removeChild , while Component.insertBefore and Component.removeChild always calls back Component.setParent , if the parent is changed. Thus, you don't need to override both Component.insertBefore and Component.setParent , if you want to customize the behavior.
Parameters:
  newChild - the new child to be inserted.
Parameters:
  refChild - the child before which you want the new childbeing inserted. If null, the new child is append to the end. true if newChild is added successfully or moved;false if it already has the specified child and the order doesn'tchange.

It can be called only in the request-processing and event-processing phases; excluding the redrawing phase.

There are two ways to draw a component, one is to invoke Component.invalidate() , and the other is Component.smartUpdate . While Component.invalidate() causes the whole content to redraw, Component.smartUpdate let component developer control which part to redraw.

Once this method is called, all invocations to Component.smartUpdate will then be ignored, and Component.redraw will be invoked later.

Unlike org.zkoss.zk.ui.event.Events.isListened , this method checks only the event listener registered by Component.addEventListener .
Parameters:
  asap - whether to check only non-deferrable listener,i.e., not implementing org.zkoss.zk.ui.event.Deferrable,or org.zkoss.zk.ui.event.Deferrable.isDeferrable is false.
See Also:   org.zkoss.zk.ui.event.Deferrable
See Also:   org.zkoss.zk.ui.event.Events.isListened
See Also:   Component.addEventListener

Note: Component.onChildAdded is called in the request-processing phase, while Component.onDrawNewChild is called in the redrawing phase. See Component.onDrawNewChild for more details.

It is not a good idea to throw an exception in this method, since it is in the middle of modifying the component tree.

It is not a good idea to throw an exception in this method, since it is in the middle of modifying the component tree.

It is called in the redrawing phase by the kernel, so it is too late to call Component.invalidate() or Component.smartUpdate in this method.

Note: Component.onChildAdded is called in the request-processing phase, while Component.onDrawNewChild is called in the redrawing phase. Component developer might do one of the follows:

• Nothing, if new child can be inserted directly.
• Overwrite Component.onDrawNewChild to add special tags, if new child needs to be added an exterior with some tags before insertion.
  Morever, if you shall add id="${child.uuid}!chdextr" to the added exterior.
• Redraw the parent, if it is too complicated. How: overwrite Component.onChildAdded and calls Component.invalidate()

If a component is moved from one page to another, Component.onPageAttached is called with both pages. Note: Component.onPageDetached is not called in this case.

Note: this method is called even if the component is attached to a page implicitly thru, say, Component.setParent .

It is not a good idea to throw an exception in this method, since it is in the middle of modifying the component tree.
Parameters:
  newpage - the new page (never null).
Parameters:
  oldpage - the previous page, if any, or null if it didn'tbelong to any page.
since:
   3.0.0

If a component is moved from one page to another, Component.onPageAttached is called with both pages. Note: Component.onPageDetached is not called in this case. In other words, Component.onPageDetached is called only if a component is detached from a page (not belong to any other page).

Note: this method is called even if the component is detached to a page implicitly thru, say, Component.setParent .

It is not a good idea to throw an exception in this method, since it is in the middle of modifying the component tree.
Parameters:
  page - the previous page (never null)
since:
   3.0.0

It is called in the redrawing phase by the kernel, so it is too late to call Component.invalidate() or Component.smartUpdate in this method.

If scope is Component.COMPONENT_SCOPE , it means attributes private to this component.

If scope is Component.SPACE_SCOPE , it means custom attributes shared by components from the same ID space as this one's.

If scope is Component.PAGE_SCOPE , it means custom attributes shared by components from the same page as this one's.

If scope is Component.DESKTOP_SCOPE , it means custom attributes shared by components from the same desktopas this one's.
Parameters:
  scope - Component.COMPONENT_SCOPE, Component.SPACE_SCOPE,Component.PAGE_SCOPE, Component.DESKTOP_SCOPE, Component.SESSION_SCOPE,Component.REQUEST_SCOPE or Component.APPLICATION_SCOPE,

You could use Component.setParent with null instead of this method.

Note: Component.setParent always calls back Component.insertBefore and/or Component.removeChild , while Component.insertBefore and Component.removeChild always calls back Component.setParent , if the parent is changed. Thus, you don't need to override both Component.insertBefore and Component.setParent , if you want to customize the behavior. true if child is removed successfully; false if it doesn'thave the specified child

If AuResponse.getDepends is not null, the response depends on the existence of the returned componet. In other words, the response is removed if the component is removed. If it is null, the response is component-independent and it is always sent to the client.

Unlike Component.smartUpdate , responses are sent to client if it is component independent or it is not removed. In other words, it is sent even if Component.invalidate() was called. Typical examples include setting the focus, selecting the text and so on.

It can be called only in the request-processing and event-processing phases; excluding the redrawing phase.
Parameters:
  key - could be anything.The second invocation of this methodin the same execution with the same key will override the previous one.However, if key is null, it won't override any other. All responseswith key == null will be sent.

Note: The attribute is removed (by Component.removeAttribute if value is null, while Component.setVariable considers null as a legal value.

If scope is Component.COMPONENT_SCOPE , it means custom attributes private to this component.

If scope is Component.SPACE_SCOPE , it means custom attributes shared by components from the same ID space as this one's.

If scope is Component.PAGE_SCOPE , it means custom attributes shared by components from the same page as this one's.

If scope is Component.DESKTOP_SCOPE , it means custom attributes shared by components from the same desktopas this one's.
Parameters:
  scope - Component.COMPONENT_SCOPE, Component.SPACE_SCOPE,Component.PAGE_SCOPE, Component.DESKTOP_SCOPE, Component.SESSION_SCOPE,Component.REQUEST_SCOPE or Component.APPLICATION_SCOPE,
Parameters:
  value - the value. If null, the attribute is removed.

When a component is constructed, an ID is generated automatically. Thus, calling this method only you need to identify a component.
See Also:   Page

For child components, the page they belong is maintained automatically. You need to invoke this method only for root components.

For child components, the page they belong is maintained automatically. You need to invoke this method only for root components.

It is similar to Component.setPage , except this component will be placed before the reference component. If the reference component is null, this component is placed at the end of all root components.
Parameters:
  refRoot - another root component used as a referencewhich this component will be placed before.If null, this component will be placed at the end of allroot components (no matter whether it already belongs to the same page).
since:
   3.0.0

Note: Component.setParent always calls back Component.insertBefore and/or Component.removeChild , while Component.insertBefore and Component.removeChild always calls back Component.setParent , if the parent is changed. Thus, you don't need to override both Component.insertBefore and Component.setParent , if you want to customize the behavior.

This method is the same as getNamespace().setVariable(name, value, local).

Once a variable is set thru this method, it is visible to both the interpreter and EL.

Note: Exactly one namespace is allocated for each ID space. For example, if the space owner of this component is the page, then the returned namespace is the same as Page.getNamespace . Otherwise, it is the same as the namspace returned by the component owning this ID space.

When to use setVariable and setAttribute?

First, only the ID space support Component.setVariable and so. Second, the variables can be referenced directly in zscript and EL expressions, while attributes are referenced thru the scope, such as spaceScope. On the other hand, using attributes causes less name popultion. In general, if you could use attributes, don't use variable.
Parameters:
  local - whether not to search any of the ancestor namespace definesthe variable. If local is false and an ancesotor has defined a variablewith the same name, the variable in the ancestor is changed directly.Otherwise, a new variable is created in the namespace containingthis component.
See Also:   Component.getSpaceOwner
See Also:   Component.getNamespace

The second invocation with the same property will replace the previous call. In other words, the same property will be set only once in each execution.

This method has no effect if Component.invalidate() is ever invoked (during this execution).

It can be called only in the request-processing and event-processing phases; excluding the redrawing phase.

There are two ways to draw a component, one is to invoke Component.invalidate() , and the other is Component.smartUpdate . While Component.invalidate() causes the whole content to redraw, Component.smartUpdate let component developer control which part to redraw.
Parameters:
  value - the new value. If null, it means removing the property.

For some old application servers (example, Webshpere 5.1), Execution.encodeURL cannot be called in the event processing thread. So, the developers have to use DeferredValue or disable the use of the event processing thread (by use of disable-event-thread in zk.xml).
since:
   3.0.1

This method is the same as getNamespace().getVariable(name, local).
Parameters:
  local - whether not to search its ancestor.If false and the current namespace doen't define the variable,it searches up its ancestor (via Component.getParent) to seeany of them has defined the specified variable.
See Also:   Component.getSpaceOwner
See Also:   Component.getNamespace