Suggest <tc:suggest>

<?xml version="1.0" encoding="UTF-8"?>

<!--
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License 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.
-->

<ui:composition template="/main.xhtml"
                xmlns="http://www.w3.org/1999/xhtml"
                xmlns:tc="http://myfaces.apache.org/tobago/component"
                xmlns:ui="http://java.sun.com/jsf/facelets">
  <ui:param name="title" value="#{demoBundle.suggest} &lt;tc:suggest&gt;"/>
  <p>A <code class="language-markup">&lt;tc:suggest/></code> tag can be added to an inputfield to make
    suggestions based on the already entered text.</p>
  <p>Tag Library Documentation:
    <tc:link label="&lt;tc:suggest/>" image="#{request.contextPath}/image/feather-leaf.png"
             link="#{demoBundle.tagDocUrl}/#{apiController.currentRelease}/tld/tc/suggest.html"/>
    |
    <tc:link label="&lt;tc:in/>" image="#{request.contextPath}/image/feather-leaf.png"
             link="#{demoBundle.tagDocUrl}/#{apiController.currentRelease}/tld/tc/in.html"/>
    |
    <tc:link label="&lt;tc:selectItems/>" image="#{request.contextPath}/image/feather-leaf.png"
             link="#{demoBundle.tagDocUrl}/#{apiController.currentRelease}/tld/tc/selectItems.html"/></p>

  <tc:section label="Basics">
    <p>After you type a character in the textfield, a list of suggestions is shown.</p>
    <p>If <code>update="true"</code> the attribute
      <code>totalCount</code> should be set to improve performance.
      It set the amount of items loaded from the server.</p>
    <p>The suggestion list is calculated in the controller. User the <code>query</code> attribute to pass
      the query string to the controller.</p>
    <pre><code class="language-markup">&lt;tc:in id="inBasic">
  &lt;tc:suggest totalCount="10" query="\#{suggestController.query}">
    &lt;tc:selectItems value="\#{suggestController.solarObjects}" var="name" itemValue="\#{name}"/>
  &lt;/tc:suggest>
&lt;/tc:in></code></pre>
    <tc:in id="inBasic">
      <tc:suggest totalCount="10" query="#{suggestController.query}">
        <tc:selectItems value="#{suggestController.solarObjects}" var="name" itemValue="#{name}"/>
      </tc:suggest>
    </tc:in>
  </tc:section>

  <tc:section label="Advanced">
    <p>This example differs in a few points from the one in the 'Basics' section.
      There are only two suggestions shown to the user, because the
      <code>maximumItems</code> attribute is set to '2'.
      Also you need to type two characters before suggestions are made,
      because of the <code>minimumCharacters</code> attribute which has the value '2'.
      And by setting the <code>delay</code> to '2000', the user have to wait two seconds,
      before the suggestion list is shown.</p>
    <pre><code class="language-markup">&lt;tc:suggest query="\#{suggestController.query}"
            maximumItems="2" minimumCharacters="2" delay="2000">
  &lt;tc:selectItems value="\#{suggestController.solarObjects}" var="name" itemValue="\#{name}"/>
&lt;/tc:suggest></code></pre>
    <tc:in id="inAdvanced" label="Solar Objects">
      <tc:suggest query="#{suggestController.query}"
                  maximumItems="2" minimumCharacters="2" delay="2000">
        <tc:selectItems value="#{suggestController.solarObjects}" var="name" itemValue="#{name}"/>
      </tc:suggest>
    </tc:in>
  </tc:section>

  <tc:section label="Client side">
    <p>Filtering can also be done by the client. For that, set <code>update="false"</code>.</p>
    <p>If client side, you can also use <code class="language-markup">&lt;tc:selectItem/></code>
      instead of <code class="language-markup">&lt;tc:selectItems/></code>.</p>
    <pre><code class="language-markup">&lt;tc:suggest update="false"/></code></pre>
    <tc:in id="inClient" label="Solar Objects">
      <tc:suggest update="false">
        <tc:selectItems value="#{suggestController.allSolarObjects}"/>
      </tc:suggest>
    </tc:in>
  </tc:section>

  <tc:section id="localMenu" label="Render local menu">
    <p>By default, the suggest menu is rendered in the <code>.tobago-page-menuStore</code>
      and positioned relative to the page. The suggest menu will be scrolled with the page.</p>
    <p>Sometimes this behavior causes problems. For example if tc:suggest is used in a fixed header.
      In this case the suggest menu must not scroll with the page. Instead it should stick on the input component.</p>
    <p>To render a suggest menu local on the component, markup <code>localMenu</code> can be used.</p>
    <tc:in id="inLocalMenu" markup="localMenu">
      <tc:suggest totalCount="10" query="#{suggestController.query}">
        <tc:selectItems value="#{suggestController.solarObjects}" var="name" itemValue="#{name}"/>
      </tc:suggest>
    </tc:in>
  </tc:section>
</ui:composition>