FormField.java 6.99 KB
Newer Older
1 2 3
/**
 * Copyright (C) 2004-2008 Jive Software. All rights reserved.
 *
4 5 6 7 8 9 10 11 12 13 14
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67
 */

package org.jivesoftware.openfire.forms;

import java.util.Iterator;

/**
 * Represents a field of a form. The field could be used to represent a question to complete,
 * a completed question or a data returned from a search. The exact interpretation of the field
 * depends on the context where the field is used.
 *
 * @author Gaston Dombiak
 * @deprecated replaced by {@link org.xmpp.forms.FormField}
 */
@Deprecated
public interface FormField {

    public static final String TYPE_BOOLEAN = "boolean";
    public static final String TYPE_FIXED = "fixed";
    public static final String TYPE_HIDDEN = "hidden";
    public static final String TYPE_JID_MULTI = "jid-multi";
    public static final String TYPE_JID_SINGLE = "jid-single";
    public static final String TYPE_LIST_MULTI = "list-multi";
    public static final String TYPE_LIST_SINGLE = "list-single";
    public static final String TYPE_TEXT_MULTI = "text-multi";
    public static final String TYPE_TEXT_PRIVATE = "text-private";
    public static final String TYPE_TEXT_SINGLE = "text-single";

    /**
     * Adds a default value to the question if the question is part of a form to fill out.
     * Otherwise, adds an answered value to the question.
     *
     * @param value a default value or an answered value of the question.
     */
    public void addValue(String value);

    /**
     * Removes all the values of the field.
     */
    public void clearValues();

    /**
     * Adds an available option to the question that the user has in order to answer
     * the question.
     *
     * @param label a label that represents the option.
     * @param value the value of the option.
     */
    public void addOption(String label, String value);

    /**
     * Sets an indicative of the format for the data to answer. Valid formats are:
     * <ul>
68 69
     * <li>text-single -&gt; single line or word of text
     * <li>text-private -&gt; instead of showing the user what they typed, you show ***** to
70
     * protect it
71 72 73 74 75
     * <li>text-multi -&gt; multiple lines of text entry
     * <li>list-single -&gt; given a list of choices, pick one
     * <li>list-multi -&gt; given a list of choices, pick one or more
     * <li>boolean -&gt; 0 or 1, true or false, yes or no. Default value is 0
     * <li>fixed -&gt; fixed for putting in text to show sections, or just advertise your web
76
     * site in the middle of the form
77 78
     * <li>hidden -&gt; is not given to the user at all, but returned with the questionnaire
     * <li>jid-single -&gt; Jabber ID - choosing a JID from your roster, and entering one based
79
     * on the rules for a JID.
80
     * <li>jid-multi -&gt; multiple entries for JIDs
81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104
     * </ul>
     *
     * @param type an indicative of the format for the data to answer.
     */
    public abstract void setType(String type);

    /**
     * Sets if the question must be answered in order to complete the questionnaire.
     *
     * @param required if the question must be answered in order to complete the questionnaire.
     */
    public abstract void setRequired(boolean required);

    /**
     * Sets the label of the question which should give enough information to the user to
     * fill out the form.
     *
     * @param label the label of the question.
     */
    public abstract void setLabel(String label);

    /**
     * Sets a description that provides extra clarification about the question. This information
     * could be presented to the user either in tool-tip, help button, or as a section of text
105 106
     * before the question.
     * <p>
107
     * If the question is of type FIXED then the description should remain empty.
108
     * </p>
109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139
     *
     * @param description provides extra clarification about the question.
     */
    public abstract void setDescription(String description);

    /**
     * Returns true if the question must be answered in order to complete the questionnaire.
     *
     * @return true if the question must be answered in order to complete the questionnaire.
     */
    public abstract boolean isRequired();

    /**
     * Returns the variable name that the question is filling out.
     *
     * @return the variable name of the question.
     */
    public abstract String getVariable();

    /**
     * Returns an Iterator for the default values of the question if the question is part
     * of a form to fill out. Otherwise, returns an Iterator for the answered values of
     * the question.
     *
     * @return an Iterator for the default values or answered values of the question.
     */
    public abstract Iterator<String> getValues();

    /**
     * Returns an indicative of the format for the data to answer. Valid formats are:
     * <ul>
140 141
     * <li>text-single -&gt; single line or word of text
     * <li>text-private -&gt; instead of showing the user what they typed, you show ***** to
142
     * protect it
143 144 145 146 147
     * <li>text-multi -&gt; multiple lines of text entry
     * <li>list-single -&gt; given a list of choices, pick one
     * <li>list-multi -&gt; given a list of choices, pick one or more
     * <li>boolean -&gt; 0 or 1, true or false, yes or no. Default value is 0
     * <li>fixed -&gt; fixed for putting in text to show sections, or just advertise your web
148
     * site in the middle of the form
149 150
     * <li>hidden -&gt; is not given to the user at all, but returned with the questionnaire
     * <li>jid-single -&gt; Jabber ID - choosing a JID from your roster, and entering one based
151
     * on the rules for a JID.
152
     * <li>jid-multi -&gt; multiple entries for JIDs
153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169
     * </ul>
     *
     * @return format for the data to answer.
     */
    public abstract String getType();

    /**
     * Returns the label of the question which should give enough information to the user to
     * fill out the form.
     *
     * @return label of the question.
     */
    public abstract String getLabel();

    /**
     * Returns a description that provides extra clarification about the question. This information
     * could be presented to the user either in tool-tip, help button, or as a section of text
170 171
     * before the question.
     * <p>
172
     * If the question is of type FIXED then the description should remain empty.
173
     * </p>
174 175 176 177 178
     *
     * @return description that provides extra clarification about the question.
     */
    public abstract String getDescription();
}