hudson.util.ListBoxModel Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of hudson-core Show documentation
Contains the core Hudson code and view files to render HTML.
The newest version!
/*******************************************************************************
 *
 * Copyright (c) 2004-2009 Oracle Corporation.
 *
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 * 
 *    Kohsuke Kawaguchi
 *
 *
 *******************************************************************************/ 

package hudson.util;

import hudson.model.ModelObject;
import org.kohsuke.stapler.HttpResponse;
import org.kohsuke.stapler.StaplerRequest;
import org.kohsuke.stapler.StaplerResponse;
import org.kohsuke.stapler.export.Exported;
import org.kohsuke.stapler.export.ExportedBean;
import org.kohsuke.stapler.export.Flavor;

import javax.servlet.ServletException;
import java.io.IOException;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collection;

/**
 * Model object of dynamically filled list box.
 *
 * Usage
  The dynamic list box support allows the SELECT element to
 * change its options dynamically by using the values given by the server.
 *
 * 
 To use this, HTML needs to declare the SELECT element:
 *
 * 

 * <select id='foo'>
 *   <option>Fetching values...</optoin>
 * </select>
 * 
 *
 *  The SELECT element may have initial option values (in fact in most cases
 * having initial values are desirable to avoid the client from submitting the
 * form before the AJAX call updates the SELECT element.) It should also have an
 * ID (although if you can get to the DOM element by other means, that's fine,
 * too.)
 *
 * 
 Other parts of the HTML can initiate the SELECT element update by using
 * the "updateListBox" function, defined in hudson-behavior.js. The
 * following example does it when the value of the textbox changes:
 *
 * 

 * <input type="textbox" onchange="updateListBox('list','optionValues?value='+encode(this.value))"/>
 * 
 *
 *  The first argument is the SELECT element or the ID of it (see
 * Prototype.js $(...) function.) The second argument is the URL that
 * returns the options list.
 *
 * 
 The URL usually maps to the doXXX method on the server, which
 * uses {@link ListBoxModel} for producing option values. See the following
 * example:
 *
 * 
 * public ListBoxModel doOptionValues(
 *
 * @QueryParameter("value") String value) throws IOException, ServletException {
 * ListBoxModel m = new ListBoxModel(); for(int i=0; i<5; i++)
 * m.add(value+i,value+i); // make the third option selected initially
 * m.get(3).selected = true; return m; } 
 * @since 1.123
 * @author Kohsuke Kawaguchi
 */
@ExportedBean
public class ListBoxModel extends ArrayList implements HttpResponse {

    @ExportedBean(defaultVisibility = 999)
    public static final class Option {

        /**
         * Text to be displayed to user.
         */
        //TODO: review and check whether we can do it private
        @Exported
        public String name;
        /**
         * The value that gets sent to the server when the form is submitted.
         */
        //TODO: review and check whether we can do it private
        @Exported
        public String value;
        /**
         * True to make this item selected.
         */
        //TODO: review and check whether we can do it private
        @Exported
        public boolean selected;

        public String getName() {
            return name;
        }

        public String getValue() {
            return value;
        }

        public boolean isSelected() {
            return selected;
        }

        public Option(String name, String value) {
            this(name, value, false);
        }

        public Option(String name) {
            this(name, name, false);
        }

        public Option(String name, String value, boolean selected) {
            this.name = name;
            this.value = value;
            this.selected = selected;
        }
    }

    public ListBoxModel(int initialCapacity) {
        super(initialCapacity);
    }

    public ListBoxModel() {
    }

    public ListBoxModel(Collection