com.arsdigita.bebop
Interface Component

All Superinterfaces:
Lockable
All Known Subinterfaces:
Container, ExcursionComponent
All Known Implementing Classes:
Completable, CompoundComponent, FormSection, NullComponent, Page, PartySearchSelect, SimpleComponent, SimpleContainer

public interface Component
extends Lockable

The common interface implemented by all Bebop components. During its lifetime, a component receives the following calls from the containing page.

Visibility

A component can be either visible or invisible. Invisible components do not produce any output and containers should be careful to completely hide their presence. The visibility of a component can be influenced in a number of ways:

The Page makes sure that the visibility of components is preserved across repeated requests to the same page.

Standard Attributes

Each component supports a few standard attributes that are copied through to the output when producing either HTML or XML output. These attributes are not used internally in any way, and setting them is entirely optional.

The standard attributes appear in the output as attributes in the element generated from this component. They correspond directly to properties with setters and getters. The standard attributes are as folows.

Attribute Java property Purpose
id getIdAttr/setIdAttr Use to uniquely identify a component within the page. Uniqueness is not enforced. The id attribute allows stylesheet designers to access individual components.
class getClassAttr()/setClassAttr(String) Use as the generic name for a component. For example, if you have a UserInfoDisplay component, the class attribute can be used to name the component "UserInfoDisplay" so that a generic template rule can style all UserInfoDisplay components.
style getStyleAttr/setStyleAttr Use to add CSS style to an individual element.

Caveat: Race Conditions

When extending any Component, honor the Lockable contract indicated by extends Lockable. Beware that member variables are not inherently threadsafe, because you may be circumventing the contract. For variables that might be different for each request, use RequestLocal. If you must add member variables in the derived class, as a minimum be sure to safeguard any write access to instance variables with Assert.assertNotLocked(com.arsdigita.util.Lockable).

Version:
$Id: //core-platform/dev/src/com/arsdigita/bebop/Component.java#10 $
Author:
David Lutterkort, Stanislav Freidin, Rory Solomon

Field Summary
static String BEBOP_XML_NS
          The XML namespace used by all the Bebop components.
static String CLASS
          The name for the class attribute.
static String ID
          The name for the ID attribute.
static String ON_CLICK
          The onClick event.
static String STYLE
          The name for the style attribute.
static String versionId
           
 
Method Summary
 Iterator children()
          Returns an iterator over the children of this component.
 void generateXML(PageState state, Element parent)
          Adds a DOM subtree representing this component under the given parent node.
 String getClassAttr()
          Gets the class attribute.
 String getIdAttr()
          Gets the id attribute.
 String getKey()
          Retrieves the programmer-supplied key.
 String getStyleAttr()
          Gets the style attribute.
 boolean isVisible(PageState state)
          Determines whether the component is visible in the request represented by state.
 void register(Form f, FormModel m)
          Registers form parameters with the form model for this form.
 void register(Page p)
          Registers state parameters for the page with its model.
 void respond(PageState state)
          Responds to the request.
 void setClassAttr(String theClass)
          Sets the class attribute.
 void setIdAttr(String id)
          Sets the id attribute.
 Component setKey(String key)
          Supplies a key for making parameter names unique.
 void setStyleAttr(String style)
          Sets the style attribute.
 void setVisible(PageState state, boolean v)
          Changes the visibility of the component.
 
Methods inherited from interface com.arsdigita.util.Lockable
isLocked, lock
 

Field Detail

versionId

public static final String versionId
See Also:
Constant Field Values

BEBOP_XML_NS

public static final String BEBOP_XML_NS
The XML namespace used by all the Bebop components.

See Also:
Constant Field Values

CLASS

public static final String CLASS
The name for the class attribute.

See Also:
setClassAttr(String), Standard Attributes, Constant Field Values

STYLE

public static final String STYLE
The name for the style attribute.

See Also:
setStyleAttr(String), Standard Attributes, Constant Field Values

ID

public static final String ID
The name for the ID attribute.

See Also:
setIdAttr(java.lang.String), Standard Attributes, Constant Field Values

ON_CLICK

public static final String ON_CLICK
The onClick event.

See Also:
Constant Field Values
Method Detail

generateXML

public void generateXML(PageState state,
                        Element parent)

Adds a DOM subtree representing this component under the given parent node. Uses the request values stored in state.

Parameters:
state - represents the current request
parent - the node under which the DOM subtree should be added

respond

public void respond(PageState state)
             throws javax.servlet.ServletException

Responds to the request. This method is only called if the request was made from a link or form that the component put on the page in the PageState.stateAsURL() previous request.

No output should be generated on the HTTP response. The component can store intermediate results in the state by calling setAttribute.

This method is called before any output is printed to the HTTP response so that the component can forward to a different page and thereby commit the response.

Parameters:
state - represents the current request
Throws:
javax.servlet.ServletException

children

public Iterator children()
Returns an iterator over the children of this component. If the component has no children, returns an empty (not null) iterator.

Returns:
an iterator over the children of this component.

register

public void register(Page p)
Registers state parameters for the page with its model. A simple component with a state parameter param would do the following in the body of this method:
   p.addComponent(this);
   p.addComponentStateParam(this, param);
 
You should override this method to set the default visibility of your component:
 public void register(Page p) {
     super.register(p);
     p.setVisibleDefault(childNotInitiallyShown,false);
     p.setVisibleDefault(anotherChild, false);
 }
 
Always call super.register when you override register. Otherwise your component may malfunction and produce errors like "Widget ... isn't associated with any Form"


register

public void register(Form f,
                     FormModel m)
Registers form parameters with the form model for this form. This method is only important for form sections and widgets (components that have a connection to an HTML form). Other components can implement it as a no-op.


getClassAttr

public String getClassAttr()
Gets the class attribute.

Returns:
the class attribute.
See Also:
setClassAttr(String), Standard Attributes

setClassAttr

public void setClassAttr(String theClass)
Sets the class attribute.

Parameters:
theClass - a valid XML name
See Also:
Standard Attributes, getClassAttr()

getStyleAttr

public String getStyleAttr()
Gets the style attribute.

Returns:
the style attribute.
See Also:
setStyleAttr(java.lang.String), Standard Attributes

setStyleAttr

public void setStyleAttr(String style)
Sets the style attribute. style should be a valid CSS style, because its value will be copied verbatim to the output and appear as a style attribute in the top level XML or HTML output element.

Parameters:
style - a valid CSS style description for use in the style attribute of an HTML tag
See Also:
Standard Attributes

getIdAttr

public String getIdAttr()
Gets the id attribute.

Returns:
the id attribute.
See Also:
Standard Attributes, setIdAttr(String id)

setIdAttr

public void setIdAttr(String id)
Sets the id attribute. id should be an XML name that is unique within the Page in which this component is contained. The value of id is copied literally to the output and not used for internal processing.

Parameters:
id - a valid XML identifier
See Also:
Standard Attributes

setKey

public Component setKey(String key)
Supplies a key for making parameter names unique. To be used instead of the component's index (see Component Prefix). To avoid collision with indexOf, it should (1) be a legal fragment of a cgi parameter, (2) differ from "g", and (3) not start with a digit.


getKey

public String getKey()
Retrieves the programmer-supplied key. Normally, there is no such key and the method returns null.

Returns:
the programmer-supplied key.

isVisible

public boolean isVisible(PageState state)
Determines whether the component is visible in the request represented by state.

Parameters:
state - represents the current request
Returns:
true if the component is visible in the request; false otherwise.
See Also:
setVisible, Description of Visibility above

setVisible

public void setVisible(PageState state,
                       boolean v)
Changes the visibility of the component. The component will keep the visibility that is set with this method in subsequent requests to this page.

Parameters:
state - represents the current request
v - true if the component should be visible
See Also:
Description of Visibility above


Copyright (c) 2004 Red Hat, Inc. Corporation. All Rights Reserved. Generated at July 20 2004:2337 UTC