com.arsdigita.bebop
Class Page

java.lang.Object
  com.arsdigita.bebop.Completable
      com.arsdigita.bebop.SimpleComponent
          com.arsdigita.bebop.TextStylable
              com.arsdigita.bebop.BlockStylable
                  com.arsdigita.bebop.Page

All Implemented Interfaces:

Cloneable, Component, Container, Lockable

Direct Known Subclasses:

BasePage, ConfirmPage, MySitePage, TemplatePage, WorkflowAdminPage

public class Page

extends BlockStylable

implements Container

The top-level container for all Bebop components and containers.

• Holds references to the components of a page.
• Provides methods for servicing requests and for notifying other components that a request for this page has been received through ActionListeners.
• Tracks request parameters for stateful components, such as tabbed panes and sortable tables.

A typical Page may be created as follows:

 Page p = new Page("Hello World");
 p.add(new Label("Hello World");
 p.lock();
 

Version:

$Id: //core-platform/dev/src/com/arsdigita/bebop/Page.java#22 $

Author:

David Lutterkort, Stanislav Freidin, Uday Mathur

Field Summary

protected BitSet	m_invisible The default (initial) visibility of components.
protected Container	m_panel Container that renders this Page.
static String	versionId

Fields inherited from class com.arsdigita.bebop.BlockStylable

ABSBOTTOM, ABSMIDDLE, BASELINE, BOTTOM, CENTER, FULL_WIDTH, INSERT, LEFT, MIDDLE, RIGHT, TEXTTOP, TOP

Fields inherited from class com.arsdigita.bebop.SimpleComponent

m_attr

Fields inherited from interface com.arsdigita.bebop.Component

BEBOP_XML_NS, CLASS, ID, ON_CLICK, STYLE

Constructor Summary

Page()
Creates an empty page with default title and implicit BoxPanel container.

Page(Label title)
Creates an empty page with the specified title and implicit BoxPanel container.

Page(Label title, Container panel)
Creates an empty page with the specified title and panel.

Page(String title)
Creates an empty page with the specified title and implicit BoxPanel container.

Page(String title, Container panel)
Creates an empty page with the specified title and panel.

Method Summary

void	add(Component c) Adds a component to this container.
void	add(Component c, int constraints) Adds a component with the specified layout constraints to this container.
void	addActionListener(ActionListener l) Registers a listener that is notified whenever a request to this page is made, after the selected component has had a chance to respond.
void	addClientStylesheet(String styleSheetURI, String mimeType) Adds a client-side stylesheet that should be used in HTML output.
void	addComponent(Component c) Deprecated. This method will become private in ACS 5.0.
void	addComponentStateParam(Component c, ParameterModel p) Registers a state parameter for a component.
void	addGlobalStateParam(ParameterModel p) Adds a global state parameter to this page.
void	addRequestListener(RequestListener l) Registers a listener that is notified whenever a request to this page is made, before the selected component has had a chance to respond.
Document	buildDocument(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse res) Builds a DOM Document from the current request state by doing a depth-first tree walk on the current set of components in this Page, calling generateXML on each.
Iterator	children() Returns an iterator over the children of this component.
boolean	contains(Object o) Returns true if this list contains the specified element.
protected void	fireActionEvent(PageState state) Broadcasts an ActionEvent to all registered listeners.
protected void	fireRequestEvent(PageState state) Broadcasts a RequestEvent to all registered listeners.
void	generateXML(PageState state, Document parent) Constructs a DOM or JDOM tree with all components on the page.
void	generateXML(PageState state, Element elt) Do nothing.
protected Element	generateXMLHelper(PageState ps, Document parent) Constructs the top nodes of the DOM or JDOM tree.
Component	get(int index) Returns the component at the specified position.
Component	getComponent(int i) Gets a page component by index.
Collection	getComponentParameters(Component c) Get the parameters registered for a given component.
Component	getErrorDisplay() Gets the Component that will display the validation errors in the current PageState.
Container	getPanel() Returns the panel that the Page uses for rendering its components.
Iterator	getParameters() Gets the ParameterModels held in this Page.
FormModel	getStateModel() Gets the form model that contains the parameters for the page's state.
Label	getTitle() Retrieves the title of this page.
Label	getTitle(PageState state) Retrieves the title of this page as a Bebop label component.
int	indexOf(Component c) Gets the index of a component.
boolean	isEmpty() Returns true if the container contains no components.
boolean	isUsingHttpSession() Returns true if this page should export state through the HttpSession instead of the URL query string.
boolean	isVisibleDefault(Component c) Checks whether the specified component is visible by default on the page.
void	lock() Locks the page and all its components against further modifications.
String	parameterName(Component c, String name) The global name of the parameter name in the component c.
String	parameterName(String name) The global name of the parameter name.
protected PageState	prepare(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse res) Deprecated. Use process(HttpServletRequest,HttpServletResponse) instead.
PageState	process(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) Creates a PageState object and processes it by calling the respond method on the selected component.
void	process(PageState state) Processes the supplied PageState object according to this PageModel.
void	removeActionListener(ActionListener l) Remove a previously registered action listener.
void	removeRequestListener(RequestListener l) Removes a previously registered request listener.
void	respond(PageState state) Responds to the request.
void	setErrorDisplay(Component c) Sets the Component that will display the validation errors in the current PageState.
void	setPanel(Container c) Set the Container used for rendering components on this page.
void	setStyleSheet(String styleSheetURI, String styleSheetType) Deprecated. Use addClientStylesheet instead. Will be removed on 2001-05-31.
void	setTitle(Label title) Set the title for this page from the passed in label.
void	setTitle(String title) Sets the title for this page from the passed in string.
void	setUsingHttpSession(boolean b) Indicates to this page whether it should export its entire state to subsequent requests through the URL query string, or if it should use the HttpSession instead and only use the URL query string for the control event.
void	setVisibleDefault(Component c, boolean v) Sets whether the specified component is visible by default.
int	size() Returns the number of elements in this container.
boolean	stateContains(Component c) Checks whether this component is already in the page model.
int	stateIndex(Component c) Gets the state index of a component.
int	stateSize() The number of components in the page model.

Methods inherited from class com.arsdigita.bebop.BlockStylable

setBorder, setBorder, setBorderColor, setHorizontalAlignment, setMargin, setMargin, setPadding, setPadding, setVerticalAlignment

Methods inherited from class com.arsdigita.bebop.TextStylable

setBackgroundColor, setColor

Methods inherited from class com.arsdigita.bebop.SimpleComponent

clone, exportAttributes, getAttribute, getClassAttr, getIdAttr, getKey, getMetaDataAttribute, getStyleAttr, hasAttributes, isLocked, isVisible, register, register, setAttribute, setClassAttr, setIdAttr, setKey, setMetaDataAttribute, setStyleAttr, setVisible

Methods inherited from class com.arsdigita.bebop.Completable

addCompletionListener, fireCompletionEvent

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.arsdigita.bebop.Component

getClassAttr, getIdAttr, getKey, getStyleAttr, isVisible, register, register, setClassAttr, setIdAttr, setKey, setStyleAttr, setVisible

Methods inherited from interface com.arsdigita.util.Lockable

isLocked

Field Detail

versionId

public static final String versionId

See Also:

Constant Field Values

m_panel

protected Container m_panel

Container that renders this Page.

m_invisible

protected BitSet m_invisible

The default (initial) visibility of components. The encoding is identical to that for PageState.m_invisible. This variable is package-friendly since it needs to be accessed by PageState.

Constructor Detail

Page

public Page(String title,
            Container panel)

Creates an empty page with the specified title and panel.

Parameters:

title - title for this page

panel - container for this page

Page

public Page(Label title,
            Container panel)

Creates an empty page with the specified title and panel.

Parameters:

title - title for this page

panel - container for this page

Page

public Page()

Creates an empty page with default title and implicit BoxPanel container.

Page

public Page(Label title)

Creates an empty page with the specified title and implicit BoxPanel container.

Parameters:

title - title for this page

Page

public Page(String title)

Creates an empty page with the specified title and implicit BoxPanel container.

Parameters:

title - title for this page

Method Detail

isUsingHttpSession

public boolean isUsingHttpSession()

Returns true if this page should export state through the HttpSession instead of the URL query string.

If this returns true, then PageState.stateAsURL() will only export the control event as a URL query string. If this returns false, then stateAsURL() will export the entire page state.

Returns:

true if this page should export state through the HttpSession; false if it should export using the URL query string.

See Also:

PageState.stateAsURL()

setUsingHttpSession

public void setUsingHttpSession(boolean b)

Indicates to this page whether it should export its entire state to subsequent requests through the URL query string, or if it should use the HttpSession instead and only use the URL query string for the control event.

Parameters:

b - true if PageState.stateAsURL() will export only the control event as a URL query string. false if stateAsURL() will export the entire page state.

See Also:

PageState.stateAsURL()

add

public void add(Component c)

Adds a component to this container.

Specified by:

add in interface Container

Parameters:

c - component to add to this container

add

public void add(Component c,
                int constraints)

Adds a component with the specified layout constraints to this container. Layout constraints are defined in each layout container as static ints. To specify multiple constraints, use bitwise OR.

Specified by:

add in interface Container

Parameters:

c - component to add to this container

constraints - layout constraints (a bitwise OR of static ints in the particular layout)

contains

public boolean contains(Object o)

Returns true if this list contains the specified element. More formally, returns true if and only if this list contains at least one element e such that (o==null ? e==null : o.equals(e)).

This method returns true only if the component has been directly added to this container. If this container contains another container that contains this component, this method returns false.

Specified by:

contains in interface Container

Parameters:

o - element whose presence in this container is to be tested

Returns:

true if this Container contains the specified component directly; false otherwise.

get

public Component get(int index)

Returns the component at the specified position. Each call to the add method increments the index. Since the user has no control over the index of added components (other than counting each call to add), this method should be used in conjunction with indexOf.

Specified by:

get in interface Container

Parameters:

index - the index of the item to be retrieved from this Container

Returns:

the component at the specified position in this container.

indexOf

public int indexOf(Component c)

Gets the index of a component.

Specified by:

indexOf in interface Container

Parameters:

c - component to search for

Returns:

the index in this list of the first occurrence of the specified element, or -1 if this list does not contain this element.

isEmpty

public boolean isEmpty()

Returns true if the container contains no components.

Specified by:

isEmpty in interface Container

Returns:

true if this container contains no components; false otherwise.

size

public int size()

Returns the number of elements in this container. This does not recursively count the components that are indirectly contained in this container.

Specified by:

size in interface Container

Returns:

the number of components directly in this container.

children

public Iterator children()

Description copied from interface: Component

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

Specified by:

children in interface Component

Overrides:

children in class SimpleComponent

getPanel

public final Container getPanel()

Returns the panel that the Page uses for rendering its components.

Returns:

the panel.

setPanel

public void setPanel(Container c)

Set the Container used for rendering components on this page. Caution should be used with this function, as the existing container is simply overwritten.

getTitle

public final Label getTitle()

Retrieves the title of this page.

Returns:

the static title of this page.

getTitle

public final Label getTitle(PageState state)

Retrieves the title of this page as a Bebop label component.

Parameters:

state - the state of the current request

Returns:

the title of the page for the current request.

setTitle

public void setTitle(String title)

Sets the title for this page from the passed in string.

Parameters:

title - title for this page

setTitle

public void setTitle(Label title)

Set the title for this page from the passed in label.

Parameters:

title - title for this page

setErrorDisplay

public final void setErrorDisplay(Component c)

Sets the Component that will display the validation errors in the current PageState. Any validation error in the PageState will cause the Page to completely ignore all other components and render only the error display component.

By default, a PageErrorDisplay component is used to display the validation errors.

Parameters:

c - the component that will display the validation errors in the current PageState

getErrorDisplay

public final Component getErrorDisplay()

Gets the Component that will display the validation errors in the current PageState. Any validation error in the PageState will cause the Page to completely ignore all other components and render only the error display component.

By default, a PageErrorDisplay component is used to display the validation errors.

Returns:

the component that will display the validation errors in the current PageState.

setStyleSheet

public void setStyleSheet(String styleSheetURI,
                          String styleSheetType)

Deprecated. Use addClientStylesheet instead. Will be removed on 2001-05-31.

Sets a stylesheet that should be used in HTML output. To use a CSS stylesheet, call something like setStyleSheet("style.css", "text/css").

These values will ultimately wind up in a <link> tag in the head of the HTML page.

Note that the stylesheet set with this call has nothing to do with the XSLT stylesheet (transformer) that is applied to the XML generated from this page.

Parameters:

styleSheetURI - the location of the stylesheet

styleSheetType - the MIME type of the stylesheet, usually text/css

addClientStylesheet

public void addClientStylesheet(String styleSheetURI,
                                String mimeType)

Adds a client-side stylesheet that should be used in HTML output. Arbitrarily many client-side stylesheets can be added with this method. To use a CSS stylesheet, call something like setStyleSheet("style.css", "text/css").

These values will ultimately wind up in a <link> tag in the head of the HTML page.

Note that the stylesheet set with this call has nothing to do with the XSLT stylesheet (transformer) that is applied to the XML generated from this page.

Parameters:

styleSheetURI - the location of the stylesheet

mimeType - the MIME type of the stylesheet, usually text/css

addGlobalStateParam

public void addGlobalStateParam(ParameterModel p)

Adds a global state parameter to this page. Global parameters are values that need to be preserved between requests, but that have no special connection to any of the components on the page. For a page that displays details about an item, a global parameter would be used to identify the item.

If the parameter was previously added as a component state parameter, its name is unmangled and stays unmangled.

Parameters:

p - the global parameter to add

See Also:

addComponentStateParam(com.arsdigita.bebop.Component, com.arsdigita.bebop.parameters.ParameterModel)

generateXMLHelper

protected Element generateXMLHelper(PageState ps,
                                    Document parent)

Constructs the top nodes of the DOM or JDOM tree. Used by generateXML(PageState, Document) below.

Generates DOM fragment:

 <bebop:page>
   <bebop:title> ... value set with setTitle ... </bebop:title>
   <bebop:stylesheet href='styleSheetURI' type='mimeType'>
   ... page content gnerated by children ...
 </bebop:page>

The content of the <title> element can be set by calling setTitle. The <stylesheet> element will only be present if a stylesheet has been set with setStyleSheet.

Parameters:

ps - the page state for the current page

parent - the DOM node for the whole Document

generateXML

public void generateXML(PageState state,
                        Document parent)

Constructs a DOM or JDOM tree with all components on the page. The tree represents the page that results from the HttpServletRequest kept in the state.

Parameters:

state - the page state produced by process(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)

parent - the DOM node for the whole Document

See Also:

process

generateXML

public void generateXML(PageState state,
                        Element elt)

Do nothing. Top-level add nodes is meaningless.

Specified by:

generateXML in interface Component

Overrides:

generateXML in class SimpleComponent

process

public PageState process(javax.servlet.http.HttpServletRequest request,
                         javax.servlet.http.HttpServletResponse response)
                  throws javax.servlet.ServletException

Creates a PageState object and processes it by calling the respond method on the selected component. Processes a request by notifying the component from which the process originated and broadcasts an ActionEvent to all the listeners that registered with addActionListener.

Throws:

javax.servlet.ServletException

See Also:

generateXML

process

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

Processes the supplied PageState object according to this PageModel. Calls the respond method on the selected Bebop component.

Throws:

javax.servlet.ServletException

prepare

protected PageState prepare(javax.servlet.http.HttpServletRequest req,
                            javax.servlet.http.HttpServletResponse res)
                     throws javax.servlet.ServletException

Deprecated. Use process(HttpServletRequest,HttpServletResponse) instead.

Does all the servicing of a request except output generation. This includes most of the common duties of buildDocument and print.

Throws:

javax.servlet.ServletException

buildDocument

public Document buildDocument(javax.servlet.http.HttpServletRequest req,
                              javax.servlet.http.HttpServletResponse res)
                       throws javax.servlet.ServletException

Builds a DOM Document from the current request state by doing a depth-first tree walk on the current set of components in this Page, calling generateXML on each. Does NOT do the rendering. If the HTTP response has already been committed, does not build the XML document.

Returns:

a DOM ready for rendering, or null if the response has already been committed.

Throws:

javax.servlet.ServletException

lock

public void lock()

Locks the page and all its components against further modifications.

Locking a page helps in finding mistakes that result from modifying a page's structure.

Specified by:

lock in interface Lockable

Overrides:

lock in class SimpleComponent

respond

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

Description copied from interface: Component

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.

Specified by:

respond in interface Component

Overrides:

respond in class SimpleComponent

Parameters:

state - the current page state

Throws:

javax.servlet.ServletException

addActionListener

public void addActionListener(ActionListener l)

Registers a listener that is notified whenever a request to this page is made, after the selected component has had a chance to respond.

removeActionListener

public void removeActionListener(ActionListener l)

Remove a previously registered action listener.

addRequestListener

public void addRequestListener(RequestListener l)

Registers a listener that is notified whenever a request to this page is made, before the selected component has had a chance to respond.

removeRequestListener

public void removeRequestListener(RequestListener l)

Removes a previously registered request listener.

fireActionEvent

protected void fireActionEvent(PageState state)

Broadcasts an ActionEvent to all registered listeners. The source of the event is this page, and the state recorded in the event is the one resulting from processing the current request.

fireRequestEvent

protected void fireRequestEvent(PageState state)

Broadcasts a RequestEvent to all registered listeners. The source of the event is this page, and the state recorded in the event is the one resulting from processing the current request.

addComponent

public void addComponent(Component c)

Deprecated. This method will become private in ACS 5.0.

Adds a component to the page model.

addComponentStateParam

public void addComponentStateParam(Component c,
                                   ParameterModel p)

Registers a state parameter for a component. It is permissible to register the same state parameter several times, from the same or different components. The name of the parameter will be changed to ensure that it won't clash with any other component's parameter. If the parameter is added more than once, the name is only changed the first time it is added.

Parameters:

c - the component to register the parameter for

p - the state parameter to register

See Also:

addGlobalStateParam(com.arsdigita.bebop.parameters.ParameterModel)

getComponentParameters

public Collection getComponentParameters(Component c)

Get the parameters registered for a given component.

stateIndex

public int stateIndex(Component c)

Gets the state index of a component. This is the number assigned to the component in the register traveral

Parameters:

c - the component to search for

Returns:

the index in this list of the first occurrence of the specified element, or -1 if this list does not contain this element.

stateSize

public int stateSize()

The number of components in the page model.

stateContains

public boolean stateContains(Component c)

Checks whether this component is already in the page model.

getComponent

public Component getComponent(int i)

Gets a page component by index.

getStateModel

public final FormModel getStateModel()

Gets the form model that contains the parameters for the page's state.

getParameters

public Iterator getParameters()

Gets the ParameterModels held in this Page.

Returns:

an iterator of ParameterModels.

isVisibleDefault

public boolean isVisibleDefault(Component c)

Checks whether the specified component is visible by default on the page.

Parameters:

c - a component contained in the page

Returns:

true if the component is visible by default; false otherwise.

See Also:

setVisibleDefault, Component.setVisible

setVisibleDefault

public void setVisibleDefault(Component c,
                              boolean v)

Sets whether the specified component is visible by default. The default visibility is used when a page is displayed for the first time and on subsequent requests until the visibility of a component is changed explicitly with Component.setVisible.

When a component is first added to a page, it is visible.

Parameters:

c - a component whose visibility is to be set

v - true if the component is visible; false otherwise.

See Also:

Component.setVisible, Component.register

parameterName

public String parameterName(Component c,
                            String name)

The global name of the parameter name in the component c.

parameterName

public String parameterName(String name)

The global name of the parameter name.