com.arsdigita.bebop
Class PropertyEditor

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.SimpleContainer
                      extended bycom.arsdigita.bebop.PropertyEditor
All Implemented Interfaces:
Cloneable, Component, Container, Lockable

public class PropertyEditor
extends SimpleContainer

Maintains a set of forms that are used when editing the properties of some object. The component maintains a single display pane and a list of forms that are selectable by links.

By default, the component looks something like this:


 +----------------+
 |                |
 |  Display Pane  |
 |                |
 +----------------+
 [link to form1]
 [link to form2]
 [link to form3]
 
When the user clicks on a link, the display pane is hidden and the corresponding form is shown.

 Enter foo: [           ]
 Enter bar: [           ]

          [Save] [Cancel]
 
When the user clicks the Save or Cancel button on the form, the form is hidden and the display pane (with its list of links) is shown once again.

The simple usage pattern for this class is as follows:


 PropertyEditor editor = new PropertyEditor();
 editor.setDisplayComponent(new FooComponent());
 NameEditForm n = new NameEditForm();
 editor.add("name", "Edit Name", n, n.getCancelButton());
 AddressEditForm a = new AddressEditForm();
 editor.add("address", "Edit Address", a, a.getCancelButton());
 
The PropertyEditor will automatically add the right listeners to the forms.

This class is used extensively in the default authoring kit steps, especially PageEdit and TextPageBody in CMS.

Advanced Usage:
The PropertyEditor may be used to maintain visibility of any components, not just forms. The addComponent(String, String, Component) method can be used to add an arbitrary component to the editor. The component will be shown in the list of links, along with other components and/or forms. The component will be shown as usual when the user clicks on a link. However, you must be sure to include a call to showDisplayPane(PageState) when the component needs to be hidden.

In addition, it is possible to manually generate ActionLinks that will display the right components in the editor. The addComponent(String, Component) method can be used to add a component to the PropertyEditor without automatically generating the link for it. The addVisibilityListener(ActionLink, String) method can then be used to add an appropriate ActionListener to any ActionLink. For example:

// Add a form
 Form fooForm = new FooForm();
 editor.addComponent(FOO_FORM, fooForm);
 editor.addListeners(fooForm, fooForm.getCancelButton());
 // Create a link that shows the form
 fooLink = new ActionLink("Edit the Foo property");
 editor.addVisibilityListener(fooLink, FOO_FORM);
Note that the visibility of the form will be handled automatically. There is no need to show or hide it manually. This approach allows greater flexibility in placing links on a page. The links may be part of the editor's display pane, but they do not have to be.

More-advanced Usage:
The PropertyEditor is backed by a PropertyEditorModel through a PropertyEditorModelBuilder. Therefore, the PropertyEditor is a model-backed component, as described in the Bebop tutorials. This means that the list of properties for the editor could be generated dynamically during each request. The setModelBuilder(PropertyEditorModelBuilder) method can be used to set a specialized PropertyEditorModelBuilder for the editor. In order to write the model builder, you may choose to extend the protected inner classes PropertyEditor.DefaultModelBuilder and PropertyEditor.DefaultModel. It is also possible to write the model builder and the corresponding model from scratch. However, most people won't need to do this.

For example, SecurityPropertyEditor uses a custom PropertyEditorModelBuilder in order to hide the links for properties which the web user is not allowed to edit.

Version:
$Revision: #12 $ $DateTime: 2004/04/07 16:07:11 $
Author:
Stanislav Freidin

Nested Class Summary
protected static class PropertyEditor.DefaultModel
          Default implementation of the PropertyEditorModel.
protected static class PropertyEditor.DefaultModelBuilder
          Default implementation of the PropertyEditorModelBuilder.
protected static class PropertyEditor.IdentityCellRenderer
          Renders the components generated by the model directly
 
Field Summary
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
PropertyEditor()
          Constructs a new, empty PropertyEditor.
PropertyEditor(Component display)
          Constructs a new PropertyEditor with the given display component.
PropertyEditor(Component display, Container pane)
          Constructs a new PropertyEditor with the given display component and display pane.
 
Method Summary
 void add(String key, String label, Form form)
          Adds a form to the set of forms that can be used to edit the properties.
 void add(String key, String label, FormSection formSection)
          Adds a form to the set of forms that can be used to edit the properties.
 void add(String key, String label, FormSection formSection, Submit cancelButton)
          Adds a form to the set of forms that can be used to edit the properties.
 void add(String key, String label, Form form, Submit cancelButton)
          Adds a form to the set of forms that can be used to edit the properties.
 void addCancelListener(FormSection form, Submit cancelButton)
          Adds a submission listener to the form that will hide all components and show the display pane.
 void addComponent(String key, Component c)
          Adds a component to the property editor.
 void addComponent(String key, String label, Component c)
          Adds a component to the list of links.
 void addListeners(FormSection form, Submit cancelButton)
          Adds all required listeners to the form to ensure that if the form is either submitted successfully or cancelled, the display pane will be shown.
 void addProcessListener(FormSection form)
          Adds a process listener to the form that will hide all components and show the display pane.
 void addVisibilityListener(ActionLink l, String key)
          This method can be used to add an ActionListener to any ActionLink, causing the action link to show the specified component when it is clicked.
 Component getComponent(String key)
          Retrieves the component at the specified key.
 Component getDisplayComponent()
          Returns the display component.
 Container getDisplayPane()
          Returns the display pane (component + list).
protected  SequentialMap getLabelsMap()
          Returns the map of labels.
 List getList()
          Returns the List that contains all the links.
protected  PropertyEditorModel getModel(PageState s)
          Returns the PropertyEditorModel in use during the current request.
protected  PropertyEditorModelBuilder getModelBuilder()
          Returns the PropertyEditorModelBuilder that supplies this property editor with its PropertyEditorModel during each request.
 String getSelectedComponentKey(PageState state)
          Returns the key of the currently visible component, or null if the display pane is currently visible.
 void lock()
          Locks this component.
 void register(Page p)
          Registers state parameters for the page with its model.
 void setDisplayComponent(Component c)
          Adds the display component if it has not been added already.
protected  void setModelBuilder(PropertyEditorModelBuilder b)
          Sets the PropertyEditorModelBuilder that will supply this property editor with its PropertyEditorModel during each request.
 void showComponent(PageState state, String key)
          Shows the component that is identified by the specified key.
 void showDisplayPane(PageState state)
          Hides the form(s) and shows the display pane.
 
Methods inherited from class com.arsdigita.bebop.SimpleContainer
add, add, children, contains, generateChildrenXML, generateParent, generateXML, get, getNamespace, getTag, indexOf, isEmpty, setNamespace, setTag, size
 
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, respond, 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, respond, 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
Constructor Detail

PropertyEditor

public PropertyEditor()
Constructs a new, empty PropertyEditor. The setDisplayComponent(Component) method must be called before this component is locked.


PropertyEditor

public PropertyEditor(Component display)
Constructs a new PropertyEditor with the given display component. The pane defaults to a SimpleContainer.

Parameters:
display - the display component

PropertyEditor

public PropertyEditor(Component display,
                      Container pane)
Constructs a new PropertyEditor with the given display component and display pane.

Parameters:
display - the display component
pane - the display pane. The caller should pass in a freshly allocated Container.
Method Detail

register

public void register(Page p)
Description copied from interface: Component
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"

Specified by:
register in interface Component
Overrides:
register in class SimpleComponent

showDisplayPane

public void showDisplayPane(PageState state)
Hides the form(s) and shows the display pane.

Parameters:
state - the page state

showComponent

public void showComponent(PageState state,
                          String key)
Shows the component that is identified by the specified key.

Parameters:
state - the page state

getSelectedComponentKey

public String getSelectedComponentKey(PageState state)
Returns the key of the currently visible component, or null if the display pane is currently visible.

Parameters:
state - the page state
Returns:
the key of the currently visible component, or null if the display pane is visible.

setDisplayComponent

public void setDisplayComponent(Component c)
Adds the display component if it has not been added already.

Parameters:
c - the display component to add

addComponent

public void addComponent(String key,
                         Component c)
Adds a component to the property editor. The component will be completely invisible. It is up to the user to call showComponent(PageState, String) to display the component and to call showDisplayPane(PageState) when the component needs to be hidden.

Parameters:
key - the symbolic key for the component (must be unique for this PropertyEditor)
c - the component

addComponent

public void addComponent(String key,
                         String label,
                         Component c)
Adds a component to the list of links. It is up to the component to correctly call showDisplayPane(PageState) when it is done.

Parameters:
key - the symbolic key for the component (must be unique for this PropertyEditor)
label - the label for the link
c - the component

add

public void add(String key,
                String label,
                Form form)
Adds a form to the set of forms that can be used to edit the properties.

Parameters:
key - the symbolic key for the form (must be unique for this PropertyEditor)
label - the label for the link
form - the form component

add

public void add(String key,
                String label,
                Form form,
                Submit cancelButton)
Adds a form to the set of forms that can be used to edit the properties.

Parameters:
key - the symbolic key for the form (must be unique for this PropertyEditor)
label - the label for the link
form - the form component
cancelButton - the Cancel button on the form

add

public void add(String key,
                String label,
                FormSection formSection)
Adds a form to the set of forms that can be used to edit the properties.

Parameters:
key - the symbolic key for the form (must be unique for this PropertyEditor)
label - the label for the link
formSection - the form component

add

public void add(String key,
                String label,
                FormSection formSection,
                Submit cancelButton)
Adds a form to the set of forms that can be used to edit the properties.

Parameters:
key - the symbolic key for the form (must be unique for this PropertyEditor)
label - the label for the link
formSection - the form component
cancelButton - the Cancel button on the form

getComponent

public Component getComponent(String key)
Retrieves the component at the specified key.

Parameters:
key - the key of the component to retrieve
Returns:
a component that has been added to this PropertyEditor at the specified key, or null if no such component exists.

addCancelListener

public void addCancelListener(FormSection form,
                              Submit cancelButton)
Adds a submission listener to the form that will hide all components and show the display pane. This method should be used to add submission listeners to forms that are buried deep inside some component and are not members of this PropertyEditor.

Parameters:
form - the form
cancelButton - the Cancel button on the form

addProcessListener

public void addProcessListener(FormSection form)
Adds a process listener to the form that will hide all components and show the display pane. This method should be used to add process listeners to forms that are buried deep inside some component and are not members of this PropertyEditor.

Parameters:
form - the form

addListeners

public void addListeners(FormSection form,
                         Submit cancelButton)
Adds all required listeners to the form to ensure that if the form is either submitted successfully or cancelled, the display pane will be shown. This method should be used to add listeners to forms that are buried deep inside some component, and are not members of this PropertyEditor.

Parameters:
form - the form
cancelButton - the Cancel button on the form

addVisibilityListener

public void addVisibilityListener(ActionLink l,
                                  String key)
This method can be used to add an ActionListener to any ActionLink, causing the action link to show the specified component when it is clicked. For example, this method may be useful if the ActionLink that is supposed to show the component is buried somewhere deep within the UI.

Parameters:
l - the ActionLink
key - the key of the component that will be shown when the link is clicked, as specified in the addComponent(String, Component) method
See Also:
addComponent(String, Component)

getList

public List getList()
Returns the List that contains all the links.

Returns:
the List that contains all the links.

getModelBuilder

protected final PropertyEditorModelBuilder getModelBuilder()
Returns the PropertyEditorModelBuilder that supplies this property editor with its PropertyEditorModel during each request.

Returns:
the PropertyEditorModelBuilder for this component.

setModelBuilder

protected final void setModelBuilder(PropertyEditorModelBuilder b)
Sets the PropertyEditorModelBuilder that will supply this property editor with its PropertyEditorModel during each request.

Parameters:
b - the property editor model builder

getModel

protected final PropertyEditorModel getModel(PageState s)
Returns the PropertyEditorModel in use during the current request.

Parameters:
s - represents the current request
Returns:
the PropertyEditorModel that supplies the properties for the current request.

getDisplayComponent

public Component getDisplayComponent()
Returns the display component.

Returns:
the display component.

getDisplayPane

public Container getDisplayPane()
Returns the display pane (component + list).

Returns:
the display pane (component + list).

getLabelsMap

protected SequentialMap getLabelsMap()
Returns the map of labels.

Returns:
the map of labels.

lock

public void lock()
Locks this component.

Specified by:
lock in interface Lockable
Overrides:
lock in class SimpleComponent


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