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         * <p>
070         * <b>Whatever is written to the response reaches the markup as is, without escaping.</b>
071         * Any part of it that comes from user input or other dynamic content must be escaped
072         * before it is written, with {@link org.apache.wicket.util.string.Strings#escapeMarkup(CharSequence) Strings#escapeMarkup(CharSequence)}.
073         * </p>
074         *
075         * @param object
076         *            completion choice object
077         * @param response
078         *            response object
079         * @param criteria
080         *            text entered by user so far
081         */
082        void render(T object, Response response, String criteria);
083
084
085        /**
086         * Render the html header fragment for the completion. Usually the html is written out by
087         * calling {@link Response#write(CharSequence)}.
088         * 
089         * <p>
090         * <b>Whatever is written to the response reaches the markup as is, without escaping.</b>
091         * Any part of it that comes from user input or other dynamic content must be escaped
092         * before it is written, with {@link org.apache.wicket.util.string.Strings#escapeMarkup(CharSequence) Strings#escapeMarkup(CharSequence)}.
093         * </p>
094         *
095         * @param response
096         */
097        void renderHeader(Response response);
098
099        /**
100         * Render the html footer fragment for the completion. Usually the html is written out by
101         * calling {@link Response#write(CharSequence)}.
102         * 
103         * <p>
104         * <b>Whatever is written to the response reaches the markup as is, without escaping.</b>
105         * Any part of it that comes from user input or other dynamic content must be escaped
106         * before it is written, with {@link org.apache.wicket.util.string.Strings#escapeMarkup(CharSequence) Strings#escapeMarkup(CharSequence)}.
107         * </p>
108         *
109         * @param response
110         * @param count
111         *            The number of choices rendered
112         */
113        void renderFooter(Response response, int count);
114
115        /**
116         * Override when needed.
117         */
118        @Override
119        default void detach()
120        {
121        }
122}