FormField


1   /**
2    * $RCSfile: FormField.java,v $
3    * $Revision: 1.4 $
4    * $Date: 2005/06/04 05:33:07 $
5    *
6    * Copyright 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.xmpp.forms;
22  
23  import org.dom4j.Element;
24  
25  import java.util.ArrayList  ;
26  import java.util.Iterator  ;
27  import java.util.List  ;
28  
29  /**
30   * Represents a field of a form. The field could be used to represent a question to complete,
31   * a completed question or a data returned from a search. The exact interpretation of the field
32   * depends on the context where the field is used.
33   *
34   * @author Gaston Dombiak
35   */
36  public class FormField {
37  
38      private Element element;
39  
40      FormField(Element element) {
41          this.element = element;
42      }
43  
44      /**
45       * Adds a default value to the question if the question is part of a form to fill out.
46       * Otherwise, adds an answered value to the question.
47       *
48       * @param value a default value or an answered value of the question.
49       */
50      public void addValue(Object   value) {
51          element.addElement("value").setText(DataForm.encode(value));
52      }
53  
54      /**
55       * Removes all the values of the field.
56       */
57      public void clearValues() {
58          for (Iterator   it = element.elementIterator("value"); it.hasNext();) {
59              it.next();
60              it.remove();
61          }
62      }
63  
64      /**
65       * Adds an available option to the question that the user has in order to answer
66       * the question.
67       *
68       * @param label a label that represents the option.
69       * @param value the value of the option.
70       */
71      public void addOption(String   label, String   value) {
72          Element option = element.addElement("option");
73          option.addAttribute("label", label);
74          option.addElement("value").setText(value);
75      }
76  
77      /**
78       * Returns the available options to answer for this question. The returned options cannot
79       * be modified but they will be updated if the underlying DOM object gets updated.
80       *
81       * @return the available options to answer for this question.
82       */
83      public List  <Option> getOptions() {
84          List  <Option> answer = new ArrayList  <Option>();
85          for (Iterator   it = element.elementIterator("option"); it.hasNext();) {
86              answer.add(new Option((Element) it.next()));
87          }
88          return answer;
89      }
90  
91      /**
92       * Sets an indicative of the format for the data to answer. Valid formats are:
93       * <p/>
94       * <ul>
95       * <li>text-single -> single line or word of text
96       * <li>text-private -> instead of showing the user what they typed, you show ***** to
97       * protect it
98       * <li>text-multi -> multiple lines of text entry
99       * <li>list-single -> given a list of choices, pick one
100      * <li>list-multi -> given a list of choices, pick one or more
101      * <li>boolean -> 0 or 1, true or false, yes or no. Default value is 0
102      * <li>fixed -> fixed for putting in text to show sections, or just advertise your web
103      * site in the middle of the form
104      * <li>hidden -> is not given to the user at all, but returned with the questionnaire
105      * <li>jid-single -> Jabber ID - choosing a JID from your roster, and entering one based
106      * on the rules for a JID.
107      * <li>jid-multi -> multiple entries for JIDs
108      * </ul>
109      *
110      * @param type an indicative of the format for the data to answer.
111      */
112     public void setType(Type type) {
113         element.addAttribute("type", type==null?null:type.toXMPP());
114     }
115 
116     /**
117      * Sets the attribute that uniquely identifies the field in the context of the form. If the
118      * field is of type "fixed" then the variable is optional.
119      *
120      * @param var the unique identifier of the field in the context of the form.
121      */
122     public void setVariable(String   var) {
123         element.addAttribute("var", var);
124     }
125 
126     /**
127      * Sets the label of the question which should give enough information to the user to
128      * fill out the form.
129      *
130      * @param label the label of the question.
131      */
132     public void setLabel(String   label) {
133         element.addAttribute("label", label);
134     }
135 
136     /**
137      * Sets if the question must be answered in order to complete the questionnaire.
138      *
139      * @param required if the question must be answered in order to complete the questionnaire.
140      */
141     public void setRequired(boolean required) {
142         // Remove an existing desc element.
143         if (element.element("required") != null) {
144             element.remove(element.element("required"));
145         }
146         if (required) {
147             element.addElement("required");
148         }
149     }
150 
151     /**
152      * Sets a description that provides extra clarification about the question. This information
153      * could be presented to the user either in tool-tip, help button, or as a section of text
154      * before the question.<p>
155      * <p/>
156      * If the question is of type FIXED then the description should remain empty.
157      *
158      * @param description provides extra clarification about the question.
159      */
160     public void setDescription(String   description) {
161         // Remove an existing desc element.
162         if (element.element("desc") != null) {
163             element.remove(element.element("desc"));
164         }
165         element.addElement("desc").setText(description);
166     }
167 
168     /**
169      * Returns true if the question must be answered in order to complete the questionnaire.
170      *
171      * @return true if the question must be answered in order to complete the questionnaire.
172      */
173     public boolean isRequired() {
174         return element.element("required") != null;
175     }
176 
177     /**
178      * Returns the variable name that the question is filling out.
179      *
180      * @return the variable name of the question.
181      */
182     public String   getVariable() {
183         return element.attributeValue("var");
184     }
185 
186     /**
187      * Returns an Iterator for the default values of the question if the question is part
188      * of a form to fill out. Otherwise, returns an Iterator for the answered values of
189      * the question.
190      *
191      * @return an Iterator for the default values or answered values of the question.
192      */
193     public List  <String  > getValues() {
194         List  <String  > answer = new ArrayList  <String  >();
195         for (Iterator   it = element.elementIterator("value"); it.hasNext();) {
196             answer.add(((Element) it.next()).getTextTrim());
197         }
198         return answer;
199     }
200 
201     /**
202      * Returns an indicative of the format for the data to answer. Valid formats are:
203      * <p/>
204      * <ul>
205      * <li>text-single -> single line or word of text
206      * <li>text-private -> instead of showing the user what they typed, you show ***** to
207      * protect it
208      * <li>text-multi -> multiple lines of text entry
209      * <li>list-single -> given a list of choices, pick one
210      * <li>list-multi -> given a list of choices, pick one or more
211      * <li>boolean -> 0 or 1, true or false, yes or no. Default value is 0
212      * <li>fixed -> fixed for putting in text to show sections, or just advertise your web
213      * site in the middle of the form
214      * <li>hidden -> is not given to the user at all, but returned with the questionnaire
215      * <li>jid-single -> Jabber ID - choosing a JID from your roster, and entering one based
216      * on the rules for a JID.
217      * <li>jid-multi -> multiple entries for JIDs
218      * </ul>
219      *
220      * @return format for the data to answer.
221      */
222     public Type getType() {
223         String   type = element.attributeValue("type");
224         if (type != null) {
225             Type.fromXMPP(type);
226         }
227         return null;
228     }
229 
230     /**
231      * Returns the label of the question which should give enough information to the user to
232      * fill out the form.
233      *
234      * @return label of the question.
235      */
236     public String   getLabel() {
237         return element.attributeValue("label");
238     }
239 
240     /**
241      * Returns a description that provides extra clarification about the question. This information
242      * could be presented to the user either in tool-tip, help button, or as a section of text
243      * before the question.<p>
244      * <p/>
245      * If the question is of type FIXED then the description should remain empty.
246      *
247      * @return description that provides extra clarification about the question.
248      */
249     public String   getDescription() {
250         return element.elementTextTrim("desc");
251     }
252 
253     /**
254      * Represents the available option of a given FormField.
255      *
256      * @author Gaston Dombiak
257      */
258     public static class Option {
259         private Element element;
260 
261         private Option(Element element) {
262             this.element = element;
263         }
264 
265         /**
266          * Returns the label that represents the option.
267          *
268          * @return the label that represents the option.
269          */
270         public String   getLabel() {
271             return element.attributeValue("label");
272         }
273 
274         /**
275          * Returns the value of the option.
276          *
277          * @return the value of the option.
278          */
279         public String   getValue() {
280             return element.elementTextTrim("value");
281         }
282     }
283 
284     /**
285      * Type-safe enumeration to represent the field type of the Data forms.<p>
286      *
287      * Implementation note: XMPP error conditions use "-" characters in
288      * their names such as "jid-multi". Because "-" characters are not valid
289      * identifier parts in Java, they have been converted to "_" characters in
290      * the  enumeration names, such as <tt>jid_multi</tt>. The {@link #toXMPP()} and
291      * {@link #fromXMPP(String)} methods can be used to convert between the
292      * enumertation values and Type code strings.
293      */
294     public enum Type {
295         /**
296          * The field enables an entity to gather or provide an either-or choice between two
297          * options. The allowable values are 1 for yes/true/assent and 0 for no/false/decline.
298          * The default value is 0.
299          */
300         boolean_type("boolean"),
301 
302         /**
303          * The field is intended for data description (e.g., human-readable text such as
304          * "section" headers) rather than data gathering or provision. The <value/> child
305          * SHOULD NOT contain newlines (the \n and \r characters); instead an application
306          * SHOULD generate multiple fixed fields, each with one <value/> child.
307          */
308         fixed("fixed"),
309 
310         /**
311          * The field is not shown to the entity providing information, but instead is
312          * returned with the form.
313          */
314         hidden("hidden"),
315 
316         /**
317          * The field enables an entity to gather or provide multiple Jabber IDs.
318          */
319         jid_multi("jid-multi"),
320 
321         /**
322          * The field enables an entity to gather or provide multiple Jabber IDs.
323          */
324         jid_single("jid-single"),
325 
326         /**
327          * The field enables an entity to gather or provide one or more options from
328          * among many.
329          */
330         list_multi("list-multi"),
331 
332         /**
333          * The field enables an entity to gather or provide one option from among many.
334          */
335         list_single("list-single"),
336 
337         /**
338          * The field enables an entity to gather or provide multiple lines of text.
339          */
340         text_multi("text-multi"),
341 
342         /**
343          * The field enables an entity to gather or provide a single line or word of text,
344          * which shall be obscured in an interface (e.g., *****).
345          */
346         text_private("text-private"),
347 
348         /**
349          * The field enables an entity to gather or provide a single line or word of text,
350          * which may be shown in an interface. This field type is the default and MUST be
351          * assumed if an entity receives a field type it does not understand.
352          */
353         text_single("text-single");
354 
355         /**
356          * Converts a String value into its Type representation.
357          *
358          * @param type the String value.
359          * @return the type corresponding to the String.
360          */
361         public static Type fromXMPP(String   type) {
362             if (type == null) {
363                 throw new NullPointerException  ();
364             }
365             type = type.toLowerCase();
366             if (boolean_type.toXMPP().equals(type)) {
367                 return boolean_type;
368             }
369             else if (fixed.toXMPP().equals(type)) {
370                 return fixed;
371             }
372             else if (hidden.toXMPP().equals(type)) {
373                 return hidden;
374             }
375             else if (jid_multi.toXMPP().equals(type)) {
376                 return jid_multi;
377             }
378             else if (jid_single.toXMPP().equals(type)) {
379                 return jid_single;
380             }
381             else if (list_multi.toXMPP().equals(type)) {
382                 return list_multi;
383             }
384             else if (list_single.toXMPP().equals(type)) {
385                 return list_single;
386             }
387             else if (text_multi.toXMPP().equals(type)) {
388                 return text_multi;
389             }
390             else if (text_private.toXMPP().equals(type)) {
391                 return text_private;
392             }
393             else if (text_single.toXMPP().equals(type)) {
394                 return text_single;
395             }
396             else {
397                 throw new IllegalArgumentException  ("Type invalid:" + type);
398             }
399         }
400 
401         private String   value;
402 
403         private Type(String   value) {
404             this.value = value;
405         }
406 
407         /**
408          * Returns the Field Type as a valid Field Type code string.
409          *
410          * @return the Field Type value.
411          */
412         public String   toXMPP() {
413             return value;
414         }
415 
416     }
417 }
418
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags