net.sf.click.control
Class Panel

java.lang.Object
  extended bynet.sf.click.control.AbstractControl
      extended bynet.sf.click.control.AbstractContainer
          extended bynet.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:

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:

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:

Returns:
a new model to merge with the template.