/hudson-core/src/main/java/hudson/util/ListBoxModel.java

  1/*
  2 * The MIT License
  3 * 
  4 * Copyright (c) 2004-2009, Sun Microsystems, Inc., Kohsuke Kawaguchi
  5 * 
  6 * Permission is hereby granted, free of charge, to any person obtaining a copy
  7 * of this software and associated documentation files (the "Software"), to deal
  8 * in the Software without restriction, including without limitation the rights
  9 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 10 * copies of the Software, and to permit persons to whom the Software is
 11 * furnished to do so, subject to the following conditions:
 12 * 
 13 * The above copyright notice and this permission notice shall be included in
 14 * all copies or substantial portions of the Software.
 15 * 
 16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 19 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 21 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 22 * THE SOFTWARE.
 23 */
 24package hudson.util;
 25
 26import hudson.model.ModelObject;
 27import org.kohsuke.stapler.HttpResponse;
 28import org.kohsuke.stapler.StaplerRequest;
 29import org.kohsuke.stapler.StaplerResponse;
 30import org.kohsuke.stapler.export.Exported;
 31import org.kohsuke.stapler.export.ExportedBean;
 32import org.kohsuke.stapler.export.Flavor;
 33
 34import javax.servlet.ServletException;
 35import java.io.IOException;
 36import java.util.ArrayList;
 37import java.util.Arrays;
 38import java.util.Collection;
 39
 40/**
 41 * Model object of dynamically filled list box.
 42 *
 43 * <h2>Usage</h2>
 44 * <p>
 45 * The dynamic list box support allows the SELECT element to change its options dynamically
 46 * by using the values given by the server.
 47 *
 48 * <p>
 49 * To use this, HTML needs to declare the SELECT element:
 50 *
 51 * <pre><xmp>
 52 * <select id='foo'>
 53 *   <option>Fetching values...</optoin>
 54 * </select>
 55 * </xmp></pre>
 56 *
 57 * <p>
 58 * The SELECT element may have initial option values (in fact in most cases having initial
 59 * values are desirable to avoid the client from submitting the form before the AJAX call
 60 * updates the SELECT element.) It should also have an ID (although if you can get
 61 * to the DOM element by other means, that's fine, too.)
 62 *
 63 * <p>
 64 * Other parts of the HTML can initiate the SELECT element update by using the "updateListBox"
 65 * function, defined in <tt>hudson-behavior.js</tt>. The following example does it
 66 * when the value of the textbox changes:
 67 *
 68 * <pre><xmp>
 69 * <input type="textbox" onchange="updateListBox('list','optionValues?value='+encode(this.value))"/>
 70 * </xmp></pre>
 71 *
 72 * <p>
 73 * The first argument is the SELECT element or the ID of it (see Prototype.js <tt>$(...)</tt> function.)
 74 * The second argument is the URL that returns the options list.
 75 *
 76 * <p>
 77 * The URL usually maps to the <tt>doXXX</tt> method on the server, which uses {@link ListBoxModel}
 78 * for producing option values. See the following example:
 79 *
 80 * <pre>
 81 * public ListBoxModel doOptionValues(@QueryParameter("value") String value) throws IOException, ServletException {
 82 *   ListBoxModel m = new ListBoxModel();
 83 *   for(int i=0; i<5; i++)
 84 *     m.add(value+i,value+i);
 85 *   // make the third option selected initially
 86 *   m.get(3).selected = true;
 87 *   return m;
 88 * }
 89 * </pre>
 90 * @since 1.123
 91 * @author Kohsuke Kawaguchi
 92 */
 93@ExportedBean
 94public class ListBoxModel extends ArrayList<ListBoxModel.Option> implements HttpResponse {
 95
 96    @ExportedBean(defaultVisibility=999)
 97    public static final class Option {
 98        /**
 99         * Text to be displayed to user.
100         */
101        //TODO: review and check whether we can do it private
102        @Exported
103        public String name;
104        /**
105         * The value that gets sent to the server when the form is submitted.
106         */
107        //TODO: review and check whether we can do it private
108        @Exported
109        public String value;
110
111        /**
112         * True to make this item selected.
113         */
114        //TODO: review and check whether we can do it private
115        @Exported
116        public boolean selected;
117
118        public String getName() {
119            return name;
120        }
121
122        public String getValue() {
123            return value;
124        }
125
126        public boolean isSelected() {
127            return selected;
128        }
129
130        public Option(String name, String value) {
131            this(name,value,false);
132        }
133
134        public Option(String name) {
135            this(name,name,false);
136        }
137
138        public Option(String name, String value, boolean selected) {
139            this.name = name;
140            this.value = value;
141            this.selected = selected;
142        }
143    }
144
145    public ListBoxModel(int initialCapacity) {
146        super(initialCapacity);
147    }
148
149    public ListBoxModel() {
150    }
151
152    public ListBoxModel(Collection<Option> c) {
153        super(c);
154    }
155
156    public ListBoxModel(Option... data) {
157        super(Arrays.asList(data));
158    }
159
160    public void add(String displayName, String value) {
161        add(new Option(displayName,value));
162    }
163
164    public void add(ModelObject usedForDisplayName, String value) {
165        add(usedForDisplayName.getDisplayName(), value);
166    }
167
168    /**
169     * A version of the {@link #add(String, String)} method where the display name and the value are the same. 
170     */
171    public ListBoxModel add(String nameAndValue) {
172        add(nameAndValue,nameAndValue);
173        return this;
174    }
175
176    public void writeTo(StaplerRequest req,StaplerResponse rsp) throws IOException, ServletException {
177        rsp.serveExposedBean(req,this,Flavor.JSON);
178    }
179
180    public void generateResponse(StaplerRequest req, StaplerResponse rsp, Object node) throws IOException, ServletException {
181        writeTo(req,rsp);
182    }
183
184    /**
185     * @deprecated
186     *      Exposed for stapler. Not meant for programatic consumption.
187     */
188    @Exported
189    public Option[] values() {
190        return toArray(new Option[size()]);
191    }
192}