001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.wicket.markup.html.form;
018
019import java.util.List;
020
021import org.apache.wicket.model.IDetachable;
022import org.apache.wicket.model.IModel;
023
024/**
025 * Renders one choice. Separates the 'id' values used for internal representation from 'display
026 * values' which are the values shown to the user of components that use this renderer.
027 *
028 * @author jcompagner
029 *
030 * @param <T>
031 *            The model object type
032 */
033public interface IChoiceRenderer<T> extends IDetachable
034{
035        /**
036         * Get the value for displaying to an end user.
037         *
038         * @param object
039         *            the actual object
040         * @return the value meant for displaying to an end user
041         */
042        Object getDisplayValue(T object);
043
044        /**
045         * This method is called to get the id value of an object (used as the value attribute of a
046         * choice element) The id can be extracted from the object like a primary key, or if the list is
047         * stable you could just return a toString of the index.
048         * <p>
049         * Note that the given index can be {@code -1} if the object in question is not contained in the
050         * available choices.
051         *
052         * @param object
053         *            The object for which the id should be generated
054         * @param index
055         *            The index of the object in the choices list.
056         * @return String
057         */
058        default String getIdValue(T object, int index) {
059                return Integer.toString(index);
060        }
061
062        /**
063         * This method is called to get an object back from its id representation.
064         *
065         * The {@code id} may be used to find/load the object in a more efficient way
066         * than loading all {@code choices} and find the one with the same id in the list
067         *
068         * @param id
069         *          The id representation of the object
070         * @param choices
071         *          The list of all rendered choices
072         * @return A choice from the list that has this {@code id}
073         */
074        default T getObject(String id, IModel<? extends List<? extends T>> choices)
075        {
076                List<? extends T> _choices = choices.getObject();
077                for (int index = 0; index < _choices.size(); index++)
078                {
079                        // Get next choice
080                        final T choice = _choices.get(index);
081                        if (getIdValue(choice, index).equals(id))
082                        {
083                                return choice;
084                        }
085                }
086                return null;
087        }
088
089        /**
090         * Override when needed.
091         */
092        @Override
093        default void detach()
094        {
095        }
096        
097}