com.arsdigita.bebop
Class Page

java.lang.Object
  extended bycom.arsdigita.bebop.Completable
      extended bycom.arsdigita.bebop.SimpleComponent
          extended bycom.arsdigita.bebop.TextStylable
              extended bycom.arsdigita.bebop.BlockStylable
                  extended bycom.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.

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.



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