001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017: package org.apache.cocoon.woody.formmodel;
018:
019: import org.apache.cocoon.woody.FormContext;
020: import org.apache.cocoon.woody.event.WidgetEvent;
021: import org.xml.sax.ContentHandler;
022: import org.xml.sax.SAXException;
023:
024: import java.util.Locale;
025:
026: /**
027: * Interface to be implemented by Widgets. In Woody, a form consists of a number
028: * of widgets. Each widget:
029: *
030: * <ul>
031: * <li>has an id, unique within its parent context widget. See {@link #getId()}.</li>
032: * <li>can have children (see {@link #getWidget(String)}, and can have a parent (see {@link #getParent()}.</li>
033: * <li>can hold a value (which can be any kind of object). See {@link #getValue()}.</li>
034: * <li>can read its value from a request object (and convert it from a string to its native type).
035: * See {@link #readFromRequest(FormContext)}.</li>
036: * <li>can validate itself. See {@link #validate(FormContext)}.</li>
037: * <li>can generate an XML representation of itself.</li>
038: * </ul>
039: *
040: * <p>Because widgets can have children, the widgets form a widget tree, with its root
041: * being the {@link Form} widget.</p>
042: *
043: * <p>A widget can have only a value, or only child widgets, or can have both a value and child
044: * widgets, or can have neither. This all depends on the widget implementation.</p>
045: *
046: * <p>When a request is submitted, first the {@link #readFromRequest(FormContext)} method of all widgets
047: * will be called so that they can read their value(s). Next, the {@link #validate(FormContext)} method will
048: * be called. Doing this in two steps allows the validation to compare values between widgets.
049: * See also the method {@link Form#process(FormContext)}.</p>
050: *
051: * <p>A Widget is created by calling the createInstance method on the a
052: * {@link WidgetDefinition}. A Widget holds all the data that is specific for
053: * a certain use of the widget (its value, validationerrors, ...), while the
054: * WidgetDefinition holds the data that is static accross all widgets. This
055: * keeps the Widgets small and light to create. This mechanism is similar to
056: * classes and objects in Java.
057: *
058: * @version CVS $Id: Widget.java 433543 2006-08-22 06:22:54Z crossley $
059: */
060: public interface Widget {
061:
062: /**
063: * Gets the source location of this widget.
064: */
065: public String getLocation();
066:
067: /**
068: * Returns the id of this widget.
069: */
070: public String getId();
071:
072: /**
073: * Gets the parent of this widget. If this widget is the root widget,
074: * this method returns null.
075: */
076: public Widget getParent();
077:
078: /**
079: * This method is called on a widget when it is added to a container.
080: * You shouldn't call this method unless youre implementing a widget yourself (in
081: * which case it should be called when a widget is added as child of your widget).
082: */
083: public void setParent(Widget widget);
084:
085: /**
086: * Get the {@link Form} to which this widget belongs. The form is the top-most ancestor
087: * of the widget.
088: */
089: public Form getForm();
090:
091: /**
092: * Gets the namespace of this widget. The combination of a widget's namespace
093: * with its id (see {@link #getId()} gives the widget a form-wide unique name.
094: * In practice, the namespace consists of the id's of the widget's parent widgets,
095: * separated by dots.
096: */
097: public String getNamespace();
098:
099: /**
100: * Returns the id prefixed with the namespace, this name should be unique
101: * accross all widgets on the form.
102: */
103: public String getFullyQualifiedId();
104:
105: /**
106: * Lets this widget read its data from a request. At this point the Widget
107: * may try to convert the request parameter to its native datatype (if it
108: * is not a string), but it should not yet generate any validation errors.
109: */
110: public void readFromRequest(FormContext formContext);
111:
112: /**
113: * Validates this widget and returns the outcome. Possible error messages are
114: * remembered by the widget itself and will be part of the XML produced by
115: * this widget in its {@link #generateSaxFragment(ContentHandler, Locale)} method.
116: */
117: public boolean validate(FormContext formContext);
118:
119: /**
120: * Generates an XML representation of this widget. The startDocument and endDocument
121: * SAX events will not be called. It is assumed that the prefix for the Woody namespace
122: * mentioned in Constants.WI_PREFIX is already declared (by the caller or otherwise).
123: */
124: public void generateSaxFragment(ContentHandler contentHandler,
125: Locale locale) throws SAXException;
126:
127: /**
128: * Generates SAX events for the label of this widget. The label will not be wrapped
129: * inside another element.
130: */
131: public void generateLabel(ContentHandler contentHandler)
132: throws SAXException;
133:
134: /**
135: * Returns the value of the widget. For some widgets (notably ContainerWidgets)
136: * this may not make sense, those should then simply return null here.
137: */
138: public Object getValue();
139:
140: /**
141: * Sets the value of this widget to the given object. Some widgets may not support this
142: * method, those should throw an runtime exception if you try to set their value anyway.
143: */
144: public void setValue(Object object);
145:
146: /**
147: * Returns wether this widget is required to be filled in. As with {@link #getValue()}, for some
148: * widgets this may not make sense, those should return false here.
149: */
150: public boolean isRequired();
151:
152: /**
153: * Gets the child widget of this widget with the given id, or null if there isn't such a child.
154: */
155: public Widget getWidget(String id);
156:
157: /**
158: * Broadcast an event previously queued by this widget to its event listeners.
159: */
160: public void broadcastEvent(WidgetEvent event);
161: }
|