october cms-官方文档-ajax（续）

AJAX API

Data attributes API

Data attributes API

属性	描述
data-request	指定AJAX要调用的方法
data-request-confirm	指定确认消息。在发送请求之前显示确认。如果用户单击“取消”按钮，则不会发送请求。
data-request-redirect	指定在成功AJAX请求之后重定向浏览器的URL。
data-request-url	指定将请求发送到的URL。默认值：window.location.href
data-request-update	指定要更新的partial和页面元素（CSS选择器）的列表。格式为partial: selector, partial: selector. 在某些情况下需要使用引号，如：‘my-partial’: ‘#myelement’. 注意@和^的用法
data-request-ajax-global	默认为false。设置为true可全局启用jQuery ajax事件：ajaxStart，ajaxStop，ajaxComplete，ajaxError，ajaxSuccess和ajaxSend。
data-request-data	指定要发送到服务器的其他POST参数。格式如下 var: value, var: value.如果用引号的话 格式为 var: ‘some string’ 该属性可以在触发元素上使用，例如在也具有data-request属性的按钮上，在触发元素的最接近元素或父表单元素上使用。该框架合并了data-request-data属性的值 如果不同元素上的属性使用相同的名称定义参数，则框架将使用以下优先级：触发元素data-request-data，较近的父元素data-request-data，表单输入数据。
data-request-before-update	指定要在页面内容更新之前直接执行的JavaScript代码。在JavaScript代码中，您可以访问以下变量：this（触发请求的元素），context对象，从服务器接收的data，textStatus 文本，jqXHR对象
data-request-success	this , context object , data object , textStatus , jqXHR object.
data-request-error	this , context object , textStatus , jqXHR object.
data-request-complete	指定在请求成功完成或遇到错误时要执行的JavaScript代码。可访问变量为：this（触发请求的元素），context对象，textStatus 文本，jqXHR对象
data-request-loading	为请求运行时要显示的元素指定CSS选择器。您可以使用此选项显示AJAX加载指示器。该功能使用jQuery的show()和hide()函数来管理元素的可见性。
data-request-form	显式指定一个表单元素以用于获取表单数据。如果未指定，则使用最接近触发元素的表单，包括元素本身是一个表单。
data-request-flash	指定后，此选项将指示服务器清除并发送带有响应的所有Flash消息。本选项也用在extra features中
data-request-files	指定请求文件时，请求将接受文件上传，这需要浏览器提供FormData接口支持。
data-track-input	可以应用于还具有data-request属性的文本，数字或密码输入字段。定义后，当用户在字段中输入内容时，输入字段会自动发送AJAX请求。 可选属性值可以定义框架在发送请求之前会等待多久间隔（以毫秒为单位）

当为元素指定data-request属性时，当用户与其交互时，该元素会触发AJAX请求。根据元素的类型，以下事件将触发请求：

元素	事件
Forms	表单发送时
Links, buttons	点击时
Text, number, and password fields	当文本更改时，并且仅当出现了data-track-input属性时
Dropdowns, checkboxes, radios	元素被选择时

用法

提交表单时调用onCalculate方法。用名为‘calcresult’的partial更新标识符为“ result”`的元素：

<form data-request="onCalculate" data-request-update="calcresult: '#result'">

发送请求之前，单击“删除”按钮，请求确认：

<form ... >
    ...
    <button data-request="onDelete" data-request-confirm="Are you sure?">Delete</button>

成功请求后，重定向到另一个页面：

<form data-request="onLogin" data-request-redirect="/admin">

成功请求后显示一个弹出窗口：

<form data-request="onLogin" data-request-success="alert('Yay!')">

发送带参POST：

在多个元素之间发送带参post：

<div data-request-data="id: 7">
    <button data-request="onDelete">Delete</button>
    <button data-request="onSave">Update</button>
</div>

文件上传

<form data-request="onSubmit" data-request-files>
    <input type="file" name="photo" accept="image/*" />
    <button type="submit">Submit</button>
</form>

JavaScript API

JavaScript API

JavaScript API比数据属性API更强大。 request方法可以与表单内部或表单元素上的任何元素一起使用。当该方法与表单内的元素一起使用时，它将被转发到表单。
request方法具有一个必填参数-AJAX处理程序名称。例：

<form onsubmit="$(this).request('onProcess'); return false;">
    ...

request方法的第二个参数是options对象。您可以使用与jQuery AJAX函数兼容的任何选项和方法。以下选项特定于十月框架：

属性	描述
update	一个对象，指定要更新的partial列表和页面元素（作为CSS选择器）：{‘partial’：’#select’}。如果前面是@select，那就是插入partial 而不是覆写
confirm	确认字符串。如果设置，则确认在发送请求之前显示。如果用户单击“取消”按钮，则请求将取消。
data	一个可选对象，用于指定要与表单数据一起发送到服务器的数据：{var：‘value’}。
redirect	字符串，指定成功请求后将浏览器重定向到的URL。
beforeUpdate	在页面元素更新之前执行的回调函数。 函数获取3个参数：从服务器接收的数据对象，文本状态字符串和jqXHR对象。函数内部的this变量解析为请求内容一个包含两个属性的object-----handler 和 options代表最初的request（）参数。
success	一旦成功，执行回调，指定AJAX要调用的方法。如果提供此选项，它将覆盖默认框架的功能：不更新元素，不触发beforeUpdate事件，不触发ajaxUpdate和ajaxUpdateComplete事件。事件处理程序获取3个参数：从服务器接收的数据对象，文本状态字符串和jqXHR对象。但是，您仍然可以调用默认框架功能，在函数内部调用this.success（…）
error	发生错误时执行回调函数。默认情况下，显示警报消息。如果覆盖此选项，则不会显示警报消息。处理程序获取3个参数：jqXHR对象，文本状态字符串和错误对象-请参见jQuery AJAX函数。
complete	一个表单元素，用于获取与请求一起发送的表单数据，可以作为选择器字符串或表单元素传递
flash	如果为true，则指示服务器清除并发送带有响应的所有Flash消息。默认值：false
form	一个表单元素，用于获取与请求一起发送的表单数据，可以作为选择器字符串或表单元素传递。
files	如果为true，则请求将接受文件上传，这需要浏览器提供FormData接口支持。默认值：false
loading	运行请求时要显示的可选字符串或对象。该字符串应为元素的CSS选择器，该对象应支持show（）和hide（）函数来管理可见性。您可以在使用框架额外功能时传递全局对象$ .oc.stripeLoadIndicator。

您还可以通过传递新fuction作为option来覆盖某些request逻辑。以下这些是可用的

方法	描述
handleConfirmMessage(message)	请求用户确认时调用。
handleErrorMessage(message)	显示错误消息时调用。
handleValidationMessage(message, fields)	使用验证时，将焦点放在第一个无效字段上。
handleFlashMessage(message, type)	使用Flash选项提供Flash消息时调用（见上文）。
handleRedirectResponse(url)	浏览器将重定向到另一个位置时调用。

用法

在发送onDelete请求之前，请请求确认：

$('form').request('onDelete', {
    confirm: 'Are you sure?',
    redirect: '/dashboard'
})

运行onCalculate处理程序，并将呈现的calcresult partial与result CSS类一起注入到page元素中：

$('form').request('onCalculate', {
    update: {calcresult: '.result'}
})

带参运行onCalculate

$('form').request('onCalculate', {data: {value: 55}})

刷新页面前调用beforeUpdate

$('form').request('onCalculate', {
    update: {calcresult: '.result'},
    beforeUpdate: function() { /* do something */ }
})

调用成功后 这么写

$('form').request('onCalculate', {success: function(data) {
    //... do something ...
    this.success(data);
}})

没有表单元素时 js写法:

$.request('onCalculate', {
    success: function() {
        console.log('Finished!');
    }
})

成功function完成后 调用一个回调

$('form').request('onCalculate', {success: function(data) {
    this.success(data).done(function() {
        //... do something after parent success() is finished ...
    });
}})

全局 AJAX 事件

AJAX框架在update，trigger，form和windows对象上装载了多个钩子。
无论使用哪个API（数据属性API或JavaScript API），都会触发钩子。

方法	描述
ajaxBeforeSend	在发送请求之前在window对象上触发。
ajaxBeforeUpdate	在请求完成之后但在页面更新之前，直接在表单对象上触发。处理程序获取5个参数：event对象, context object, the data object 服务器传回的data对象, 状态文本值, 和jqXHR对象
ajaxUpdate	在使用框架更新后在页面元素上触发。处理程序获取5个参数：event对象, context object, the data object 服务器传回的data对象, 状态文本值, 和jqXHR对象
ajaxUpdateComplete	框架更新所有元素后，在window对象上触发。处理程序获取5个参数：event对象, context object, the data object 服务器传回的data对象, 状态文本值, 和jqXHR对象
ajaxSuccess	成功完成请求后，在表单对象上触发。处理程序获取5个参数：event对象, context object, the data object 服务器传回的data对象, 状态文本值, 和jqXHR对象
ajaxError	如果请求遇到错误，则在表单对象上触发。 处理程序获取5个参数：event对象, context object, error信息， 状态文本值, 和jqXHR对象
ajaxErrorMessage	如果请求遇到错误，则在窗口对象上触发。处理程序获取2个参数：事件对象和从服务器返回的错误消息
ajaxConfirmMessage	当给出确认选项时，在窗口对象上触发。处理程序获得2个参数：事件对象和作为confirm选项的一部分分配给方法的文本消息。这对于实现自定义确认逻辑/接口而不是本机javascript确认框很有用。

以下事件在触发元素上触发：

方法	描述
ajaxSetup	在形成请求之前触发，从而允许通过context.options对象修改option。
ajaxPromise	在AJAX请求发送之前直接触发。
ajaxFail	如果AJAX请求失败，则最终触发。
ajaxDone	如果AJAX请求成功，则最终触发。
ajaxAlways	无论AJAX请求失败还是成功都触发。

例子

在元素上触发ajaxUpdate事件时执行JavaScript代码。

$('.calcresult').on('ajaxUpdate', function() {
    console.log('Updated!');
})

使用逻辑处理程序执行显示Flash消息的单个请求。

$.request('onDoSomething', {
    flash: 1,
    handleFlashMessage: function(message, type) {
        $.oc.flashMsg({ text: message, class: type })
    }
})

将配置全局应用于所有AJAX请求。

$(document).on('ajaxSetup', function(event, context) {
    // Enable AJAX handling of Flash messages on all AJAX requests
    context.options.flash = true

    // Enable the StripeLoadIndicator on all AJAX requests
    context.options.loading = $.oc.stripeLoadIndicator

    // Handle Error Messages by triggering a flashMsg of type error
    context.options.handleErrorMessage = function(message) {
        $.oc.flashMsg({ text: message, class: 'error' })
    }

    // Handle Flash Messages by triggering a flashMsg of the message type
    context.options.handleFlashMessage = function(message, type) {
        $.oc.flashMsg({ text: message, class: type })
    }
})

extras 额外后缀功能

使用AJAX框架时，可以选择指定Extras后缀，其中包括其他StyleSheet和JavaScript文件。当在前端CMS页面中使用AJAX请求时，这些功能很有用。

{% framework extras %}

Loading indicator 加载指示器

你应该注意到的第一个功能是运行AJAX请求时显示在页面顶部的加载指示器。该指标与AJAX框架使用的全局事件挂钩。
当AJAX请求启动时，将触发ajaxPromise事件，该事件显示加载指示器并将鼠标光标变为加载状态。
ajaxFail和ajaxDone事件用于检测请求何时完成，指示符在哪里再次隐藏。

表单验证

您可以在表单上指定data-request-validate属性以启用验证功能。

<form
    data-request="onSubmit"
    data-request-validate>
    <!-- ... -->
</form>

抛出验证错误

服务器端AJAX处理程序中，您可以使用ValidationException类抛出验证异常，以使字段无效，其中第一个参数是数组。
数组应使用字段名称作为键，并使用错误消息作为值。

function onSubmit()
{
    throw new ValidationException(['name' => 'You must give a name!']);
}

注意：您还可以将验证服务(validation service)的实例作为异常的第一个参数传递。

展示error信息

在表单内部，可以使用容器元素上的data-validate-error属性显示第一条错误消息。容器内的内容将被设置为错误消息，并且该元素将变为可见。

<div data-validate-error></div>

要显示多个错误消息，请包含一个具有data-message属性的元素。
在此示例中，段落标签将被复制并为存在的每条消息设置内容。

<div class="alert alert-danger" data-validate-error>
    <p data-message></p>
</div>

要在AJAX失效上添加自定义类，请钩住ajaxInvalidField和ajaxPromise JS事件

$(window).on('ajaxInvalidField', function(event, fieldElement, fieldName, errorMsg, isFirst) {
    $(fieldElement).closest('.form-group').addClass('has-error');
});

$(document).on('ajaxPromise', '[data-request]', function() {
    $(this).closest('form').find('.form-group.has-error').removeClass('has-error');
});

字段展示error

另外，您可以通过定义使用data-validate-for属性的元素（将字段名称作为值传递）来显示各个字段的验证消息。

<!-- Input field -->
<input name="phone" />

<!-- Validation message for the field -->
<div data-validate-for="phone"></div>

如果该元素保留为空，则将使用服务器中的验证文本填充该元素。否则，您可以指定您喜欢的任何文本，它将改为显示。

<div data-validate-for="phone">
    Oops.. phone number is invalid!
</div>

加载button

当任何元素包含data-attach-loading属性时，将在AJAX请求期间将CSS类oc-loading添加到该元素。此类使用:after在按钮和锚点元素上生成小加载图标。

<form data-request="onSubmit">
    <button data-attach-loading>
        Submit
    </button>
</form>

<a
    href="#"
    data-request="onDoSomething"
    data-attach-loading>
    Do something
</a>

flash信息

在表单上指定data-request-flash属性，以在成功的AJAX请求中启用Flash消息。

<form
    data-request="onSuccess"
    data-request-flash>
    <!-- ... -->
</form>

结合事件处理程序中Flash外观的使用，请求完成后将显示一条Flash消息。

function onSuccess()
{
    Flash::success('You did it!');
}

为了与基于AJAX的Flash消息保持一致，可以通过在页面或布局中放置此代码来在页面加载时呈现标准flash信息 standard flash message。

{% flash %}
    <p
        data-control="flash-message"
        class="flash-message fade {{ type }}"
        data-interval="5">
        {{ message }}
    </p>
{% endflash %}

用法

以下是表单验证的完整示例。它调用onDoSomething事件处理程序，该事件处理程序将触发加载提交按钮，对表单字段执行验证，然后显示成功的Flash消息。

<form
    data-request="onDoSomething"
    data-request-validate
    data-request-flash>

    <div>
        <input name="name" />
        <span data-validate-for="name"></span>
    </div>

    <div>
        <input name="email" />
        <span data-validate-for="email"></span>
    </div>

    <button data-attach-loading>
        Submit
    </button>

    <div class="alert alert-danger" data-validate-error>
        <p data-message></p>
    </div>

</form>

AJAX事件处理程序查看客户端发送的POST数据，并将一些规则应用于验证器。如果验证失败，则抛出ValidationException，否则返回Flash :: success消息。

function onDoSomething()
{
    $data = post();

    $rules = [
        'name' => 'required',
        'email' => 'required|email',
    ];

    $validation = Validator::make($data, $rules);

    if ($validation->fails()) {
        throw new ValidationException($validation);
    }

    Flash::success('Jobs done!');
}