FormField


1   /**
2    * $RCSfile$
3    * $Revision: 2407 $
4    * $Date: 2004-11-02 20:37:00 -0300 (Tue, 02 Nov 2004) $
5    *
6    * Copyright 2003-2004 Jive Software.
7    *
8    * All rights reserved. Licensed under the Apache License, Version 2.0 (the "License");
9    * you may not use this file except in compliance with the License.
10   * You may obtain a copy of the License at
11   *
12   *     http://www.apache.org/licenses/LICENSE-2.0
13   *
14   * Unless required by applicable law or agreed to in writing, software
15   * distributed under the License is distributed on an "AS IS" BASIS,
16   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17   * See the License for the specific language governing permissions and
18   * limitations under the License.
19   */
20  
21  package org.jivesoftware.smackx;
22  
23  import java.util.*;
24  
25  /**
26   * Represents a field of a form. The field could be used to represent a question to complete,
27   * a completed question or a data returned from a search. The exact interpretation of the field
28   * depends on the context where the field is used.
29   * 
30   * @author Gaston Dombiak
31   */
32  public class FormField {
33      public static final String   TYPE_BOOLEAN = "boolean";
34      public static final String   TYPE_FIXED = "fixed";
35      public static final String   TYPE_HIDDEN = "hidden";
36      public static final String   TYPE_JID_MULTI = "jid-multi";
37      public static final String   TYPE_JID_SINGLE = "jid-single";
38      public static final String   TYPE_LIST_MULTI = "list-multi";
39      public static final String   TYPE_LIST_SINGLE = "list-single";
40      public static final String   TYPE_TEXT_MULTI = "text-multi";
41      public static final String   TYPE_TEXT_PRIVATE = "text-private";
42      public static final String   TYPE_TEXT_SINGLE = "text-single";
43  
44      private String   description;
45      private boolean required = false;
46      private String   label;
47      private String   variable;
48      private String   type;
49      private List options = new ArrayList();
50      private List values = new ArrayList();
51  
52      /**
53       * Creates a new FormField with the variable name that uniquely identifies the field 
54       * in the context of the form. 
55       *  
56       * @param variable the variable name of the question.
57       */
58      public FormField(String   variable) {
59          this.variable = variable;
60      }
61      
62      /**
63       * Creates a new FormField of type FIXED. The fields of type FIXED do not define a variable 
64       * name. 
65       *  
66       */
67      public FormField() {
68          this.type = FormField.TYPE_FIXED; 
69      }
70      
71      /**
72       * Returns a description that provides extra clarification about the question. This information
73       * could be presented to the user either in tool-tip, help button, or as a section of text 
74       * before the question.<p> 
75       * 
76       * If the question is of type FIXED then the description should remain empty.
77       * 
78       * @return description that provides extra clarification about the question.
79       */
80      public String   getDescription() {
81          return description;
82      }
83  
84      /**
85       * Returns the label of the question which should give enough information to the user to 
86       * fill out the form.
87       * 
88       * @return label of the question.
89       */
90      public String   getLabel() {
91          return label;
92      }
93  
94      /**
95       * Returns an Iterator for the available options that the user has in order to answer
96       * the question. 
97       * 
98       * @return Iterator for the available options. 
99       */
100     public Iterator getOptions() {
101         synchronized (options) {
102             return Collections.unmodifiableList(new ArrayList(options)).iterator();
103         }
104     }
105 
106     /**
107      * Returns true if the question must be answered in order to complete the questionnaire.
108      * 
109      * @return true if the question must be answered in order to complete the questionnaire.
110      */
111     public boolean isRequired() {
112         return required;
113     }
114 
115     /**
116      * Returns an indicative of the format for the data to answer. Valid formats are:
117      * 
118      * <ul>
119      *  <li>text-single -> single line or word of text
120      *  <li>text-private -> instead of showing the user what they typed, you show ***** to 
121      * protect it
122      *  <li>text-multi -> multiple lines of text entry
123      *  <li>list-single -> given a list of choices, pick one
124      *  <li>list-multi -> given a list of choices, pick one or more
125      *  <li>boolean -> 0 or 1, true or false, yes or no. Default value is 0
126      *  <li>fixed -> fixed for putting in text to show sections, or just advertise your web 
127      * site in the middle of the form
128      *  <li>hidden -> is not given to the user at all, but returned with the questionnaire
129      *  <li>jid-single -> Jabber ID - choosing a JID from your roster, and entering one based 
130      * on the rules for a JID.
131      *  <li>jid-multi -> multiple entries for JIDs
132      * </ul>
133      * 
134      * @return format for the data to answer.
135      */
136     public String   getType() {
137         return type;
138     }
139 
140     /**
141      * Returns an Iterator for the default values of the question if the question is part
142      * of a form to fill out. Otherwise, returns an Iterator for the answered values of 
143      * the question. 
144      * 
145      * @return an Iterator for the default values or answered values of the question. 
146      */
147     public Iterator getValues() {
148         synchronized (values) {
149             return Collections.unmodifiableList(new ArrayList(values)).iterator();
150         }
151     }
152 
153     /**
154      * Returns the variable name that the question is filling out.
155      * 
156      * @return the variable name of the question.
157      */
158     public String   getVariable() {
159         return variable;
160     }
161 
162     /**
163      * Sets a description that provides extra clarification about the question. This information
164      * could be presented to the user either in tool-tip, help button, or as a section of text 
165      * before the question.<p> 
166      * 
167      * If the question is of type FIXED then the description should remain empty.
168      * 
169      * @param description provides extra clarification about the question.
170      */
171     public void setDescription(String   description) {
172         this.description = description;
173     }
174 
175     /**
176      * Sets the label of the question which should give enough information to the user to 
177      * fill out the form.
178      * 
179      * @param label the label of the question.
180      */
181     public void setLabel(String   label) {
182         this.label = label;
183     }
184 
185     /**
186      * Sets if the question must be answered in order to complete the questionnaire.
187      * 
188      * @param required if the question must be answered in order to complete the questionnaire.
189      */
190     public void setRequired(boolean required) {
191         this.required = required;
192     }
193 
194     /**
195      * Sets an indicative of the format for the data to answer. Valid formats are:
196      * 
197      * <ul>
198      *  <li>text-single -> single line or word of text
199      *  <li>text-private -> instead of showing the user what they typed, you show ***** to 
200      * protect it
201      *  <li>text-multi -> multiple lines of text entry
202      *  <li>list-single -> given a list of choices, pick one
203      *  <li>list-multi -> given a list of choices, pick one or more
204      *  <li>boolean -> 0 or 1, true or false, yes or no. Default value is 0
205      *  <li>fixed -> fixed for putting in text to show sections, or just advertise your web 
206      * site in the middle of the form
207      *  <li>hidden -> is not given to the user at all, but returned with the questionnaire
208      *  <li>jid-single -> Jabber ID - choosing a JID from your roster, and entering one based 
209      * on the rules for a JID.
210      *  <li>jid-multi -> multiple entries for JIDs
211      * </ul>
212      * 
213      * @param type an indicative of the format for the data to answer.
214      */
215     public void setType(String   type) {
216         this.type = type;
217     }
218 
219     /**
220      * Adds a default value to the question if the question is part of a form to fill out. 
221      * Otherwise, adds an answered value to the question.
222      *  
223      * @param value a default value or an answered value of the question.
224      */
225     public void addValue(String   value) {
226         synchronized (values) {
227             values.add(value);
228         }
229     }
230 
231     /**
232      * Adds a default values to the question if the question is part of a form to fill out. 
233      * Otherwise, adds an answered values to the question.
234      *  
235      * @param newValues default values or an answered values of the question.
236      */
237     public void addValues(List newValues) {
238         synchronized (values) {
239             values.addAll(newValues);
240         }
241     }
242 
243     /**
244      * Removes all the values of the field.
245      *
246      */
247     protected void resetValues() {
248         synchronized (values) {
249             values.removeAll(new ArrayList(values));
250         }
251     }
252     
253     /**
254      * Adss an available options to the question that the user has in order to answer 
255      * the question.
256      *  
257      * @param option a new available option for the question.
258      */
259     public void addOption(Option option) {
260         synchronized (options) {
261             options.add(option);
262         }
263     }
264 
265     public String   toXML() {
266         StringBuffer   buf = new StringBuffer  ();
267         buf.append("<field");
268         // Add attributes
269         if (getLabel() != null) {
270             buf.append(" label=\"").append(getLabel()).append("\"");
271         }
272         if (getVariable() != null) {
273             buf.append(" var=\"").append(getVariable()).append("\"");
274         }
275         if (getType() != null) {
276             buf.append(" type=\"").append(getType()).append("\"");
277         }
278         buf.append(">");
279         // Add elements
280         if (getDescription() != null) {
281             buf.append("<desc>").append(getDescription()).append("</desc>");
282         }
283         if (isRequired()) {
284             buf.append("<required/>");
285         }
286         // Loop through all the values and append them to the string buffer
287         for (Iterator i = getValues(); i.hasNext();) {
288             buf.append("<value>").append(i.next()).append("</value>");
289         }
290         // Loop through all the values and append them to the string buffer
291         for (Iterator i = getOptions(); i.hasNext();) {
292             buf.append(((Option)i.next()).toXML());
293         }
294         buf.append("</field>");
295         return buf.toString();
296     }
297 
298     /**
299      * 
300      * Represents the available option of a given FormField. 
301      * 
302      * @author Gaston Dombiak
303      */
304     public static class Option {
305         private String   label;
306         private String   value; 
307 
308         public Option(String   value) {
309             this.value = value;
310         }
311 
312         public Option(String   label, String   value) {
313             this.label = label;
314             this.value = value;
315         }
316         
317         /**
318          * Returns the label that represents the option. 
319          * 
320          * @return the label that represents the option.
321          */
322         public String   getLabel() {
323             return label;
324         }
325 
326         /**
327          * Returns the value of the option.
328          * 
329          * @return the value of the option.
330          */
331         public String   getValue() {
332             return value;
333         }
334 
335         public String   toXML() {
336             StringBuffer   buf = new StringBuffer  ();
337             buf.append("<option");
338             // Add attribute
339             if (getLabel() != null) {
340                 buf.append(" label=\"").append(getLabel()).append("\"");
341             }
342             buf.append(">");
343             // Add element
344             buf.append("<value>").append(getValue()).append("</value>");
345 
346             buf.append("</option>");
347             return buf.toString();
348         }
349     }
350 }
351
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags