net.sf.click.control
Class Panel

java.lang.Object
  net.sf.click.control.AbstractControl
      net.sf.click.control.AbstractContainer
          net.sf.click.control.Panel

All Implemented Interfaces:

Container, Control, Serializable

public class Panel

extends AbstractContainer

Provides a Panel control for creating customized layout sections within a page.

Panel

My panel content.

The Panel class uses a template for rendering any model data or controls you have added to the Page.

Panel is a very powerful component and provides the same capability as a Page, since it has its own associated template and model.

This allows you to create very modular components. For example, if you add a tab control to your Page, each tab could refer to a separate Panel. Each Panel template could then render its own Form or Table controls.

Panel Example

An simple example creating a Panel with the panel-template.htm is provided below:

 <fieldset>
   <legend class="title"> $messages.heading </legend>
   $messages.content
 </fieldset> 

Then in our page class we would include the Panel. With the $messages.heading and $messages.content values defined in the Pages properties file.

 public class WelcomePage extends Page {

     public Panel panel = new Panel("panel", "/panel-template.htm");
 } 

In our WelcomePage template welcome.htm would simply reference our panel control:

 $panel 

The Panel template would then be merged with the template model and rendered in the page as:

Welcome

Welcome to MyCorp.

MyCorp is your telecommuting office portal. Its just like being there at the office!

Panel rendering is performed using the AbstractContainer.toString() method, and the template model is created using createTemplateModel().

Template Model

To render the panel's template, a model is created which is merged with the template. This model will include the pages model values, plus any Panel defined model values, with the Panels values overriding any Page defined values. In addition a number of values are automatically added model. These values include:

• attributes - the panel HTML attributes map
• context - the Servlet context path, e.g. /mycorp
• format - the page Format object for formatting the display of objects
• this - a reference to this panel object
• messages - the panel messages bundle
• request - the servlet request
• response - the servlet request
• session - the SessionMap adaptor for the users HttpSession

Author:

Phil Barnes, Malcolm Edgar

See Also:

Serialized Form

Field Summary

protected boolean	disabled The panel disabled value.
protected String	id The "identifier" for this panel (CSS id for rendering).
protected String	label The (localized) label of this panel.
protected Map	model A temporary storage for model objects until the Page is set.
protected List	panels The list of sub panels.
protected String	template The path of the template to render.

Fields inherited from class net.sf.click.control.AbstractContainer

controlMap, controls

Fields inherited from class net.sf.click.control.AbstractControl

actionListener, attributes, listener, listenerMethod, messages, name, parent, styles

Fields inherited from interface net.sf.click.Control

CONTROL_MESSAGES

Constructor Summary

Panel()
Create a Panel with no name or template defined.

Panel(String name)
Create a Panel with the given name.

Panel(String name, String template)
Create a Panel with the given name and template path.

Panel(String name, String id, String template)
Create a Panel with the given name, id attribute and template path.

Method Summary

Control	add(Control control) Add the control to the panel and return the specified control.
Control	addControl(Control control)
void	addModel(String name, Object value) Add the named object value to the Panels model map.
protected Map	createTemplateModel() Create a model to merge with the template.
String	getId() Return the panel id value.
String	getLabel() Return the panel display label.
Map	getModel() Return the panels model map.
List	getPanels() Return the list of sub panels associated with this panel.
String	getTemplate() Return the path of the template to render.
boolean	isDisabled() Return true if the panel is disabled.
boolean	remove(Control control) Remove the control from the panel and returning true if the control was found in the container and removed, or false if the control was not found.
boolean	removeControl(Control control)
void	render(HtmlStringBuffer buffer) Render the HTML string representation of the Panel.
void	setActionListener(ActionListener listener) This method does nothing, since Panel does not support action listener callback.
void	setDisabled(boolean disabled) Set whether the panel is disabled.
void	setId(String id) Set the id for this panel.
void	setLabel(String label) Set the Panel display caption.
void	setListener(Object listener, String method) This method does nothing, since Panel does not support listener callback.
void	setTemplate(String template) Set the path of the template to render.

Methods inherited from class net.sf.click.control.AbstractContainer

contains, getControl, getControlMap, getControls, getControlSizeEst, getHtmlImports, hasControls, insert, onDestroy, onInit, onProcess, onRender, renderChildren, renderContent, renderTagEnd, toString

Methods inherited from class net.sf.click.control.AbstractControl

addStyleClass, appendAttributes, getActionListener, getAttribute, getAttributes, getContext, getMessage, getMessage, getMessage, getMessages, getName, getPage, getParent, getStyle, getStyles, getTag, hasAttribute, hasAttributes, hasStyles, onDeploy, registerActionEvent, removeStyleClass, renderTagBegin, setAttribute, setName, setParent, setStyle

Methods inherited from class java.lang.Object

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

Methods inherited from interface net.sf.click.Control

getContext, getMessages, getName, getParent, onDeploy, setName, setParent

Field Detail

disabled

protected boolean disabled

The panel disabled value.

id

protected String id

The "identifier" for this panel (CSS id for rendering).

label

protected String label

The (localized) label of this panel.

model

protected Map model

A temporary storage for model objects until the Page is set.

panels

protected List panels

The list of sub panels.

template

protected String template

The path of the template to render.

Constructor Detail

Panel

public Panel(String name)

Create a Panel with the given name.

Parameters:

name - the name of the panel

Panel

public Panel(String name,
             String template)

Create a Panel with the given name and template path.

Parameters:

name - the name of the panel

template - the template path

Panel

public Panel(String name,
             String id,
             String template)

Create a Panel with the given name, id attribute and template path.

Parameters:

name - the name of the panel

template - the template path

id - the id HTML attribute value

Panel

public Panel()

Create a Panel with no name or template defined.

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

Method Detail

addControl

public Control addControl(Control control)

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, if the name of the control is not defined or the container already contains a control with the same name

See Also:

add(net.sf.click.Control)

add

public Control add(Control control)

Add the control to the panel and return the specified control.

In addition to the requirements specified by Container.add(net.sf.click.Control), note the following:

• The control's name must be set when adding to a panel.
• The control will be added to the Panel model using the controls name as the key and can be accessed through getModel(). This allows one to reference the control in the Panels template.
• If the specified control is an instanceof a Panel, it will also be added to a list of panels and can be accessed through getPanels().

Specified by:

add in interface Container

Overrides:

add in class AbstractContainer

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 or the container already contains a control with the same name

See Also:

Container.add(net.sf.click.Control)

removeControl

public boolean removeControl(Control control)

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 or if the name of the control is not defined

See Also:

remove(net.sf.click.Control)

remove

public boolean remove(Control control)

Remove the control from the panel and returning true if the control was found in the container and removed, or false if the control was not found.

In addition to the requirements specified by Container.remove(net.sf.click.Control), the controls name must also be set.

Specified by:

remove in interface Container

Overrides:

remove in class AbstractContainer

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(net.sf.click.Control)

isDisabled

public boolean isDisabled()

Return true if the panel is disabled.

Returns:

true if the panel is disabled

setDisabled

public void setDisabled(boolean disabled)

Set whether the panel is disabled.

Parameters:

disabled - the disabled flag

getId

public String getId()

Return the panel id value. If no id attribute is defined then this method will return the panel name. If no name is defined this method will return null.

Specified by:

getId in interface Control

Overrides:

getId in class AbstractControl

Returns:

the panel HTML id attribute value

See Also:

Control.getId()

setId

public void setId(String id)

Set the id for this panel. This is the identifier that will be assigned to the 'id' tag for this panel's model.

Overrides:

setId in class AbstractControl

Parameters:

id - the id attribute for this panel

getLabel

public String getLabel()

Return the panel display label.

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 Panel name will be converted into a label using the method: ClickUtils.toLabel(String)

Typically the label property is used as a header for a particular panel. For example:

  <div id="$panel.id">
      <h1>$panel.label</h1>
      ## content here
  </div> 

Returns:

the internationalized label associated with this control

setLabel

public void setLabel(String label)

Set the Panel display caption.

Parameters:

label - the display label of the Panel

setListener

public void setListener(Object listener,
                        String method)

This method does nothing, since Panel does not support listener callback.

Specified by:

setListener in interface Control

Overrides:

setListener in class AbstractControl

Parameters:

listener - the listener object with the named method to invoke

method - the name of the method to invoke

See Also:

Control.setListener(Object, String)

setActionListener

public void setActionListener(ActionListener listener)

This method does nothing, since Panel does not support action listener callback.

Overrides:

setActionListener in class AbstractControl

Parameters:

listener - the control's action listener

See Also:

AbstractControl.setActionListener(net.sf.click.ActionListener)

addModel

public void addModel(String name,
                     Object value)

Add the named object value to the Panels model map.

Parameters:

name - the key name of the object to add

value - the object to add

Throws:

IllegalArgumentException - if the name or value parameters are null, or if there is already a named value in the model

getModel

public Map getModel()

Return the panels model map. The model is used populate the Template Context with is merged with the panel template before rendering.

Returns:

the Page's model map

getPanels

public List getPanels()

Return the list of sub panels associated with this panel. Do not add sub panels using this method, use add(Control) instead.

Returns:

the list of sub-panels, if any

getTemplate

public String getTemplate()

Return the path of the template to render.

Returns:

the path of the template to render

setTemplate

public void setTemplate(String template)

Set the path of the template to render.

Parameters:

template - the path of the template to render

render

public void render(HtmlStringBuffer buffer)

Render the HTML string representation of the Panel. The panel will be rendered by merging the template with the template model. The template model is created using createTemplateModel().

If a Panel template is not defined, a template based on the classes name will be loaded. For more details please see Context.renderTemplate(Class, Map).

Specified by:

render in interface Control

Overrides:

render in class AbstractContainer

Parameters:

buffer - the specified buffer to render the control's output to

See Also:

AbstractContainer.toString()

createTemplateModel

protected Map createTemplateModel()

Create a model to merge with the template. The model will include the pages model values, plus any Panel defined model values, and a number of automatically added model values. Note panel model values will override any page defined model values.

The following values automatically added to the Model:

• attributes - the panel HTML attributes map
• context - the Servlet context path, e.g. /mycorp
• format - the page Format object for formatting the display of objects
• this - a reference to this panel
• messages - the panel messages bundle
• request - the servlet request
• response - the servlet request
• session - the SessionMap adaptor for the users HttpSession

Returns:

a new model to merge with the template.