net.sf.click.control
Class AbstractControl

java.lang.Object
  net.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:

• must hava a valid Java method name
• takes no arguments
• returns a boolean value

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