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

http://github.com/hudson/hudson · Java · 192 lines · 76 code · 21 blank · 95 comment · 0 complexity · a5e53f1bb0167bc6564c447bb4681b88 MD5 · raw file

  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. */
  24. package hudson.util;
  25. import hudson.model.ModelObject;
  26. import org.kohsuke.stapler.HttpResponse;
  27. import org.kohsuke.stapler.StaplerRequest;
  28. import org.kohsuke.stapler.StaplerResponse;
  29. import org.kohsuke.stapler.export.Exported;
  30. import org.kohsuke.stapler.export.ExportedBean;
  31. import org.kohsuke.stapler.export.Flavor;
  32. import javax.servlet.ServletException;
  33. import java.io.IOException;
  34. import java.util.ArrayList;
  35. import java.util.Arrays;
  36. import java.util.Collection;
  37. /**
  38. * Model object of dynamically filled list box.
  39. *
  40. * <h2>Usage</h2>
  41. * <p>
  42. * The dynamic list box support allows the SELECT element to change its options dynamically
  43. * by using the values given by the server.
  44. *
  45. * <p>
  46. * To use this, HTML needs to declare the SELECT element:
  47. *
  48. * <pre><xmp>
  49. * <select id='foo'>
  50. * <option>Fetching values...</optoin>
  51. * </select>
  52. * </xmp></pre>
  53. *
  54. * <p>
  55. * The SELECT element may have initial option values (in fact in most cases having initial
  56. * values are desirable to avoid the client from submitting the form before the AJAX call
  57. * updates the SELECT element.) It should also have an ID (although if you can get
  58. * to the DOM element by other means, that's fine, too.)
  59. *
  60. * <p>
  61. * Other parts of the HTML can initiate the SELECT element update by using the "updateListBox"
  62. * function, defined in <tt>hudson-behavior.js</tt>. The following example does it
  63. * when the value of the textbox changes:
  64. *
  65. * <pre><xmp>
  66. * <input type="textbox" onchange="updateListBox('list','optionValues?value='+encode(this.value))"/>
  67. * </xmp></pre>
  68. *
  69. * <p>
  70. * The first argument is the SELECT element or the ID of it (see Prototype.js <tt>$(...)</tt> function.)
  71. * The second argument is the URL that returns the options list.
  72. *
  73. * <p>
  74. * The URL usually maps to the <tt>doXXX</tt> method on the server, which uses {@link ListBoxModel}
  75. * for producing option values. See the following example:
  76. *
  77. * <pre>
  78. * public ListBoxModel doOptionValues(@QueryParameter("value") String value) throws IOException, ServletException {
  79. * ListBoxModel m = new ListBoxModel();
  80. * for(int i=0; i<5; i++)
  81. * m.add(value+i,value+i);
  82. * // make the third option selected initially
  83. * m.get(3).selected = true;
  84. * return m;
  85. * }
  86. * </pre>
  87. * @since 1.123
  88. * @author Kohsuke Kawaguchi
  89. */
  90. @ExportedBean
  91. public class ListBoxModel extends ArrayList<ListBoxModel.Option> implements HttpResponse {
  92. @ExportedBean(defaultVisibility=999)
  93. public static final class Option {
  94. /**
  95. * Text to be displayed to user.
  96. */
  97. //TODO: review and check whether we can do it private
  98. @Exported
  99. public String name;
  100. /**
  101. * The value that gets sent to the server when the form is submitted.
  102. */
  103. //TODO: review and check whether we can do it private
  104. @Exported
  105. public String value;
  106. /**
  107. * True to make this item selected.
  108. */
  109. //TODO: review and check whether we can do it private
  110. @Exported
  111. public boolean selected;
  112. public String getName() {
  113. return name;
  114. }
  115. public String getValue() {
  116. return value;
  117. }
  118. public boolean isSelected() {
  119. return selected;
  120. }
  121. public Option(String name, String value) {
  122. this(name,value,false);
  123. }
  124. public Option(String name) {
  125. this(name,name,false);
  126. }
  127. public Option(String name, String value, boolean selected) {
  128. this.name = name;
  129. this.value = value;
  130. this.selected = selected;
  131. }
  132. }
  133. public ListBoxModel(int initialCapacity) {
  134. super(initialCapacity);
  135. }
  136. public ListBoxModel() {
  137. }
  138. public ListBoxModel(Collection<Option> c) {
  139. super(c);
  140. }
  141. public ListBoxModel(Option... data) {
  142. super(Arrays.asList(data));
  143. }
  144. public void add(String displayName, String value) {
  145. add(new Option(displayName,value));
  146. }
  147. public void add(ModelObject usedForDisplayName, String value) {
  148. add(usedForDisplayName.getDisplayName(), value);
  149. }
  150. /**
  151. * A version of the {@link #add(String, String)} method where the display name and the value are the same.
  152. */
  153. public ListBoxModel add(String nameAndValue) {
  154. add(nameAndValue,nameAndValue);
  155. return this;
  156. }
  157. public void writeTo(StaplerRequest req,StaplerResponse rsp) throws IOException, ServletException {
  158. rsp.serveExposedBean(req,this,Flavor.JSON);
  159. }
  160. public void generateResponse(StaplerRequest req, StaplerResponse rsp, Object node) throws IOException, ServletException {
  161. writeTo(req,rsp);
  162. }
  163. /**
  164. * @deprecated
  165. * Exposed for stapler. Not meant for programatic consumption.
  166. */
  167. @Exported
  168. public Option[] values() {
  169. return toArray(new Option[size()]);
  170. }
  171. }