org.apache.click.control
Class AbstractContainer

java.lang.Object
  extended by org.apache.click.control.AbstractControl
      extended by org.apache.click.control.AbstractContainer
All Implemented Interfaces:
Serializable, Control, Container
Direct Known Subclasses:
Form, Panel

public abstract class AbstractContainer
extends AbstractControl
implements Container

Provides a default implementation of the Container interface to make it easier for developers to create their own containers.

Subclasses can override AbstractControl.getTag() to return a specific HTML element.

The following example shows how to create an HTML div element:

 public class Div extends AbstractContainer {

     public String getTag() {
         // Return the HTML tag
         return "div";
     }
 } 

See Also:
Serialized Form

Field Summary
protected  Map<String,Control> controlMap
          The map of controls keyed by field name.
protected  List<Control> controls
          The list of controls.
 
Fields inherited from class org.apache.click.control.AbstractControl
actionListener, attributes, behaviors, headElements, listener, listenerMethod, messages, name, parent, styles
 
Fields inherited from interface org.apache.click.Control
CONTROL_MESSAGES
 
Constructor Summary
AbstractContainer()
          Create a container with no name defined.
AbstractContainer(String name)
          Create a container with the given name.
 
Method Summary
 Control add(Control control)
          Add the control to the container and return the added instance.
 boolean contains(Control control)
          Return true if the container contains the specified control.
 Control getControl(String controlName)
          Return the named control from the container if found or null otherwise.
 Map<String,Control> getControlMap()
          Return the map of controls where each map's key / value pair will consist of the control name and instance.
 List<Control> getControls()
          Return the sequential list of controls held by the container.
 int getControlSizeEst()
          Return the estimated rendered control size in characters.
 boolean hasControls()
          Returns true if this container has existing controls, false otherwise.
 Control insert(Control control, int index)
          Add the control to the container at the specified index, and return the added instance.
 void onDestroy()
          This method does nothing.
 void onInit()
          This method does nothing.
 boolean onProcess()
          The on process event handler.
 void onRender()
          This method does nothing.
 boolean remove(Control control)
          Remove the given control from the container, returning true if the control was found in the container and removed, or false if the control was not found.
 void render(HtmlStringBuffer buffer)
          Render the HTML representation of the container and all its child controls to the specified buffer.
protected  void renderChildren(HtmlStringBuffer buffer)
          Render this container children to the specified buffer.
protected  void renderContent(HtmlStringBuffer buffer)
          Render this container content to the specified buffer.
protected  void renderTagEnd(String tagName, HtmlStringBuffer buffer)
          Closes the specified tag.
 Control replace(Control currentControl, Control newControl)
          Deprecated. this method was used for stateful pages, which have been deprecated
 String toString()
          Returns the HTML representation of this control.
 
Methods inherited from class org.apache.click.control.AbstractControl
addBehavior, addStyleClass, appendAttributes, dispatchActionEvent, getActionListener, getAttribute, getAttributes, getBehaviors, getContext, getHeadElements, getHtmlImports, getId, getMessage, getMessage, getMessages, getName, getPage, getParent, getStyle, getStyles, getTag, hasAttribute, hasAttributes, hasBehaviors, hasStyles, isAjaxTarget, onDeploy, removeBehavior, removeStyleClass, renderTagBegin, setActionListener, setAttribute, setId, setListener, setName, setParent, setStyle
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface org.apache.click.Control
getBehaviors, getContext, getHeadElements, getId, getMessages, getName, getParent, hasBehaviors, isAjaxTarget, onDeploy, setListener, setName, setParent
 

Field Detail

controls

protected List<Control> controls
The list of controls.


controlMap

protected Map<String,Control> controlMap
The map of controls keyed by field name.

Constructor Detail

AbstractContainer

public AbstractContainer()
Create a container with no name defined.


AbstractContainer

public AbstractContainer(String name)
Create a container with the given name.

Parameters:
name - the container name
Method Detail

add

public Control add(Control control)
Description copied from interface: Container
Add the control to the container and return the added instance.

Specified by:
add in interface Container
Parameters:
control - the control to add to the container
Returns:
the control that was added to the container
Throws:
IllegalArgumentException - if the control is null
See Also:

Please note: if the container contains a control with the same name as the given control, that control will be {@link #replace(org.apache.click.Control, org.apache.click.Control) replaced} by the given control. If a control has no name defined it cannot be replaced.


insert

public Control insert(Control control,
                      int index)
Add the control to the container at the specified index, and return the added instance.

Please note: if the container contains a control with the same name as the given control, that control will be replaced by the given control. If a control has no name defined it cannot be replaced.

Also note if the specified control already has a parent assigned, it will automatically be removed from that parent and inserted into this container.

Specified by:
insert in interface Container
Parameters:
control - the control to add to the container
index - the index at which the control is to be inserted
Returns:
the control that was added to the container
Throws:
IllegalArgumentException - if the control is null or if the control and container is the same instance
IndexOutOfBoundsException - if index is out of range (index < 0 || index > getControls().size())
See Also:
Container.insert(org.apache.click.Control, int)

remove

public boolean remove(Control control)
Description copied from interface: Container
Remove the given control from the container, returning true if the control was found in the container and removed, or false if the control was not found.

Specified by:
remove in interface Container
Parameters:
control - the control to remove from the container
Returns:
true if the control was removed from the container
Throws:
IllegalArgumentException - if the control is null
See Also:
Container.remove(org.apache.click.Control).

replace

public Control replace(Control currentControl,
                       Control newControl)
Deprecated. this method was used for stateful pages, which have been deprecated

Replace the control in the container at the specified index, and return the newly added control.

Specified by:
replace in interface Container
Parameters:
currentControl - the control currently contained in the container
newControl - the control to replace the current control contained in the container
Returns:
the new control that replaced the current control
Throws:
IllegalArgumentException - if the currentControl or newControl is null
IllegalStateException - if the currentControl is not contained in the container
See Also:
Container.replace(org.apache.click.Control, org.apache.click.Control)

getControls

public List<Control> getControls()
Description copied from interface: Container
Return the sequential list of controls held by the container.

Specified by:
getControls in interface Container
Returns:
the sequential list of controls held by the container
See Also:
Container.getControls().

getControl

public Control getControl(String controlName)
Description copied from interface: Container
Return the named control from the container if found or null otherwise.

Specified by:
getControl in interface Container
Parameters:
controlName - the name of the control to get from the container
Returns:
the named control from the container if found or null otherwise
See Also:
Container.getControl(java.lang.String)

contains

public boolean contains(Control control)
Description copied from interface: Container
Return true if the container contains the specified control.

Specified by:
contains in interface Container
Parameters:
control - the control whose presence in this container is to be tested
Returns:
true if the container contains the specified control
See Also:
Container.contains(org.apache.click.Control)

hasControls

public boolean hasControls()
Returns true if this container has existing controls, false otherwise.

Specified by:
hasControls in interface Container
Returns:
true if the container has existing controls, false otherwise.

getControlMap

public Map<String,Control> getControlMap()
Return the map of controls where each map's key / value pair will consist of the control name and instance.

Controls added to the container that did not specify a AbstractControl.name, will not be included in the returned map.

Returns:
the map of controls

getControlSizeEst

public int getControlSizeEst()
Description copied from class: AbstractControl
Return the estimated rendered control size in characters.

Overrides:
getControlSizeEst in class AbstractControl
Returns:
the estimated rendered control size in characters
See Also:
AbstractControl.getControlSizeEst().

onProcess

public boolean onProcess()
Description copied from interface: Control
The on process event handler. Each control will be processed when the Page is requested.

ClickServlet will process all Page controls in the order they were added to the Page.

Container implementations should recursively invoke the onProcess method on each of their child controls ensuring that all controls receive this event. However when a control onProcess method return false, no other controls onProcess method should be invoked.

When a control is processed it should return true if the Page should continue event processing, or false if no other controls should be processed and the Page.onGet() or Page.onPost() methods should not be invoked.

Please note: a common problem when overriding onProcess in subclasses is forgetting to call super.onProcess(). Consider carefully whether you should call super.onProcess() or not, especially for Containers which by default call onProcess on all their child controls as well.

Specified by:
onProcess in interface Control
Overrides:
onProcess in class AbstractControl
Returns:
true to continue Page event processing or false otherwise
See Also:
Control.onProcess().

onDestroy

public void onDestroy()
Description copied from class: AbstractControl
This method does nothing. Subclasses may override this method to perform clean up any resources.

Specified by:
onDestroy in interface Control
Overrides:
onDestroy in class AbstractControl
See Also:
Control.onDestroy()

onInit

public void onInit()
Description copied from class: AbstractControl
This method does nothing. Subclasses may override this method to perform initialization.

Specified by:
onInit in interface Control
Overrides:
onInit in class AbstractControl
See Also:
Control.onInit()

onRender

public void onRender()
Description copied from class: AbstractControl
This method does nothing. Subclasses may override this method to perform pre rendering logic.

Specified by:
onRender in interface Control
Overrides:
onRender in class AbstractControl
See Also:
Control.onRender()

render

public void render(HtmlStringBuffer buffer)
Render the HTML representation of the container and all its child controls to the specified buffer.

If AbstractControl.getTag() returns null, this method will render only its child controls.

Specified by:
render in interface Control
Overrides:
render in class AbstractControl
Parameters:
buffer - the specified buffer to render the control's output to
See Also:
AbstractControl.render(org.apache.click.util.HtmlStringBuffer)

toString

public String toString()
Returns the HTML representation of this control.

This method delegates the rendering to the method render(org.apache.click.util.HtmlStringBuffer). The size of buffer is determined by getControlSizeEst().

Overrides:
toString in class AbstractControl
Returns:
the HTML representation of this control
See Also:
Object.toString()

renderTagEnd

protected void renderTagEnd(String tagName,
                            HtmlStringBuffer buffer)
Description copied from class: AbstractControl
Closes the specified tag.

Overrides:
renderTagEnd in class AbstractControl
Parameters:
tagName - the name of the tag to close
buffer - the buffer to append the output to
See Also:
AbstractControl.renderTagEnd(java.lang.String, org.apache.click.util.HtmlStringBuffer).

renderContent

protected void renderContent(HtmlStringBuffer buffer)
Render this container content to the specified buffer.

Parameters:
buffer - the buffer to append the output to

renderChildren

protected void renderChildren(HtmlStringBuffer buffer)
Render this container children to the specified buffer.

Parameters:
buffer - the buffer to append the output to
See Also:
getControls()