org.apache.click.control
Class AbstractLink

java.lang.Object
  org.apache.click.control.AbstractControl
      org.apache.click.control.AbstractLink

All Implemented Interfaces:

Serializable, Control, Stateful

Direct Known Subclasses:

ActionLink, PageLink

public abstract class AbstractLink
extends AbstractControl
implements Stateful

Provides a Abstract Link control: <a href=""></a>.

See also the W3C HTML reference: A Links

See Also:

ActionLink, Submit, Serialized Form

Field Summary

protected boolean	disabled The Field disabled value.
protected String	imageSrc The image src path attribute.
protected String	label The link display label.
protected Map<String,Object>	parameters The link parameters map.
protected boolean	renderLabelAndImage Flag to set if both icon and text are rendered, default value is false.
protected int	tabindex The link 'tabindex' attribute.
protected String	title The link title attribute, which acts as a tooltip help message.

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

AbstractLink()
Create an AbstractLink with no name defined.

AbstractLink(String name)
Create an AbstractLink for the given name.

Method Summary

protected void	bindRequestParameters(Context context) This method binds the submitted request parameters to the link parameters.
void	bindRequestValue() This method does nothing by default since AbstractLink does not bind to request values.
void	defineParameter(String name) Defines a link parameter that will have its value bound to a matching request parameter.
abstract String	getHref() Return the AbstractLink anchor <a> tag href attribute.
String	getId() Return the "id" attribute value if defined, or null otherwise.
String	getImageSrc() Return the image src path attribute.
String	getLabel() Return the label for the AbstractLink.
String	getParameter(String name) Return the link request parameter value for the given name, or null if the parameter value does not exist.
Map<String,Object>	getParameters() Return the AbstractLink parameters Map.
String[]	getParameterValues(String name) Return the link request parameter values for the given name, or null if the parameter values does not exist.
Object	getState() Return the link state.
int	getTabIndex() Return the link "tabindex" attribute value.
String	getTag() Return the link html tag: a.
String	getTitle() Return the 'title' attribute, or null if not defined.
boolean	hasParameters() Return true if the AbstractLink has parameters, false otherwise.
boolean	isAjaxTarget(Context context) Returns true if this control is an AJAX target, false otherwise.
boolean	isDisabled() Return true if the AbstractLink is a disabled.
boolean	isRenderLabelAndImage() Returns true if both icon and label are rendered, false otherwise.
void	removeState(Context context) Remove the link state from the session for the given request context.
void	render(HtmlStringBuffer buffer) Render the HTML representation of the anchor link.
protected void	renderImgTag(HtmlStringBuffer buffer) Render the Image tag to the buffer.
protected void	renderParameters(HtmlStringBuffer buffer, Map<String,Object> parameters, Context context) Render the given link parameters to the buffer.
void	restoreState(Context context) Restore the link state from the session for the given request context.
void	saveState(Context context) Save the link state to the session for the given request context.
void	setDisabled(boolean disabled) Set the disabled flag.
void	setImageSrc(String src) Set the image src path attribute.
void	setLabel(String label) Set the label for the ActionLink.
void	setParameter(String name, Object value) Set the link parameter with the given parameter name and value.
void	setParameters(Map parameters) Set the AbstractLink parameter map.
void	setParameterValues(String name, Object[] values) Set the link parameter with the given parameter name and values.
void	setRenderLabelAndImage(boolean renderLabelAndImage) Sets whether both label and icon are rendered for this link.
void	setState(Object state) Set the link state.
void	setTabIndex(int tabindex) Set the link "tabindex" attribute value.
void	setTitle(String value) Set the 'title' attribute tooltip message.

Methods inherited from class org.apache.click.control.AbstractControl

addBehavior, addStyleClass, appendAttributes, dispatchActionEvent, getActionListener, getAttribute, getAttributes, getBehaviors, getContext, getControlSizeEst, getHeadElements, getHtmlImports, getMessage, getMessage, getMessages, getName, getPage, getParent, getStyle, getStyles, hasAttribute, hasAttributes, hasBehaviors, hasStyles, onDeploy, onDestroy, onInit, onProcess, onRender, removeBehavior, removeStyleClass, renderTagBegin, renderTagEnd, setActionListener, setAttribute, setId, setListener, setName, setParent, setStyle, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

disabled

protected boolean disabled

The Field disabled value.

imageSrc

protected String imageSrc

The image src path attribute. If the image src is defined then a <img/> element will rendered inside the anchor link when using the AbstractLink AbstractControl.toString() method.

If the image src value is prefixed with '/' then the request context path will be prefixed to the src value when rendered by the control.

label

protected String label

The link display label.

parameters

protected Map<String,Object> parameters

The link parameters map.

tabindex

protected int tabindex

The link 'tabindex' attribute.

title

protected String title

The link title attribute, which acts as a tooltip help message.

renderLabelAndImage

protected boolean renderLabelAndImage

Flag to set if both icon and text are rendered, default value is false.

Constructor Detail

AbstractLink

public AbstractLink(String name)

Create an AbstractLink for the given name.

Parameters:

name - the page link name

Throws:

IllegalArgumentException - if the name is null

AbstractLink

public AbstractLink()

Create an AbstractLink with no name defined.

Please note the control's name must be defined before it is valid.

Method Detail

getTag

public String getTag()

Return the link html tag: a.

Overrides:

getTag in class AbstractControl

Returns:

this controls html tag

See Also:

AbstractControl.getTag()

isDisabled

public boolean isDisabled()

Return true if the AbstractLink is a disabled. If the link is disabled it will be rendered as <span> element with a HTML class attribute of "disabled".

Returns:

true if the AbstractLink is a disabled

setDisabled

public void setDisabled(boolean disabled)

Set the disabled flag. If the link is disabled it will be rendered as <span> element with a HTML class attribute of "disabled".

Parameters:

disabled - the disabled flag

getHref

public abstract String getHref()

Return the AbstractLink anchor <a> tag href attribute. This method will encode the URL with the session ID if required using HttpServletResponse.encodeURL().

Returns:

the AbstractLink HTML href attribute

getImageSrc

public String getImageSrc()

Return the image src path attribute. If the image src is defined then a <img/> element will be rendered inside the anchor link when using the AbstractLink AbstractControl.toString() method.

Note: the label will not be rendered in this case (default behavior), unless the setRenderLabelAndImage(boolean) flag is set to true.

If the src value is prefixed with '/' then the request context path will be prefixed to the src value when rendered by the control.

Returns:

the image src path attribute

setImageSrc

public void setImageSrc(String src)

Set the image src path attribute. If the src value is prefixed with '/' then the request context path will be prefixed to the src value when rendered by the control.

If the image src is defined then an <img/> element will be rendered inside the anchor link when using the AbstractLink AbstractControl.toString() method.

Note: the label will not be rendered in this case (default behavior), unless the setRenderLabelAndImage(boolean) flag is set to true.

Parameters:

src - the image src path attribute

getId

public String getId()

Return the "id" attribute value if defined, or null otherwise.

Specified by:

getId in interface Control

Overrides:

getId in class AbstractControl

Returns:

HTML element identifier attribute "id" value

See Also:

Control.getId()

getLabel

public String getLabel()

Return the label for the AbstractLink.

If the label value is null, this method will attempt to find a localized label message in the parent messages using the key:

getName() + ".label"

If not found then the message will be looked up in the /click-control.properties file using the same key. If a value still cannot be found then the ActionLink name will be converted into a label using the method: ClickUtils.toLabel(String)

For example given a OrderPage with the properties file OrderPage.properties:

 checkout.label=Checkout
 checkout.title=Proceed to Checkout 

The page ActionLink code:

 public class OrderPage extends Page {
     ActionLink checkoutLink = new ActionLink("checkout");
     ..
 } 

Will render the AbstractLink label and title properties as:

 <a href=".." title="Proceed to Checkout">Checkout</a> 

When a label value is not set, or defined in any properties files, then its value will be created from the Fields name.

For example given the ActionLink code:

 ActionLink nameField = new ActionLink("deleteItem");  

Will render the ActionLink label as:

 <a href="..">Delete Item</a> 

Note the ActionLink label can include raw HTML to render other elements.

For example the configured label:

 edit.label=<img src="images/edit.png" title="Edit Item"/> 

Will render the ActionLink label as:

 <a href=".."><img src="images/edit.png" title="Edit Item"/></a> 

Returns:

the label for the ActionLink

setLabel

public void setLabel(String label)

Set the label for the ActionLink.

Parameters:

label - the label for the ActionLink

See Also:

getLabel()

getParameter

public String getParameter(String name)

Return the link request parameter value for the given name, or null if the parameter value does not exist.

Parameters:

name - the name of request parameter

Returns:

the link request parameter value

setParameter

public void setParameter(String name,
                         Object value)

Set the link parameter with the given parameter name and value. You would generally use parameter if you were creating the entire AbstractLink programmatically and rendering it with the AbstractControl.toString() method.

For example given the ActionLink:

 PageLink editLink = new PageLink("editLink", EditCustomer.class);
 editLink.setLabel("Edit Customer");
 editLink.setParameter("customerId", customerId); 

And the page template:

 $editLink 

Will render the HTML as:

 <a href="/mycorp/edit-customer.htm?customerId=13490">Edit Customer</a> 

Parameters:

name - the attribute name

value - the attribute value

Throws:

IllegalArgumentException - if name parameter is null

getParameterValues

public String[] getParameterValues(String name)

Return the link request parameter values for the given name, or null if the parameter values does not exist.

Parameters:

name - the name of request parameter

Returns:

the link request parameter values

setParameterValues

public void setParameterValues(String name,
                               Object[] values)

Set the link parameter with the given parameter name and values. If the values are null, the parameter will be removed from the parameters.

Parameters:

name - the attribute name

values - the attribute values

Throws:

IllegalArgumentException - if name parameter is null

See Also:

setParameter(java.lang.String, java.lang.Object)

getParameters

public Map<String,Object> getParameters()

Return the AbstractLink parameters Map.

Returns:

the AbstractLink parameters Map

setParameters

public void setParameters(Map parameters)

Set the AbstractLink parameter map.

Parameters:

parameters - the link parameter map

defineParameter

public void defineParameter(String name)

Defines a link parameter that will have its value bound to a matching request parameter. setParameter implicitly defines a parameter as well.

Please note: parameters need only be defined for Ajax requests. For non-Ajax requests, all incoming request parameters are bound, whether they are defined or not. This behavior may change in a future release.

Also note: link parameters are bound to request parameters during the AbstractControl.onProcess() event, so link parameters must be defined in the Page constructor or onInit() event.

Parameters:

name - the name of the parameter to define

hasParameters

public boolean hasParameters()

Return true if the AbstractLink has parameters, false otherwise.

Returns:

true if the AbstractLink has parameters, false otherwise

getTabIndex

public int getTabIndex()

Return the link "tabindex" attribute value.

Returns:

the link "tabindex" attribute value

setTabIndex

public void setTabIndex(int tabindex)

Set the link "tabindex" attribute value.

Parameters:

tabindex - the link "tabindex" attribute value

getTitle

public String getTitle()

Return the 'title' attribute, or null if not defined. The title attribute acts like tooltip message over the link.

If the title value is null, this method will attempt to find a localized label message in the parent messages using the key:

getName() + ".title"

If not found then the message will be looked up in the /click-control.properties file using the same key.

For examle given a ItemsPage with the properties file ItemPage.properties:

 edit.label=Edit
 edit.title=Edit Item 

The page ActionLink code:

 public class ItemsPage extends Page {
     ActionLink editLink = new ActionLink("edit");
     ..
 } 

Will render the ActionLink label and title properties as:

 <a href=".." title="Edit Item">Edit</a> 

Returns:

the 'title' attribute tooltip message

setTitle

public void setTitle(String value)

Set the 'title' attribute tooltip message.

Parameters:

value - the 'title' attribute tooltip message

See Also:

getTitle()

isRenderLabelAndImage

public boolean isRenderLabelAndImage()

Returns true if both icon and label are rendered, false otherwise.

Returns:

true if both icon and text are rendered, false otherwise

setRenderLabelAndImage

public void setRenderLabelAndImage(boolean renderLabelAndImage)

Sets whether both label and icon are rendered for this link.

Parameters:

renderLabelAndImage - sets the rendering type of the link.

isAjaxTarget

public boolean isAjaxTarget(Context context)

Description copied from class: AbstractControl

Returns true if this control is an AJAX target, false otherwise.

The control is defined as an Ajax target if the control ID is send as a request parameter.

Specified by:

isAjaxTarget in interface Control

Overrides:

isAjaxTarget in class AbstractControl

Parameters:

context - the request context

Returns:

true if this control is an AJAX target, false otherwise

bindRequestValue

public void bindRequestValue()

This method does nothing by default since AbstractLink does not bind to request values.

getState

public Object getState()

Return the link state. The following state is returned:

• link parameters

Specified by:

getState in interface Stateful

Returns:

the link state

setState

public void setState(Object state)

Set the link state.

Specified by:

setState in interface Stateful

Parameters:

state - the link state to set

render

public void render(HtmlStringBuffer buffer)

Render the HTML representation of the anchor link. This method will render the entire anchor link including the tags, the label and any attributes, see AbstractControl.setAttribute(String, String) for an example.

If the image src is defined then a <img/> element will rendered inside the anchor link instead of the label property.

This method invokes the abstract getHref() method.

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.toString()

removeState

public void removeState(Context context)

Remove the link state from the session for the given request context.

Parameters:

context - the request context

See Also:

saveState(org.apache.click.Context), restoreState(org.apache.click.Context)

restoreState

public void restoreState(Context context)

Restore the link state from the session for the given request context.

This method delegates to setState(java.lang.Object) to set the link restored state.

Parameters:

context - the request context

See Also:

saveState(org.apache.click.Context), removeState(org.apache.click.Context)

saveState

public void saveState(Context context)

Save the link state to the session for the given request context.

* This method delegates to getState() to retrieve the link state to save.

Parameters:

context - the request context

See Also:

restoreState(org.apache.click.Context), removeState(org.apache.click.Context)

renderImgTag

protected void renderImgTag(HtmlStringBuffer buffer)

Render the Image tag to the buffer.

Parameters:

buffer - the buffer to render the image tag to

renderParameters

protected void renderParameters(HtmlStringBuffer buffer,
                                Map<String,Object> parameters,
                                Context context)

Render the given link parameters to the buffer.

The parameters will be rendered as URL key/value pairs e.g: "firstname=john&lastname=smith".

Multivalued parameters will be rendered with each value sharing the same key e.g: "name=john&name=susan&name=mary".

The parameter value will be encoded through ClickUtils.encodeUrl(java.lang.Object, org.apache.click.Context).

Parameters:

buffer - the buffer to render the parameters to

parameters - the parameters to render

context - the request context

bindRequestParameters

protected void bindRequestParameters(Context context)

This method binds the submitted request parameters to the link parameters.

For non-Ajax requests this method will bind all incoming request parameters to the link. For Ajax requests this method will only bind the parameters already defined on the link.

Parameters:

context - the request context