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.extensions.ajax.markup.html.autocomplete;
018
019import org.apache.wicket.model.IDetachable;
020import org.apache.wicket.request.Response;
021
022/**
023 * A renderer used to generate html output for the {@link AutoCompleteBehavior}.
024 * <p>
025 * Helper implementations of this interface may abstract the implementation specific details. Direct
026 * implementations of this interface should only be used when total control is required.
027 * <p>
028 * The autocompletion value is supplied via an attribute on the first html element named
029 * <code>textvalue</code>, if no attribute is found the innerHtml property of the first element will
030 * be used instead.
031 * 
032 * For example:
033 * 
034 * <pre>
035 * new IAutoCompleteRenderer() {
036 *     void renderHead(Response r) { r.write(&quot;
037 * &lt;ul&gt;
038 * &quot;); }
039 *     
040 *     void render(Object o, Response r) {
041 *        // notice the textvalue attribute we define for li element
042 *        r.write(&quot;
043 * &lt;li textvalue=\""+o.toString()+"\"&gt;
044 * &lt;i&gt;&quot;+o.toString()+&quot;&lt;/i&gt;
045 * &lt;/li&gt;
046 * &quot;;
047 *     }
048 *     
049 *     void renderFooter(Response r) { r.write(&quot;
050 * &lt;/ul&gt;
051 * &quot;); }
052 * }
053 * </pre>
054 * 
055 * @param <T>
056 * 
057 * @since 1.2
058 * 
059 * @author Igor Vaynberg (ivaynberg)
060 * @author Janne Hietam&auml;ki (jannehietamaki)
061 * 
062 */
063public interface IAutoCompleteRenderer<T> extends IDetachable
064{
065        /**
066         * Render the html fragment for the given completion object. Usually the html is written out by
067         * calling {@link Response#write(CharSequence)}.
068         * 
069         * @param object
070         *            completion choice object
071         * @param response
072         *            response object
073         * @param criteria
074         *            text entered by user so far
075         */
076        void render(T object, Response response, String criteria);
077
078
079        /**
080         * Render the html header fragment for the completion. Usually the html is written out by
081         * calling {@link Response#write(CharSequence)}.
082         * 
083         * @param response
084         */
085        void renderHeader(Response response);
086
087        /**
088         * Render the html footer fragment for the completion. Usually the html is written out by
089         * calling {@link Response#write(CharSequence)}.
090         * 
091         * @param response
092         * @param count
093         *            The number of choices rendered
094         */
095        void renderFooter(Response response, int count);
096
097        /**
098         * Override when needed.
099         */
100        @Override
101        default void detach()
102        {
103        }
104}