FormField


1   /**
2    * $RCSfile: FormField.java,v $
3    * $Revision: 1.3 $
4    * $Date: 2004/11/08 01:52:36 $
5    *
6    * Copyright (C) 2004 Jive Software. All rights reserved.
7    *
8    * This software is published under the terms of the GNU Public License (GPL),
9    * a copy of which is included in this distribution.
10   */
11  
12  package org.jivesoftware.messenger.forms;
13  
14  import java.util.Iterator  ;
15  
16  /**
17   * Represents a field of a form. The field could be used to represent a question to complete,
18   * a completed question or a data returned from a search. The exact interpretation of the field
19   * depends on the context where the field is used.
20   *
21   * @author Gaston Dombiak
22   */
23  public interface FormField {
24  
25      public static final String   TYPE_BOOLEAN = "boolean";
26      public static final String   TYPE_FIXED = "fixed";
27      public static final String   TYPE_HIDDEN = "hidden";
28      public static final String   TYPE_JID_MULTI = "jid-multi";
29      public static final String   TYPE_JID_SINGLE = "jid-single";
30      public static final String   TYPE_LIST_MULTI = "list-multi";
31      public static final String   TYPE_LIST_SINGLE = "list-single";
32      public static final String   TYPE_TEXT_MULTI = "text-multi";
33      public static final String   TYPE_TEXT_PRIVATE = "text-private";
34      public static final String   TYPE_TEXT_SINGLE = "text-single";
35  
36      /**
37       * Adds a default value to the question if the question is part of a form to fill out.
38       * Otherwise, adds an answered value to the question.
39       *
40       * @param value a default value or an answered value of the question.
41       */
42      public void addValue(String   value);
43  
44      /**
45       * Removes all the values of the field.
46       */
47      public void clearValues();
48  
49      /**
50       * Adds an available option to the question that the user has in order to answer
51       * the question.
52       *
53       * @param label a label that represents the option.
54       * @param value the value of the option.
55       */
56      public void addOption(String   label, String   value);
57  
58      /**
59       * Sets an indicative of the format for the data to answer. Valid formats are:
60       * <p/>
61       * <ul>
62       * <li>text-single -> single line or word of text
63       * <li>text-private -> instead of showing the user what they typed, you show ***** to
64       * protect it
65       * <li>text-multi -> multiple lines of text entry
66       * <li>list-single -> given a list of choices, pick one
67       * <li>list-multi -> given a list of choices, pick one or more
68       * <li>boolean -> 0 or 1, true or false, yes or no. Default value is 0
69       * <li>fixed -> fixed for putting in text to show sections, or just advertise your web
70       * site in the middle of the form
71       * <li>hidden -> is not given to the user at all, but returned with the questionnaire
72       * <li>jid-single -> Jabber ID - choosing a JID from your roster, and entering one based
73       * on the rules for a JID.
74       * <li>jid-multi -> multiple entries for JIDs
75       * </ul>
76       *
77       * @param type an indicative of the format for the data to answer.
78       */
79      public abstract void setType(String   type);
80  
81      /**
82       * Sets if the question must be answered in order to complete the questionnaire.
83       *
84       * @param required if the question must be answered in order to complete the questionnaire.
85       */
86      public abstract void setRequired(boolean required);
87  
88      /**
89       * Sets the label of the question which should give enough information to the user to
90       * fill out the form.
91       *
92       * @param label the label of the question.
93       */
94      public abstract void setLabel(String   label);
95  
96      /**
97       * Sets a description that provides extra clarification about the question. This information
98       * could be presented to the user either in tool-tip, help button, or as a section of text
99       * before the question.<p>
100      * <p/>
101      * If the question is of type FIXED then the description should remain empty.
102      *
103      * @param description provides extra clarification about the question.
104      */
105     public abstract void setDescription(String   description);
106 
107     /**
108      * Returns true if the question must be answered in order to complete the questionnaire.
109      *
110      * @return true if the question must be answered in order to complete the questionnaire.
111      */
112     public abstract boolean isRequired();
113 
114     /**
115      * Returns the variable name that the question is filling out.
116      *
117      * @return the variable name of the question.
118      */
119     public abstract String   getVariable();
120 
121     /**
122      * Returns an Iterator for the default values of the question if the question is part
123      * of a form to fill out. Otherwise, returns an Iterator for the answered values of
124      * the question.
125      *
126      * @return an Iterator for the default values or answered values of the question.
127      */
128     public abstract Iterator  <String  > getValues();
129 
130     /**
131      * Returns an indicative of the format for the data to answer. Valid formats are:
132      * <p/>
133      * <ul>
134      * <li>text-single -> single line or word of text
135      * <li>text-private -> instead of showing the user what they typed, you show ***** to
136      * protect it
137      * <li>text-multi -> multiple lines of text entry
138      * <li>list-single -> given a list of choices, pick one
139      * <li>list-multi -> given a list of choices, pick one or more
140      * <li>boolean -> 0 or 1, true or false, yes or no. Default value is 0
141      * <li>fixed -> fixed for putting in text to show sections, or just advertise your web
142      * site in the middle of the form
143      * <li>hidden -> is not given to the user at all, but returned with the questionnaire
144      * <li>jid-single -> Jabber ID - choosing a JID from your roster, and entering one based
145      * on the rules for a JID.
146      * <li>jid-multi -> multiple entries for JIDs
147      * </ul>
148      *
149      * @return format for the data to answer.
150      */
151     public abstract String   getType();
152 
153     /**
154      * Returns the label of the question which should give enough information to the user to
155      * fill out the form.
156      *
157      * @return label of the question.
158      */
159     public abstract String   getLabel();
160 
161     /**
162      * Returns a description that provides extra clarification about the question. This information
163      * could be presented to the user either in tool-tip, help button, or as a section of text
164      * before the question.<p>
165      * <p/>
166      * If the question is of type FIXED then the description should remain empty.
167      *
168      * @return description that provides extra clarification about the question.
169      */
170     public abstract String   getDescription();
171 }
172
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags