001: /*
002: * Copyright 2004 Outerthought bvba and Schaubroeck nv
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016: package org.outerj.daisy.frontend.editor;
017:
018: import org.apache.cocoon.forms.formmodel.Widget;
019: import org.apache.cocoon.forms.validation.ValidationError;
020: import org.outerj.daisy.repository.Document;
021: import org.outerj.daisy.repository.schema.FieldTypeUse;
022: import org.xml.sax.ContentHandler;
023:
024: import java.util.Locale;
025:
026: /**
027: * Interface for field editors, that is, editors for Daisy document fields
028: * on the "fields" page of the document editor.
029: */
030: public interface FieldEditor {
031: /**
032: * Generate a piece of CForm definition XML, to be embedded in a larger form definition.
033: * This should not geenrate start and end document events.
034: *
035: * <p>The generated form definition XML is inserted within a container widget with
036: * a unique name, so the field editor does not have to bother about producing
037: * a unique name.
038: *
039: * <p>The produced form definition fragment should be 'stable', that is, always
040: * produce the same result for the same FieldTypeUse, and not depend on factors
041: * such as 'time of the day'. This is because the form definitions are cached
042: * and shared between multiple for instances and users.
043: */
044: void generateFormDefinitionFragment(ContentHandler contentHandler,
045: Locale locale) throws Exception;
046:
047: /**
048: * Generate a piece of JX-based CForms template for this field.
049: * This should not generate start and end document events.
050: *
051: * <p>The remark about stability of the {#generateFormDefinitionFragment} also applies here.
052: */
053: void generateFormTemplateFragment(ContentHandler contentHandler,
054: Locale locale) throws Exception;
055:
056: /**
057: * Returns the FieldTypeUse for which this FieldEditor serves.
058: */
059: FieldTypeUse getFieldTypeUse();
060:
061: /**
062: * This method is called to set the validation error in case this field
063: * is required but does not have a value yet.
064: *
065: * <p>Note that the requiredness-validation only happens after the individual
066: * field editors have been successfully validated, so this will not conflict
067: * with any validation the field editor does itself.
068: */
069: void setValidationError(ValidationError error);
070:
071: /**
072: * Returns true if this field has a value (used for field-requiredness validation).
073: */
074: boolean hasValue(Widget widget);
075:
076: /**
077: * Allows to perform initialisation of the field editor.
078: *
079: * @param parentWidget the widget within which the form definition fragment
080: * produced by {@link #generateFormDefinitionFragment}
081: * is inserted. So if you generated a widget with
082: * ID "foo", it can be accessed using parentWidget.getChild("foo").
083: * @param fieldEditorContext provides access to the (current users') Repository object,
084: * among other things.
085: */
086: void init(Widget parentWidget, FieldEditorContext fieldEditorContext);
087:
088: /**
089: * Loads the field value from the document. This method is only called
090: * if the document actually has a value for the field, so it is safe
091: * to assume document.getField() returns non-null when used for the
092: * field type for which this editor serves.
093: */
094: void load(Document document) throws Exception;
095:
096: /**
097: * Stores the field value to the document. If the field has
098: * no value but it is present in the document, it is the
099: * responsibility of the field editor implementation to delete the field
100: * from the document.
101: */
102: void store(Document document) throws Exception;
103: }
|