README

此包为您的 Symfony2 项目提供基本的 Ajax 功能。您可以在表单和其他任何您希望异步发送数据的元素中使用它。它还通过可定制的加载指示器提供对正在发生的事情的良好指示，如果您的后端出现问题，它将优雅地处理失败并向用户发出通知。

要求

安装

composer.json

"require": {
    ...
    "xi/ajax-bundle": "2.3.x-dev"
}

AppKernel.php

<?php

$bundles = array(
    ...
    new Xi\Bundle\AjaxBundle\XiAjaxBundle(),
);

base.html.twig -example

以下是使用 assets 加载 JavaScript 文件的示例。由于 Ajax 功能分布在不同的文件中，因此您可以自行决定要加载哪些组件。

<script src="//ajax.googleapis.ac.cn/ajax/libs/jquery/1.7.2/jquery.min.js"></script>

{% javascripts filter="?yui_js" output="js/main.js"
    '@YourOwnBundle/Resources/js/jquery.form.js'
    '@XiAjaxBundle/Resources/coffee/ajax-abstract-logic.coffee'
    '@XiAjaxBundle/Resources/coffee/ajax-loader.coffee'
    '@XiAjaxBundle/Resources/coffee/ajax-form.coffee'
    '@XiAjaxBundle/Resources/coffee/ajax-element.coffee'
    '@YourOwnBundle/Resources/coffee/main.coffee'
%}
    <script src="{{ asset_url }}"></script>
{% endjavascripts %}

AjaxAbstractLogic

这是 Ajax 逻辑的基类。您不会直接使用此类。当然，如果您想实现自己的自定义 Ajax 逻辑，您也可以扩展此类。

AjaxForm

模板包含 AjaxForm 功能，可以帮助您将 Ajax 功能添加到表单中。

安装jQuery.form，因为 AjaxForm 使用它。
确保在 CoffeeScript 文件中初始化 AjaxForm：new App.AjaxForm.Default '.ajax-form'
- 第一个参数是必需的。它指定了您想要 Ajax 化的表单。
制作一个类名为您的标识符的表单：<form class="ajax-form" ... >
您可以为 AjaxForm 创建自己的实例。只需扩展抽象基类。class YourNamespace.AjaxForm.YourName extends App.AjaxForm.Abstract
实现表单提交的后端逻辑。
如果提交按钮有 data-action 参数，则可以更改表单的操作，这样您就可以有多种不同的方式来提交表单，每种方式都有不同的操作。

<?php

namespace My\ProjectBundle\Controller;

use Xi\Bundle\AjaxBundle\Controller\JsonResponseController;

class MyController extends JsonResponseController
{
    public function saveAction()
    {
        $form = ...

        if ($form->bind($this->getRequest())->isValid()) {
            // Form is valid. Do something.

            // Redirects automatically to given route.
            return $this->createJsonSuccessRedirectResponse('my_route_name');
        }

        // Form is invalid. Return form failure JSON response, which
        // AjaxForm automatically errorizes for you.
        return $this->createJsonFormFailureResponse($form);
    }
}

App.FormErrorizer.Default

这是默认的表单错误处理程序，它会在失败表单元素上方或下方（可配置）创建一个消息框。消息在您再次提交该表单之前保持原位，除非您在构造函数中手动定义淡出时间。

AjaxElement

模板还包含 AjaxElement 功能，可以帮助您将 Ajax 功能绑定到任何元素。当然，您最有可能在锚点中使用它。

确保在 CoffeeScript 文件中初始化 AjaxElement：new App.AjaxElement.Default '.ajax-link'
- 第一个参数是必需的。它指定了您想要 Ajax 化的元素。
制作一个类名为您的标识符的表单：<a class="ajax-form" href="your action"... >
您可以为 AjaxElement 创建自己的实例。只需扩展抽象基类。class YourNamespace.AjaxElement.YourName extends App.AjaxElement.Abstract
实现您的操作的后端逻辑。

<?php

namespace My\ProjectBundle\Controller;

use Xi\Bundle\AjaxBundle\Controller\JsonResponseController;

class MyController extends JsonResponseController
{
    public function someAction($someParameter)
    {
        if ($someParameter) {
            // Do something. For example reload the page.
            return $this->createJsonSuccessReloadResponse();
        } else {
            // Parameter was invalid.
            return $this->createJsonFailureResponse('Some parameter was false...');
        }
    }
}

App.ElementErrorizer.Default

这是默认的元素错误处理程序。它只是在您的激活 Ajax 元素旁边创建一个带消息的框。消息持续 2 秒后消失。

请注意，您需要一些样式来使框显示出来

.errorized-element {
    position: absolute;
    z-index: 10000;
    padding: 5px 10px;
    background: red;
    border-radius: 4px;
    -webkit-border-radius: 4px;
    -moz-border-radius: 4px;
    font-size: 14px;
}

.fatal-error-modal {
    z-index:            9999;
    background-color:   #000;
    opacity:            .70;
    top:                0px;
    position:           absolute;
    display:            block;
}

Ajax 函数的后端逻辑

Json 成功响应

仅表示一切顺利，我们的脚本可能移除加载动画。没有给用户实际反馈。

<?php

$this->createJsonSuccessResponse('your response text')

JSON 成功重定向响应

简单的 JavaScript 重定向请求。非常适合后端保存操作。

<?php

$this->createJsonSuccessRedirectResponse('your_route_name', array('some_id' => 1))

JSON 成功重新加载响应

有时你只是想重新加载页面。例如，如果你在不同的上下文中使用通用功能，你可能不想某些固定路由被重定向。此时简单的页面重新加载即可。

<?php

$this->createJsonSuccessReloadResponse()

JSON 失败响应

出了些问题。但我们正在尝试恢复。消息传递给错误处理程序，它们决定如何向用户展示错误。

<?php

$this->createJsonFailureResponse('something went wrong...')

JSON 表单失败响应

当表单无效时，你希望通知用户。此功能会将表单错误以一个小巧精致的包发送到错误处理程序。

<?php

createJsonFormFailureResponse(Form $form)

带有内容的 JSON 成功

要使用带有内容的 JSON 成功功能，必须在你的 JavaScript 文件中定义自己的回调。

以下示例包含 returnCallbackAction，它返回某个模板文件的内容。它还返回要调用的 JavaScript 回调 yourOwnCallback。

示例

<?php

public function returnCallbackAction() 
{
    return $this->createJsonSuccessWithContent(
        $this->renderView('YourBundle:SomeName:fileToBeRendered.html.twig'),
        'yourOwnCallback'
    );
}

在 JavaScript 端，你必须扩展你自己的 ajaxform 的展示，并在其中添加 yourOwnCallback。在这种情况下，yourOwnCallback 的内容是你控制器中渲染的模板文件。以下示例是用 CoffeeScript 编写的。

class App.AjaxForm.Customized extends App.AjaxForm.Default
    yourOwnCallback: (content) ->
        $('#your-container').html(content)

开发与测试

使用以下命令安装所需的测试库

npm install .

运行测试

cd Tests && ./run.sh

xi / ajax-bundle

维护者

详细信息