com.vaynberg.wicket.select2.ChoiceProvider Maven / Gradle / Ivy

Go to download
/*
 * Copyright 2012 Igor Vaynberg
 * 
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this work except in compliance with
 * the License. You may obtain a copy of the License in the LICENSE file, or 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.
 */
package com.vaynberg.wicket.select2;

import java.util.Collection;

import org.apache.wicket.model.IDetachable;
import org.json.JSONException;
import org.json.JSONWriter;

/**
 * 
 * Acts as a bridge between Select2 components and the application's domain model.
 * 

 * The two important services provided by implementations are:
 * 

 * Feeding choices, represented by the application's domain objects, to Select2 components
 * Transcoding said choices to and from Json so they can consumed by Select2
 * 
 * 
 * For the most common usecase where each choice is rendered as a text string see {@link TextChoiceProvider}.
 *
 * @param  type of choice object
 * @author igor
 */
public abstract class ChoiceProvider implements IDetachable {

    /**
     * Queries application for choices that match the search {@code term} and adds them to the {@code response}
     *
     * @param term     search term
     * @param page     requested search term results page
     * @param response aggregate for matching choices as well as other response options
     */
    public abstract void query(String term, int page, Response response);

    /**
     * Converts the specified choice to Json.
     * 

     * 

     * At the very least each choice should contain an {@code id} attribute. If no custom rendering function is
     * specified, the {@code text} attribute should also be provided
     * 
     * 
     * 

     * Example: If mapping a User {Long id, String name} using default rendering the code should look like this:
     * 

     * 
     * toJson(User choice, JSONWriter writer) {
     *     writer.key("id").value(choice.getId()).key("text").value(choice.getName());
     * }
     * 
     * 
     * 
     *
     * @param choice choice to convert
     * @param writer Json writer that should be used to covnert the choice
     * @throws JSONException
     */
    public abstract void toJson(T choice, JSONWriter writer) throws JSONException;

    /**
     * Converts a list of choice ids back into application's choice objects. When the choice provider is attached to a
     * single-select component the {@code ids} collection will contain exactly one id, and a collection containing
     * exactly one choice should be returned.
     *
     * @param ids collection containing choice ids
     * @return collection containing application choice objects
     */
    public abstract Collection toChoices(Collection ids);

    @Override
    public void detach() {}
}