org.apache.click.control
Class Panel

java.lang.Object
  org.apache.click.control.AbstractControl
      org.apache.click.control.AbstractContainer
          org.apache.click.control.Panel

All Implemented Interfaces:

Serializable, Control, Container

public class Panel
extends AbstractContainer

Provides a Panel container that has its own template and model.

Panels are powerful components for creating modular, reusable and customized layout sections within a page.

Panel

My panel content.

The Panel class uses a template for rendering model data and controls that have been added to the Panel. Furthermore the Panel's parent Page model is also made available to the Panel template.

Example 1 - A Simple Panel

This example shows how to create a basic Panel and adding it to a Page.

First we create the /panel/simple-panel.htm that references the variable $time:

The time is now $time

Then in our page class, SimplePageDemo, we create and add the Panel instance:

 public class SimplePageDemo extends Page {

     private Panel panel = new Panel("panel", "/panel/simple-panel.htm");

     public SimplePanelDemo() {
          Date time = new Date();

         // Add the $time variable to the panel model
         panel.getModel().put("time", time);

         addControl(panel);
     }
 } 

The SimplePanelDemo template, /simple-panel-demo.htm, would reference the panel control:

$panel

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

Time time is now Sun Mar 15 07:32:51 EST 2009 

Example 2 - Localization support

In this example, we demonstrate localization support by specifying the Panel content in the SimplePanelDemo.properties file. Since the Panel model and Page model are merged at runtime, the Panel template can access the Page messages.

First we create the SimplePanelDemo.properties file which specifies two properties: heading and content.

 heading=Welcome
 content=Welcome to MyCorp<p/>MyCorp is your telecommuting office portal. Its just like being there at the office!

Then we create the /panel/simple-panel.htm that references the localized Page properties. Since a Page properties are made available through the $messages map, the Panel can access the Page properties using the variables $messages.header and $messages.content:

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

In our page class, SimplePageDemo, we create and add the Panel instance:

 public class SimplePanelDemo extends Page {

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

In the Page above we make use of Click's autobinding feature by declaring a public Panel field. Autobinding will automatically add the Panel to the Page model.

The SimplePanelDemo template, /simple-panel-demo.htm, would reference the panel control:

 $panel 

And the result is:

Welcome

Welcome to MyCorp.

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

Example 3 - Reusing and Nesting Panels

Panels provide a good way to create reusable components, and since Panel is a Container it can hold child controls, even other Panels.

In this example we create a reusable CustomerPanel which is added to a Border Panel.

First we create the /panel/customer-panel.htm template which references the $form variable:

 $form 

Next up is the CustomerPanel:

 public class CustomerPanel extends Panel {

     private Form form = new Form("form");

     public CustomerPanel(String name) {
         super(name);

         // We explicitly set the customer panel template
         setTemplate("/panel/customer-panel.htm");

         form.add(new TextField("name");
         form.add(new DateField("dateJoined");
         form.add(new DoubleField("holdings");
     }
 } 

The Border Panel template, /panel/border-panel.htm, will draw a Border around its contents:

 <div> style="border: 1px solid black">
 $panel
 </div> 

Lastly we specify the NestedDemo Page, that creates a Border Panel, and adds CustomerPanel as a child.

 public class NestedDemo extends Page {

     private Panel borderPanel = new Panel("borderPanel", "/panel/border-panel.htm");

     private CustomerPanel customerPanel = new CustomerPanel("panel");

     public void onInit() {
         // Add CustomerPanel to the Border panel
         parentPanel.add(childPanel);

         // Add border panel to page
         addControl(parentPanel);
     }
 } 

The Page template, /nested-demo.htm, would reference the $borderPanel variable:

 $borderPanel 

Template Model

To render the panel's template, a model is created (createTemplateModel()) which is merged with the template. This model will include the page model values, plus any Panel defined model values, with the Panel's values overriding the Page defined values. In addition a number of predefined values are automatically added to the 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

See Also:

Serialized Form

Field Summary

protected boolean	active The panel active value, "true" by default.
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<String,Object>	model A temporary storage for model objects until the Page is set.
protected List<Panel>	panels The list of sub panels.
protected String	template The path of the template to render.

Fields inherited from class org.apache.click.control.AbstractContainer

controlMap, controls

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

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	addControl(Control control) Deprecated. use AbstractContainer.add(org.apache.click.Control) instead
void	addModel(String name, Object value) Add the named object value to the Panels model map.
protected Map<String,Object>	createTemplateModel() Create a model to merge with the template.
String	getId() Return the panel id value.
String	getLabel() Return the panel display label.
Map<String,Object>	getModel() Return the panels model map.
List<Panel>	getPanels() Return the list of sub panels associated with this panel.
String	getTemplate() Return the path of the template to render.
Control	insert(Control control, int index) Add the control to the panel and return the specified control.
boolean	isActive() Return true if the panel is active.
boolean	isDisabled() Return true if the panel is disabled.
void	onInit() Initialize the panel.
boolean	onProcess() This method processes the Panel request returning true to continue processing or false otherwise.
void	onRender() Perform any pre rendering logic and invoke the onRender() method of any child controls.
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) Deprecated. use remove(org.apache.click.Control) instead
void	render(HtmlStringBuffer buffer) Render the HTML string representation of the Panel.
Control	replace(Control currentControl, Control newControl) Deprecated. this method was used for stateful pages, which have been deprecated
void	setActive(boolean active) Set the panel active flag.
void	setDisabled(boolean disabled) Set the panel disabled flag.
void	setId(String id) Set the id for this panel.
void	setLabel(String label) Set the Panel display caption.
void	setTemplate(String template) Set the path of the template to render.

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

add, contains, getControl, getControlMap, getControls, getControlSizeEst, hasControls, onDestroy, renderChildren, renderContent, renderTagEnd, toString

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

addBehavior, addStyleClass, appendAttributes, dispatchActionEvent, getActionListener, getAttribute, getAttributes, getBehaviors, getContext, getHeadElements, getHtmlImports, getMessage, getMessage, getMessages, getName, getPage, getParent, getStyle, getStyles, getTag, hasAttribute, hasAttributes, hasBehaviors, hasStyles, isAjaxTarget, onDeploy, removeBehavior, removeStyleClass, renderTagBegin, setActionListener, setAttribute, setListener, setName, setParent, setStyle

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.apache.click.Control

getBehaviors, getContext, getHeadElements, getMessages, getName, getParent, hasBehaviors, isAjaxTarget, onDeploy, setListener, 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<String,Object> model

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

panels

protected List<Panel> panels

The list of sub panels.

template

protected String template

The path of the template to render.

active

protected boolean active

The panel active value, "true" by default.

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

id - the id HTML attribute value

template - the template path

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)

Deprecated. use AbstractContainer.add(org.apache.click.Control) instead

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

See Also:

AbstractContainer.add(org.apache.click.Control)

insert

public Control insert(Control control,
                      int index)

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

Please note: if the Panel contains a control with the same name as the given control, that control will be replaced by the given control. If a control has no name defined it cannot be replaced.

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

• If the control name is defined, it will be added to the Panel model using the control name as the key. The control can be referenced via it's name from the Panel template.
• If the specified control is an instanceof a Panel, it will be added to the list of panels and can be accessed through getPanels().

Specified by:

insert in interface Container

Overrides:

insert in class AbstractContainer

Parameters:

control - the control to add to the container

index - the index at which the control is to be inserted

Returns:

the control that was added to the container

Throws:

IllegalArgumentException - if the control is null

See Also:

Container.add(org.apache.click.Control)

replace

public Control replace(Control currentControl,
                       Control newControl)

Deprecated. this method was used for stateful pages, which have been deprecated

Replace the current control with the new control.

Specified by:

replace in interface Container

Overrides:

replace in class AbstractContainer

Parameters:

currentControl - the current control container in the panel

newControl - the control to replace the current control

Returns:

the new control that replaced the current control

Throws:

IllegalArgumentException - if the currentControl or newControl is null

IllegalStateException - if the currentControl is not contained in the panel

See Also:

Container.replace(org.apache.click.Control, org.apache.click.Control)

removeControl

public boolean removeControl(Control control)

Deprecated. use remove(org.apache.click.Control) instead

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(org.apache.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(org.apache.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(org.apache.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 the panel disabled flag. Disabled panels are not processed nor is their action event fired.

Parameters:

disabled - the disabled flag

isActive

public boolean isActive()

Return true if the panel is active.

Returns:

true if the panel is active

setActive

public void setActive(boolean active)

Set the panel active flag. The active property is normally managed and set by Panel containers. Please note: inactive panels do not have their events (onInit(), onProcess(), onRender()) processed.

Parameters:

active - the active 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:

setActive(boolean), 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

addModel

public void addModel(String name,
                     Object value)

Add the named object value to the Panels model map.

Please note: if the Panel contains an object with a matching name, that object will be replaced by the given value.

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

getModel

public Map<String,Object> 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<Panel> getPanels()

Return the list of sub panels associated with this panel. Do not add sub panels using this method, use AbstractContainer.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

onInit

public void onInit()

Initialize the panel.

Please note: inactive panels are not initialized.

Specified by:

onInit in interface Control

Overrides:

onInit in class AbstractContainer

See Also:

Control.onInit()

onProcess

public boolean onProcess()

This method processes the Panel request returning true to continue processing or false otherwise.

Please note: Disabled and inactive panels are not processed.

Specified by:

onProcess in interface Control

Overrides:

onProcess in class AbstractContainer

Returns:

true to continue Panel event processing, false otherwise

See Also:

Control.onProcess().

onRender

public void onRender()

Perform any pre rendering logic and invoke the onRender() method of any child controls.

Please note: inactive panels are not rendered.

Specified by:

onRender in interface Control

Overrides:

onRender in class AbstractContainer

See Also:

Control.onRender()

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<String,Object> 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.