README

安装

步骤 1: 下载扩展包

$ composer require everlutionsk/ajaxcom-bundle

步骤 2: 启用扩展包

<?php
// app/AppKernel.php

// ...
class AppKernel extends Kernel
{
    public function registerBundles()
    {
        $bundles = array(
            // ...

            new Everlution\AjaxcomBundle\EverlutionAjaxcomBundle(),
        );

        // ...
    }

    // ...
}

步骤 3: 在您的 TWIG 布局中包含 Ajaxcom 库的 JavaScript

使用 npm 安装 @everlutionsk/ajaxcom-js 并将 ajaxcom.js 包含到您的 TWIG 布局中

<script type="text/javascript" src="{{ asset('build/ajaxcom.js') }}"></script>

最后，您需要在 TWIG 布局中提供一些 JavaScript 处理程序 - 请参考 @everlutionsk/ajaxcom-js 的文档。

配置

如果您想使用扩展包提供的闪存消息模板，则无需进行任何配置。

# all configuration is optional - following values are default
everlution_ajaxcom:
    flash_template: @EverlutionAjaxcom/flash_message.html.twig
    flash_block_id: flash_message
    persistent_class: ajaxcom-persistent
    blocks_to_render: # default value is empty array - when you provide this value, AjaxcomBundle will automatically render these blocks within each AJAX request
          - id: 'content'
          - id: 'navigation'
          - id: 'flash_message'
            refresh: true

默认情况下，AjaxcomBundle 会忽略空块，并且如果开发者要求渲染空块，我们将过滤掉这些实例。如果您想要重新渲染空内容的块，您应该将 refresh 标志设置为 true，就像上面示例中那样。

当您想要从控制器设置刷新标志时，您需要首先添加该块，然后刷新它

<?php

public function exampleAction()
{
    $this->addAjaxBlock('example');
    $this->refreshAjaxBlock('example');
    
    return $this->render('some/template');
}

该扩展包与 Bootstrap 3+ CSS 框架配合工作效果最佳。

使用

从 Everlution\AjaxcomBundle\Controller\Controller 扩展您的控制器，或使用 Everlution\AjaxcomBundle\Controller\AjaxcomTrait 特性与您的控制器结合以获得 Ajaxcom 功能。

默认情况下，ajaxcom-js 库将处理所有除了带有 target="_blank" 的链接点击和所有表单提交之外的所有链接点击。如果您需要更改选择器或您想要对哪些链接由 ajaxcom-js 处理以及哪些不被处理进行控制，您可以在 ajaxcom-js 初始化中覆盖默认选择器。请参阅 @everlutionsk/ajaxcom-js 的 文档。

示例

<a href="https://www.google.com">External link</a> <!-- won't be handled by Ajaxcom -->
<a href="{{ path('remove_user') }}">Remove user</a> <!-- will be handled by Ajaxcom -->

以下方法可以组合使用 - 例如，您可以在一个请求中渲染多个块、移除多个块，并添加任意数量的 JavaScript 回调。

public function render($view, array $parameters = array(), Response $response = null)

Everlution 的 Ajaxcom 扩展包扩展了标准的 Symfony 的 render() 方法，因此您可以在不修改代码库的情况下将 Ajaxcom 集成到项目中。

render() 方法会自动判断是响应 Ajax 还是非 Ajax 调用，因此您不需要在应用程序中处理特殊场景。

Ajaxcom 扩展包会自动处理 Symfony 控制器的 Ajax 和非 Ajax 请求，因此您不需要重复编写代码 - 扩展包始终调用相同的操作。

在您的标准 Symfony 控制器的操作中，您将只有非常小的开销，这将为处理 Ajax 请求设置操作的行为。这些开销方法将在接下来的几个部分中解释。

renderAjaxBlock(string $id)

为了在页面上动态渲染单个块，您需要满足以下两个条件

1. 您想要渲染的块被包裹在 TWIG 的 block 中
2. TWIG 的 block 被包裹在一个具有相同名称的 ID 的 DOM 元素中

默认情况下，TWIG 不支持在块名称中使用连字符，因此如果您需要在 ID 中使用连字符，我们将自动将连字符转换为下划线。因此，您可以在 ID 中使用连字符，结合具有相同名称的 TWIG 块 - 您只需将连字符替换为下划线即可。例如：`id='custom-block'` 和 `{% block custom_block %}` 将由 AjaxcomBundle 自动匹配。

示例

Twig

<div id="list">
    {% block list %}
        // this is the HTML which will be replaced/removed ...
    {% endblock %}
</div>

PHP

$this->renderAjaxBlock("list");

在控制器的操作中，只需调用 renderAjaxBlock，您需要提供块 ID（例如 TWIG 块名称）。

当您的操作通过 Ajax 请求调用时，Ajaxcom 库的 JSON 响应将包含有关应使用哪个 HTML 重新渲染哪个块的信息。

removeAjaxBlock(string $selector)

如果您想动态地删除某些 DOM 元素，例如在从表中删除某一行后，可以使用 removeAjaxBlock() 方法，其中您只需提供要删除的元素的 CSS 选择器。

示例

Twig

<table>
    <tbody>
        <tr id="row-1"><td>1.</td></tr>
        <tr id="row-2"><td>2.</td></tr>
        <tr id="row-3"><td>3.</td></tr>
    </tbody>
</table>

PHP

$this->removeBlock("#row-2");

// OR you can use any CSS selector

$this->removeBlock("tr:nth-child(2)");

上面的代码（两个示例）将在操作调用后从表中删除中间行。

结果

<table>
    <tbody>
        <tr id="row-1"><td>1.</td></tr>
        <!-- the #row-2 has been removed -->
        <tr id="row-3"><td>3.</td></tr>
    </tbody>
</table>

addCallback(string $function, array $parameters = [])

您可以添加尽可能多的 JavaScript 回调。`addCallback()` 的第一个参数是要调用的函数的名称，第二个是作为对象传递给函数的参数数组。

示例

PHP

$this->addCallback('Table.init', ['some' => 'data', 'other' => ['data', 'etc']]);

var Table = function() {
    return {
        init: function(data){
            var some = data.some;
            var otherArray = data.other;
            
            // initialize table with provided data
        };
    }
};

您不一定需要使用此函数

如果您以以下方式编写 JavaScript，实际上您不需要使用此函数

// additional.js
var App = {
    additional: function () {
        // some additional functionality
        console.log('executing App.additional');
    },
    // more functions within App namespace
}

App.additional();

App.additional() 将在浏览器每次下载 additional.js 文件时执行 - 不论请求是否由 Ajaxcom 处理。您只需确保通过 Ajaxcom 将 `<script src="additional.js"></script>` 添加到 DOM 中即可。

AjaxcomBundle 将自动将 `javascripts` 块内的所有脚本添加到您的页面中（它们将在您的代码中最后一个 `<script>` 之后插入）。

replaceClass()

您可以通过调用 replaceClass() 并传递两个参数（CSS 选择器和要替换的类）来轻松地在任何 DOM 对象中替换类。

doNotChangeUrl()

您可以通过调用 doNotChangeUrl() 来轻松避免替换目标页面的 URL。

Flash 消息

Flash 消息由 Ajaxcom Bundle 自动处理。当请求通过 Ajax 调用时，会话包中的闪存消息将自动渲染。

您只需在 twig 布局中包含提供的 twig 模板即可。

{% include "@EverlutionAjaxcom/flash_message.html.twig" %}

当您从控制器调用 addFlash() 时，请使用 Everlution\AjaxcomBundle\Flash 来提供闪存消息类型。

$this->addFlash(Everlution\AjaxcomBundle\Flash::SUCCESS, 'Your request has been successfully handled by Ajaxcom bundle');

// you can use following constants:
// Everlution\AjaxcomBundle\Flash::SUCCESS
// Everlution\AjaxcomBundle\Flash::ERROR
// Everlution\AjaxcomBundle\Flash::WARNING
// Everlution\AjaxcomBundle\Flash::INFO

Ajaxcom 通过发送表单

默认情况下，所有表单都由 `ajaxcom-js` 处理。您可以通过在初始化 `ajaxcom-js` 时覆盖默认表单选择器来更改此行为。请参阅 @everlutionsk/ajaxcom-js 文档。

重用数据源

为了在多个标签之间重用数据源，您可以轻松地通过扩展我们的 `BaseDataSource` 创建 Twig 函数。

只需在您的 services.yml 中添加以下语句

    AppBundle\DataProvider\:
        resource: '../../src/AppBundle/DataProvider'
        tags: ['twig.extension']

您可以指定项目中的任何文件夹。在此示例中，我们选择了 `AppBundle\DataProvider` 命名空间。

此命名空间中每个扩展 `Everlution\AjaxcomBundle\DataSource\BaseDataSource` 的类都会通过反射扫描具有后缀 `Provider` 的公共方法，并从中创建简单的 Twig 函数。让我们看看示例

// AppBundle\DataProvider\Example.php

// simple function which returns static array
public function navigationProvider() {
    return [ 
        // some data... 
    ];
}

// you can use parametrical functions and injected services as well
public function userProfileProvider(int $id) {
    return $this->someService->getData($id);
}

创建此类后，您可以在 twig 中调用该函数

{{ dump(navigation()); }} {# will dump static array #}

{% for item in userProfile(2) %}
   {{ dump(item) }}
{% endfor %}

最佳实践

如果您想无缝使用AjaxcomBundle，应将 @EverlutionAjaxcom\layout_bootstrap_4.html.twig 复制到您的项目（例如：AppBundle）中，并根据需要对其进行修改。

这样，AjaxcomBundle 将为您处理诸如替换JavaScript、样式表和元标签等任务。

使用JS、CSS、Meta和标题的自动替换

当您使用 @EverlutionAjaxcom\layout_bootstrap_4.html.twig 中的块时，您应该已经设置好了。

当您决定手动设置布局时，以下部分将帮助您了解自动替换的工作方式。

替换JavaScript

1. 应包含 class='ajaxcom-persistent'（或您在包配置中设置的任何内容）的所有需要在每个页面上包含的JavaScript。
2. 您正在扩展的主布局必须包含 {% block javascripts %}{% endblock %}
3. 当您扩展主布局并重写 javascripts 块时，AjaxcomBundle 将自动为您加载此块中的脚本。

替换样式表

1. 与JavaScript相同，需要在每个页面上包含的所有样式表都必须包含 class='ajaxcom-persistent'（或您在包配置中设置的任何内容）。
2. 您正在扩展的主布局必须包含 {% block stylesheets %}{% endblock %}
3. 当您扩展主布局并重写 stylesheets 块时，AjaxcomBundle 将自动为您加载此块中的样式。

替换元标签和标题

1. 需要在每个页面上存在的所有元标签都必须包含 class='ajaxcom-persistent'（或您在包配置中设置的任何内容）。
2. 您正在扩展的主布局必须包含 {% block metatags %}{% endblock %}
3. 当您扩展主布局并重写 metatags 块时，AjaxcomBundle 将自动为您加载此块中的元标签。
4. 如果您想更改页面布局的 title，您的布局必须包含 <title>{% block title %}{% endblock %}</title>，并且您需要在扩展主模板的模板中重写 title 块。

待办事项

• 添加复杂用法示例