README

这是一个 Symfony v2.2+ 扩展包，提供了 Bootstrap (v2.x 或 v3.x) Typeahead 组件，用于表单。本扩展包中使用的 Typeahead 组件是原始 Bootstrap v2.3 Typeahead 库的改进版本。

更新：如果您在 composer.json 中指向 dev-master，并且此扩展包停止工作，请将版本改为 "^1.*"，然后运行 composer update lifo/typeahead 以更新您的项目。

如果您使用的是 Bootstrap v2.x，则必须使用此扩展包的 1.* 版本。
如果您使用的是 Bootstrap v3.x，则必须使用此扩展包的 2.* 版本。

注意：此扩展包不使用较新的 Twitter/Typeahead.js JavaScript 库。

增强的 Typeahead 功能

此扩展包对原始 Bootstrap typeahead JavaScript 库进行了一些增强

支持 JSON 对象
缓存结果
延迟 AJAX 请求以减少服务器请求
正确处理鼠标粘贴
包含 AJAX Loader 图标
支持非实体查找
支持通过自定义回调函数进行非 AJAX 加载

截图

此示例显示了一个允许输入单个名称的表单字段。

此示例显示了一个允许输入多个名称的表单字段。点击名称链接可以移除实体。后端实体实际上是一个 ArrayCollection，自动允许从列表中添加/移除实体。

如何安装

注意： 此扩展包需要您的环境中安装 jQuery 和 Bootstrap，但不会直接包含它们。 我建议使用 mopa/bootstrap-bundle，它可以帮助您完成这项工作。

将 lifo/typeahead-bundle 添加到项目 composer.json 文件的 "requires" 部分，您可以通过在项目目录中运行 composer 命令来自动完成此操作
```
composer require lifo/typeahead-bundle
```
或者手动编辑 composer.json 文件
```
{
    // ...
    "require": {
        // ...
        "lifo/typeahead-bundle": "^2.0"
    }
}
```
在项目根目录运行 composer update

更新项目 app/AppKernel.php 文件并将此扩展包添加到 $bundles 数组

$bundles = array(
    // ...
    new Lifo\TypeaheadBundle\LifoTypeaheadBundle(),
);

将 @lifo_typeahead_js 添加到您的 Assetic javascripts 块中。类似于下面的块。您的实际设置可能不同。确保在 jQuery 和 Bootstrap 库之后包含它。
```
{% javascripts filter='?yui_js' output='js/site.js'
    '@lifo_typeahead_js'
%}
    <script src="{{ asset_url }}"></script>
{% endjavascripts %}
```

将 @lifo_typeahead_css 添加到您的 Assetic stylesheets 块中。类似于下面的块。您的实际设置可能不同。

{% stylesheets filter='cssrewrite,?yui_css' output='css/site.css'
    '@lifo_typeahead_css'
-%}
    <link href="{{ asset_url }}" type="text/css" rel="stylesheet" />
{% endstylesheets %}

如果您不使用 Assetic，则必须手动将 JavaScript 和 CSS 文件包含到您的项目中。

<link href="{{ asset('bundles/lifotypeahead/css/typeaheadbundle.css') }}" type="text/css" rel="stylesheet" />
<script src="{{ asset('bundles/lifotypeahead/js/bootstrap-typeahead.js') }}"></script>
<script src="{{ asset('bundles/lifotypeahead/js/typeaheadbundle.js') }}"></script>

如何使用

使用 typeahead 控件非常简单。下面的表格概述了可用的选项

$builder->add('user', 'entity_typeahead', array(
    'class'  => 'MyBundle:User',
    'render' => 'fullname',
    'route'  => 'user_list',
));

选项

class 是你的实体类。如果为 null（或未指定），控制器 AJAX 响应返回的项目不必是实体。如果不为空，则使用该类将项目映射到数据库实体。
source 是要调用的函数名称，该函数将收集要显示的项目。此函数或 route 必须指定。原型为：function(query, process)，其中 process 是你在获取匹配项的列表后应调用的回调函数。它期望一个扁平的字符串数组以渲染下拉菜单 （不是 {id:'...', value:'...'} 对象！）。下面是示例以获取更多信息。
route 是获取实体的路由名称。与路由匹配的控制器将通过 POST 接收以下参数
- query 按查询字符串过滤结果。
- limit 要返回的最大结果数。
- render 配置的 render 名称。这是你在 AJAX 响应中设置 value 属性时应使用的内容。
- property 配置的 property 名称。通常这是 id。这是你在 AJAX 响应中设置 id 属性时应使用的内容。
route_params 要传递给 route 的额外参数。
minLength 触发 AJAX 请求所需的最小字符数。
items 一次最多显示的项目数 （默认：8）
delay 在触发 AJAX 之前延迟的毫秒数 （默认：250）
spinner 用于加载指示器的类字符串 （默认："glyphicon glyphicon-refresh spin"） Font-Awesome 示例："fa fa-refresh fa-spin fa-fw"
multiple 如果为真，则小部件将允许选择多个实体。一次一个。此特殊模式在类型提示小部件下方创建一个无序列表以显示所选实体。
callback 当项目被选择时调用的回调函数（或字符串）。原型：function(text, data)，其中 text 是所选项目的标签，而 data 是服务器返回的 JSON 对象。
render 是要在类型提示输入中显示的实体属性。这用于将初始值渲染到小部件中。一旦用户开始输入，渲染的响应就取决于使用的 route 或 source。

AJAX 响应

控制器应返回以下格式的 JSON 数组。注意：id 和 value 属性是必需的，但你也可以包含其他属性。

[
  { id: 1, value: 'Displayed Text 1' },
  { id: 2, value: 'Displayed Text 2' }
]

注意：如果你使用一个空的 class 选项，那么你的 JavaScript 数组应返回一个 id 和 value 是同一个东西。例如

[
  { id: 'Result 1', value: 'Result 1' },
  { id: 'Result 2', value: 'Result 2' }
]

如果你不返回相同的字符串用于 id 和 value，你将在 UI 中得到令人困惑的结果。

自定义源回调

下面是一个自定义 source 回调的示例。此示例模拟使用 route 选项时的相同结果。

function get_users(query, process) {
    $.post('/mysite/lookup/users', {query: query}, 'json')
        .success(function (data) {
            // must convert the data array into a flat list of strings. 
            // If your lookup function already returns a flat list, then $.map() is not needed.
            process($.map(data, function(a){
                return a.value;
            }));
        });
}

$builder->add('user', 'entity_typeahead', array(
    'class'  => 'MyBundle:User',
    'render' => 'fullname',
    'source' => 'get_users', // a function name in the global javascript "window" object 
));

模板

你的表单模板可能看起来像这样 （上面的截图使用了此模板部分）。 注意： widget_addon 属性是 mopa/bootstrap-bundle 的属性。

{{ form_row(form.name) }}
{{ form_row(form.owner, { attr: { placeholder: 'Search for user ...'}, widget_addon: {type: 'append', 'icon': 'user'}}) }}
{{ form_row(form.users, { attr: { placeholder: 'Add another user ...'}, widget_addon: {type: 'append', 'icon': 'user'}}) }}

说明

此组件以标准的 Symfony 风格渲染其表单元素。你必须覆盖表单块以应用正确的 Bootstrap 样式。我强烈建议使用类似 mopa/bootstrap-bundle 的东西，它可以自动为你覆盖 Symfony 表单模板，并使用正确的 Bootstrap 版本。

lifo / typeahead-bundle

维护者

详细信息