net.sf.click.control
Class AbstractControl

java.lang.Object
  extended bynet.sf.click.control.AbstractControl
All Implemented Interfaces:
Control, Serializable
Direct Known Subclasses:
AbstractContainer, AbstractLink, Field, Table

public abstract class AbstractControl
extends Object
implements Control

Provides a default implementation of the Control interface, to make it easier for developers to implement their own controls.

Subclasses are expected to at least override getTag() to differentiate the control. However some controls does not map cleanly to a html tag, in which case you can override render(net.sf.click.util.HtmlStringBuffer) for complete control over the output.

Below is an example of creating a new control called MyField:

 public class MyField extends AbstractControl {

     private String value;

     public void setValue(String value) {
         this.value = value;
     }

     public String getValue() {
         return value;
     }

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

     public boolean onProcess() {
         // Bind the request parameter to the field value
         String requestValue = getContext().getRequestParamter(getName());
         setValue(requestValue);

         // Invoke any listener of MyField
         return registerActionEvent();
     }
 }
 
By overriding getTag() one can specify the html tag to render.

Overriding onProcess() allows one to bind the servlet request parameter to MyField value. The registerActionEvent() method registers the listener for this control on the Context. Once the onProcess event has finished, all registered listeners will be fired.

To view the html rendered by MyField invoke the control's toString() method:

 public class Test {
     public static void main (String args[]) {
         // Create mock context in which to test the control.
         MockContext.initContext();

         String fieldName = "myfield";
         MyField myfield = new MyField(fieldName);
         String output = myfield.toString();
         System.out.println(output);
     }
 } 
Executing the above test results in the following output:
 <input name="myfield" id="myfield"/>
Also see Control javadoc for an explanation of the Control execution sequence.

Author:
Bob Schellink, Malcolm Edgar
See Also:
Serialized Form

Field Summary
protected  ActionListener actionListener
          The control's action listener.
protected  Map attributes
          The Control attributes Map.
protected  Object listener
          The listener target object.
protected  String listenerMethod
          The listener method name.
protected  Map messages
          The Control localized messages Map.
protected  String name
          The Control name.
protected  Object parent
          The control's parent.
protected  Map styles
          Deprecated. use addStyleClass(String) and removeStyleClass(String) instead.
 
Fields inherited from interface net.sf.click.Control
CONTROL_MESSAGES
 
Constructor Summary
AbstractControl()
          Create a control with no name defined.
AbstractControl(String name)
          Create a control with the given name.
 
Method Summary
 void addStyleClass(String value)
          Add the CSS class attribute.
protected  void appendAttributes(HtmlStringBuffer buffer)
          Append all the controls attributes to the specified buffer.
 ActionListener getActionListener()
          Return the control's action listener.
 String getAttribute(String name)
          Return the control HTML attribute with the given name, or null if the attribute does not exist.
 Map getAttributes()
          Return the control's attributes Map.
 Context getContext()
          Return the Page request Context of the Control.
protected  int getControlSizeEst()
          Return the estimated rendered control size in characters.
 String getHtmlImports()
          Return the HTML import string to be include in the page.
 String getId()
          Return the "id" attribute value if defined, or the control name otherwise.
 String getMessage(String name)
          Return the localized message for the given key, or null if not found.
 String getMessage(String name, Object arg)
          Return the formatted message for the given resource name, message format argument and the context request locale, or null if no message was found.
 String getMessage(String name, Object[] args)
          Return the formatted message for the given resource name, message format arguments and the context request locale, or null if no message was found.
 Map getMessages()
          Return a Map of localized messages for the control.
 String getName()
          Return the name of the Control.
 Page getPage()
          Return the parent page of this control, or null if not defined.
 Object getParent()
          Return the parent of the Control.
 String getStyle(String name)
          Return the control CSS style for the given name.
 Map getStyles()
          Deprecated. use getAttribute(String) instead
 String getTag()
          Returns the controls html tag.
 boolean hasAttribute(String name)
          Returns true if specified attribute is defined, false otherwise.
 boolean hasAttributes()
          Return true if the control has attributes or false otherwise.
 boolean hasStyles()
          Deprecated. use hasAttribute(String) instead
 void onDeploy(ServletContext servletContext)
          This method does nothing.
 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.
protected  void registerActionEvent()
          Register this control's listener with the ControlRegistry registry.
 void removeStyleClass(String value)
          Removes the CSS class attribute.
 void render(HtmlStringBuffer buffer)
          Render the control's output to the specified buffer.
protected  void renderTagBegin(String tagName, HtmlStringBuffer buffer)
          Render the tag and common attributes.
protected  void renderTagEnd(String tagName, HtmlStringBuffer buffer)
          Closes the specifies tag.
 void setActionListener(ActionListener listener)
          Set the control's action listener.
 void setAttribute(String name, String value)
          Set the control attribute with the given attribute name and value.
 void setId(String id)
          Set the HTML id attribute for the control with the given value.
 void setListener(Object listener, String method)
          Set the controls event listener.
 void setName(String name)
          Set the name of the Control.
 void setParent(Object parent)
          Set the parent of the Control.
 void setStyle(String name, String value)
          Set the control CSS style name and value pair.
 String toString()
          Returns the HTML representation of this control.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

actionListener

protected ActionListener actionListener
The control's action listener.


attributes

protected Map attributes
The Control attributes Map.


messages

protected transient Map messages
The Control localized messages Map.


name

protected String name
The Control name.


parent

protected Object parent
The control's parent.


styles

protected Map styles
Deprecated. use addStyleClass(String) and removeStyleClass(String) instead.

The Map of CSS style attributes.


listener

protected Object listener
The listener target object.


listenerMethod

protected String listenerMethod
The listener method name.

Constructor Detail

AbstractControl

public AbstractControl()
Create a control with no name defined.


AbstractControl

public AbstractControl(String name)
Create a control with the given name.

Parameters:
name - the control name
Method Detail

getTag

public String getTag()
Returns the controls html tag.

Subclasses should override this method and return the correct tag.

This method returns null by default.

Example tags include table, form, a and input.

Returns:
this controls html tag

getActionListener

public ActionListener getActionListener()
Return the control's action listener. If the control has a listener target and listener method defined, this method will return an ActionListenerAdaptor instance.

Returns:
the control's action listener

setActionListener

public void setActionListener(ActionListener listener)
Set the control's action listener.

Parameters:
listener - the control's action listener

getAttribute

public String getAttribute(String name)
Return the control HTML attribute with the given name, or null if the attribute does not exist.

Parameters:
name - the name of link HTML attribute
Returns:
the link HTML attribute

setAttribute

public void setAttribute(String name,
                         String value)
Set the control attribute with the given attribute name and value. You would generally use attributes if you were creating the entire Control programmatically and rendering it with the toString() method.

For example given the ActionLink:

 ActionLink addLink = new ActionLink("addLink", "Add");
 addLink.setAttribute("target", "_blank"); 
Will render the HTML as:
 <a href=".." target="_blank">Add</a> 
Note: for style and class attributes you can also use the methods setStyle(String, String) and addStyleClass(String).

Parameters:
name - the attribute name
value - the attribute value
Throws:
IllegalArgumentException - if name parameter is null
See Also:
setStyle(String, String), addStyleClass(String), removeStyleClass(String)

getAttributes

public Map getAttributes()
Return the control's attributes Map.

Returns:
the control's attributes Map.

hasAttributes

public boolean hasAttributes()
Return true if the control has attributes or false otherwise.

Returns:
true if the control has attributes on false otherwise

hasAttribute

public boolean hasAttribute(String name)
Returns true if specified attribute is defined, false otherwise.

Parameters:
name - the specified attribute to check
Returns:
true if name is a defined attribute

getContext

public Context getContext()
Description copied from interface: Control
Return the Page request Context of the Control.

Specified by:
getContext in interface Control
Returns:
the Page request Context
See Also:
Control.getContext()

getName

public String getName()
Description copied from interface: Control
Return the name of the Control. Each control name must be unique in the containing Page model or the containing Form.

Specified by:
getName in interface Control
Returns:
the name of the control
See Also:
Control.getName()

setName

public void setName(String name)
Description copied from interface: Control
Set the name of the Control. Each control name must be unique in the containing Page model or the parent container.

Please note: changing the name of a Control after it has been added to its parent container is undefined. Thus it is best not to change the name of a Control once its been set.

Specified by:
setName in interface Control
Parameters:
name - of the control
Throws:
IllegalArgumentException - if the name is null
See Also:
Control.setName(String)

getId

public String getId()
Return the "id" attribute value if defined, or the control name otherwise.

Specified by:
getId in interface Control
Returns:
HTML element identifier attribute "id" value
See Also:
Control.getId()

setId

public void setId(String id)
Set the HTML id attribute for the control with the given value.

Parameters:
id - the element HTML id attribute value to set

getMessage

public String getMessage(String name)
Return the localized message for the given key, or null if not found.

This method will attempt to lookup the localized message in the parent's messages, which resolves to the Page's resource bundle.

If the message was not found, this method will attempt to look up the value in the /click-control.properties message properties file, through the method getMessages().

If still not found, this method will return null.

Parameters:
name - the name of the message resource
Returns:
the named localized message, or null if not found

getMessage

public String getMessage(String name,
                         Object arg)
Return the formatted message for the given resource name, message format argument and the context request locale, or null if no message was found.

getMessage(java.lang.String, java.lang.Object[]) is invoked to retrieve the message for the specified name.

Parameters:
name - resource name of the message
arg - the message argument to format
Returns:
the named localized message for the control

getMessage

public String getMessage(String name,
                         Object[] args)
Return the formatted message for the given resource name, message format arguments and the context request locale, or null if no message was found.

getMessage(java.lang.String) is invoked to retrieve the message for the specified name.

Parameters:
name - resource name of the message
args - the message arguments to format
Returns:
the named localized message for the package or null if no message was found

getMessages

public Map getMessages()
Return a Map of localized messages for the control.

Specified by:
getMessages in interface Control
Returns:
a Map of localized messages for the control
Throws:
IllegalStateException - if the context for the control has not be set

getParent

public Object getParent()
Description copied from interface: Control
Return the parent of the Control.

Specified by:
getParent in interface Control
Returns:
the Control's parent
See Also:
Control.getParent()

setParent

public void setParent(Object parent)
Description copied from interface: Control
Set the parent of the Control.

Specified by:
setParent in interface Control
Parameters:
parent - the parent of the Control
Throws:
IllegalArgumentException - if the given parent instance is referencing this object: if (parent == this)
See Also:
Control.setParent(Object)

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
Returns:
true to continue Page event processing or false otherwise
See Also:
Control.onProcess()

setListener

public void setListener(Object listener,
                        String method)
Set the controls event listener.

The method signature of the listener is:

An example event listener method would be:

 public boolean onClick() {
     System.out.println("onClick called");
     return true;
 } 

Specified by:
setListener in interface Control
Parameters:
listener - the listener object with the named method to invoke
method - the name of the method to invoke

onInit

public void onInit()
This method does nothing. Subclasses may override this method to perform initialization.

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

onDestroy

public void onDestroy()
This method does nothing. Subclasses may override this method to perform clean up any resources.

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

onDeploy

public void onDeploy(ServletContext servletContext)
This method does nothing. Subclasses may override this method to deploy static web resources.

Specified by:
onDeploy in interface Control
Parameters:
servletContext - the servlet context
See Also:
Control.onDeploy(ServletContext)

onRender

public void onRender()
This method does nothing. Subclasses may override this method to perform pre rendering logic.

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

getHtmlImports

public String getHtmlImports()
Description copied from interface: Control
Return the HTML import string to be include in the page.

Override this method to specify JavaScript and CSS includes for the page. For example:

 protected static final String HTML_IMPORT =
     "<script type=\"text/javascript\" src=\"{0}/click/custom.js\"></script>";

 public String getHtmlImports() {
     return ClickUtils.createHtmlImport(HTML_IMPORTS, getResourceVersionIndicator(), getContext());
 } 
Note multiple import lines should be separated by a '\n' char, as the PageImports will parse multiple import lines on the '\n' char and ensure that imports are not included twice.

The order in which JS and CSS files are include will be preserved in the page.

Also note: a common problem when overriding getHtmlImports in subclasses is forgetting to call super.getHtmlImports. Consider carefully whether you should call super.getHtmlImports or not.

Specified by:
getHtmlImports in interface Control
Returns:
the HTML includes statements for the control stylesheet and JavaScript files
See Also:
Control.getHtmlImports()

getPage

public Page getPage()
Return the parent page of this control, or null if not defined.

Returns:
the parent page of this control, or null if not defined

getStyle

public String getStyle(String name)
Return the control CSS style for the given name.

Parameters:
name - the CSS style name
Returns:
the CSS style for the given name

setStyle

public void setStyle(String name,
                     String value)
Set the control CSS style name and value pair.

For example given the ActionLink:

 ActionLink addLink = new ActionLink("addLink", "Add");
 addLink.setStyle("color", "red");
 addLink.setStyle("border", "1px solid black"); 
Will render the HTML as:
 <a href=".." style="color:red;border:1px solid black;">Add</a>
 
To remove an existing style, set the value to null.

Parameters:
name - the CSS style name
value - the CSS style value

hasStyles

public boolean hasStyles()
Deprecated. use hasAttribute(String) instead

Return true if CSS styles are defined.

Returns:
true if CSS styles are defined

getStyles

public Map getStyles()
Deprecated. use getAttribute(String) instead

Return the Map of control CSS styles.

Returns:
the Map of control CSS styles

addStyleClass

public void addStyleClass(String value)
Add the CSS class attribute. Null values will be ignored.

For example given the ActionLink:

 ActionLink addLink = new ActionLink("addLink", "Add");
 addLink.addStyleClass("red"); 
Will render the HTML as:
 <a href=".." class="red">Add</a> 

Parameters:
value - the class attribute to add

removeStyleClass

public void removeStyleClass(String value)
Removes the CSS class attribute.

Parameters:
value - the CSS class attribute

render

public void render(HtmlStringBuffer buffer)
Render the control's output to the specified buffer.

If getTag() returns null, this method will return an empty string.

Specified by:
render in interface Control
Parameters:
buffer - the specified buffer to render the control's output to
See Also:
Control.render(net.sf.click.util.HtmlStringBuffer)

toString

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

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

Returns:
the HTML representation of this control
See Also:
Object.toString()

registerActionEvent

protected void registerActionEvent()
Register this control's listener with the ControlRegistry registry.

See Also:
ControlRegistry.registerActionEvent(net.sf.click.Control, net.sf.click.ActionListener)

appendAttributes

protected void appendAttributes(HtmlStringBuffer buffer)
Append all the controls attributes to the specified buffer.

Parameters:
buffer - the specified buffer to append all the attributes

renderTagBegin

protected void renderTagBegin(String tagName,
                              HtmlStringBuffer buffer)
Render the tag and common attributes.

Please note: the tag will not be closed by this method. This enables callers of this method to append extra attributes as needed.

For example the result of calling:

 Field field = new TextField("mytext");
 HtmlStringBuffer buffer = new HtmlStringBuffer();
 field.renderTagBegin("div", buffer);
 
will be:
 <div name="mytext" id="mytext"
 
Note that the tag is not closed, so subclasses can easily add more attributes.

Parameters:
tagName - the name of the tag to render
buffer - the buffer to append the output to

renderTagEnd

protected void renderTagEnd(String tagName,
                            HtmlStringBuffer buffer)
Closes the specifies tag.

Parameters:
tagName - the name of the tag to close
buffer - the buffer to append the output to

getControlSizeEst

protected int getControlSizeEst()
Return the estimated rendered control size in characters.

Returns:
the estimated rendered control size in characters