README

带有 AJAX 数据的 Yii 2.0 下拉小部件

AjaxDropDown 允许您在表单中使用下拉菜单选择一个或多个值。下拉数据通过 AJAX POST 方法发送。

工作原理

该小部件收集 AJAX 数据并将其显示为列表，其中每个元素都可以单击以选择该值作为模型属性。每页的结果数由源控制器动作控制。在第一页之后，只有在单击“下一页”按钮且目标页面尚未收集时，小部件才会收集新页面数据。在任何其他情况下，数据始终存在，浏览已加载的页面不消耗服务器时间。下拉按钮旁边的输入文本字段的目的是在显示小部件之前过滤源数据，但对此没有要求，因此您可以在此处添加任何喜欢的逻辑。

屏幕截图

默认视图

下拉列表可见：（还有“dropup”选项可用）

额外按钮

已选记录

如何安装

更新您的 composer.json 文件

{
  "require": {
    "bizley/ajaxdropdown": "*"
  }
}

并运行 composer update。安装后，在您的视图中添加以下内容（根据需要修改）

<?= \bizley\ajaxdropdown\AjaxDropdown::widget([
  'model' => $model,
  'attribute' => 'attribute',
  'source' => \yii\helpers\Url::to(['source']),
]); ?>

这只是一个基本的小部件配置。您可以在 AjaxDropDown.php 和文档文件中找到所有选项的描述。

完整的小部件结构及其可能的选项

<div id="[WIDGET_ID]" class="ajaxDropDownWidget {mainClass}" {style="{mainStyle}"}>
    <div class="ajaxDropDown {groupClass}" {style="{groupStyle}"}>
        <input {type="text" name="ajaxDropDownInput" value="" class="{inputClass}" {style="{inputStyle}"} inputOptions}>
        <input type="hidden" value="[SELECTED_ID]" name="[ATTRIBUTE_NAME]" class="singleResult">
        <div class="{buttonsClass}" {style="{buttonsStyle}"}>
            {<button type="button" {extraButtonOptions}>{extraButtonLabel}</button>}
            <button data-page="[DATA_PAGE]" data-toggle="dropdown" type="button" class="ajaxDropDownToggle {buttonClass}" {style="{buttonStyle}"}>
                {buttonLabel}
            </button>
            <button type="button" class="ajaxDropDownSingleRemove {removeSingleClass}" {style="{removeSingleStyle}"}>
                {removeSingleLabel}
            </button>
            <ul role="menu" class="ajaxDropDownMenu {resultsClass}" {style="{resultsStyle}"}>
                <li class="dropdown-header {headerClass}" {style="{headerStyle}"}>
                    {pagerBegin}
                        <span class="ajaxDropDownPageNumber">[CURRENT_PAGE_NUMBER]</span>/<span class="ajaxDropDownTotalPages">[TOTAL_PAGES_NUMBER]</span>
                    {pagerEnd}{local.allRecords|local.recordsContaining}
                </li>
                <li class="divider"></li>
                <li class="ajaxDropDownLoading {loadingClass}" {style="{loadingStyle}"}>{progressBar}</li>
                <li class="dropdown-header {errorClass}" {style="{errorStyle}"}>{local.error}</li>
                <li class="dropdown-header {noRecordsClass}" {style="{noRecordsStyle}"}>{local.noRecords}</li>
                <li class="ajaxDropDownPages ajaxDropDownPage[PAGE_NUMBER] ajaxDropDownRecord[RECORD_ID] {recordClass}" {style="{recordStyle}"}>
                    <a data-id="[RECORD_ID]" class="ajaxDropDownResult" href="#">{markBegin}[RECORD_VALUE]{markEnd}</a>
                </li>
                <li class="divider ajaxDropDownInfo"></li>
                <li class="ajaxDropDownInfo {switchClass}" {style="{switchStyle}"}>
                    <a class="ajaxDropDownPrev {previousClass}" {style="{previousStyle}"} href="#">
                        {previousBegin}{local.previous}{previousEnd}
                    </a>
                    <a class="ajaxDropDownNext {nextClass}" {style="{nextStyle}"} href="#">
                        {nextBegin}{local.next}{nextEnd}
                    </a>
                </li>
            </ul>
        </div>
    </div>
    <ul class="ajaxDropDownResults {selectedClass}" {style="{selectedStyle}"}>
        <li class="ajaxDropDownSelected[SELECTED_ID] {resultClass}" {style="{resultStyle}"}>
            <a class="ajaxDropDownRemove {removeClass}" {style="{removeStyle}"} href="#" data-id="[SELECTED_ID]">
                {removeLabel}
            </a>{additionalCode}{markBegin}[SELECTED_VALUE]{markEnd}<input type="hidden" value="[SELECTED_ID]" name="[ATTRIBUTE_NAME]">
        </li>
    </ul>
</div>

花括号中的名称是选项，可以作为小部件参数设置。方括号中的名称是自动设置的小部件数据。

AJAX 数据源

以下是该小部件所需的结构

[
  'data' => [
    [
      'id' => RECORD_ID,
      'mark' => RECORD_EMPHASIS,
      'value' => RECORD_VALUE
    ],
    // ...
  ],
  'page' => CURRENT_PAGE_NUMBER,
  'total' => TOTAL_PAGES_NUMBER
]

其中
RECORD_ID 是记录的唯一标识符，
RECORD_EMPHASIS 是 0|1 标志，表示此记录值是否应被 {markBegin} 和 {markEnd} 包围，
RECORD_VALUE 是记录的实际值，
CURRENT_PAGE_NUMBER 是实际页面编号（从 1 开始），
TOTAL_PAGES_NUMBER 是所有可用页面的数量。

这应该是 JSON 编码的。您可以在文档文件中找到示例。

使用 PHP 预选和验证数据。

如果您想显示一些记录为已选或只想在验证后保留所选数据，则需要准备 'data' 参数，该参数几乎与源数组相同。

[
  [
    'id' => RECORD_ID,
    'mark' => RECORD_EMPHASIS,
    'value' => RECORD_VALUE
  ],
  // ...
]

这次数组不应进行编码。即使在单个结果的情况下也保持此结构。

您可以在文档文件中找到控制器动作的示例。

使用 JavaScript 预选和验证数据。

您可以通过在 AjaxDropDown 对象上触发以下事件来操作所选结果

add
添加一个或多个结果。如果 'singleMode' 为 true，则仅显示最后添加的结果。

jQuery({id or class of AjaxDropDown field}).trigger('add', [result1, result2, ...]);

每个结果数据都是具有 id、value、mark 和 additional 属性的对象（id 是必需的）

{id:1, value:"xxx", mark:0, additional:"xxx"}

removeOne
删除一个或多个结果。

jQuery({id or class of AjaxDropDown field}).trigger('removeOne', [id1, id2, ...]);

removeAll
删除所有结果。

jQuery({id or class of AjaxDropDown field}).trigger('removeAll');

默认情况下，事件（除 'removeAll' 之外）会调用回调方法 onRemove 和 onSelect。您可以通过将 'jsEventsCallback' 设置为 false 来更改它。

可用的额外选项

向上弹出
将 'dropup' => true 设置为触发下拉菜单在按钮上方。

额外按钮
将'extraButtonLabel'和/或'extraButtonOptions'设置为在输入文本字段和下拉触发按钮之间添加额外按钮。

额外代码
如果您想在移除所选结果和所选结果标签之间添加额外代码，请设置'additionalCode'。您可以使用{ID}和{VALUE}标签自动替换这些标签为所选数据。您可以通过在'data'参数中设置'additional'数组元素来只为单行替换此通用选项。

单选模式
如果您只想一次选择一个结果，请将'singleMode'设置为true。此选项将所选结果渲染在过滤字段内部 - 如果您想将其显示在字段下方，请将'singleModeBottom'设置为true。

回调函数
将任何JavaScript函数作为字符串传递给'onSelect'和'onRemove'参数，以在从列表中选择或移除结果时调用它们。在第一种情况下，可用的变量有id（结果ID）、label（其标签）和selection（所有选定结果的列表）。在第二种情况下，只有id和selection可用。

bizley / ajaxdropdown

维护者

详细信息