october cms-官方文档-ajax

公孙令秋

2023-12-01

AJAX

介绍

October包含一个整体ajax解决方案，可以让你无刷新加载数据
这个库同样可以用在主题和后端页面的任何地方

AJAX框架有两种写法
你可以使用JavaScript API或数据attributes API。
其中，数据属性API不需要任何JavaScript知识

如何引入

AJAX框架在CMS主题中是可选的
要使用这个库，您应该将{%framework%}标记放在页面或布局中的任何位置来包含它。这将添加对十月前端JavaScript库的引用。
库需要jQuery，因此应该先加载它，例如：

<script src="{{ 'assets/javascript/jquery.js'|theme }}"></script>

{% framework %}

{%framework%}标记支持可选的extras参数。如果指定了此参数，则标记将添加样式表和JavaScript文件以获得额外的功能，包括表单验证和加载指示器。

{% framework extras %}

请求

页面可以通过数据属性或JavaScript发出AJAX请求。
每个请求都会在服务器上调用一个事件处理程序（也称为AJAX处理程序）
并可以使用partials更新页面元素。
AJAX请求最适合表单，因为表单数据会自动发送到服务器。
以下是请求工作流：

客户端发起ajax请求里面包含方法名和一系列参数
服务端找到此方法并执行它
方法执行并更新环境变量
服务端通过更新后的option来渲染指定partials
服务端发起response，包含markup后的partials
客户端框架接受partials数据并更新页面元素

注意根据页面上下文 CMS partial 或后端 partial将被渲染

用法

下面是一个简单的例子，它使用数据属性API来定义一个支持AJAX的表单。表
单提交ajax，服务端执行onTest方法，并请求把渲染后的后端partial—“mypartial” 放入结果容器。

<!-- AJAX enabled form -->
<form data-request="onTest" data-request-update="mypartial: '#myDiv'">

    <!-- Input two values -->
    <input name="value1"> + <input name="value2">

    <!-- Action button -->
    <button type="submit">Calculate</button>

</form>

<!-- Result container -->
<div id="myDiv"></div>

注意：value1和value2的表单数据随AJAX请求自动发送。

名为"mypartial"的partial包含读取结果变量的标记。

The result is {{ result }}

onTest使用input的一系列助手api，可以访问到表单数据，并将结果传递到result页面变量。

function onTest()
{
    $this->page['result'] = input('value1') + input('value2');
}

该示例可能如下所示：“提交表单后，向onTest发出AJAX请求。执行后，将mypartial注入#myDiv元素。”

事件调用

ajax调用

AJAX event handlers are PHP functions that can be defined in the page or layout PHP section or inside components. Handler names should have the following pattern: onName. All handlers support the use of updating partials as part of the AJAX request.
ajax调用是一个php方法，可以被定义在

页面内
php布局片段
组件中
命名规则为 onName
所有的方法都支持在AJAX请求中使用更新partials的用法

function onSubmitContactForm()
{
    // ...
}

如果在page和layout布局中同时定义了两个具有相同名称的方法，优先执行page的。
component具有最低优先级。

调用方法

每个AJAX请求都应使用数据属性API或JavaScript API指定处理程序名称。
发出请求后，服务器将搜索所有已注册的处理程序，并找到它找到的第一个处理程序。

<!-- Attributes API -->
<button data-request="onSubmitContactForm">Go</button>

<!-- JavaScript API -->
<script> $.request('onSubmitContactForm') </script>

如果两个组件注册了相同的处理程序名称，建议为处理程序添加组件简称或别名。如果组件使用mycomponent的别名，则可以使用mycomponent :: onName作为处理程序的目标。

<button data-request="mycomponent::onSubmitContactForm">Go</button>

如果用户更改了页面上使用的组件别名，则可能要使用__SELF__引用变量而不是硬编码别名。

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

通用方法

有时你发出AJAX请求就是想刷新一下页面，而不想执行任何代码。
可以使用onAjax。该方法本身就有，无需编写任何代码。

<button data-request="onAjax">Do nothing</button>

ajax方法重定向

从ajax方法返回Redirect对象，框架帮助你来重定向页面

function onRedirectMe()
{
    return Redirect::to('http://google.com');
}

ajax返回数据

从success中获得返回数据

function onFetchDataFromServer()
{
    /* 服务器端*/

    return [
        'totalUsers' => 1000,
        'totalProjects' => 937
    ];
}

通过属性获取数据

<form data-request="onHandleForm" data-request-success="console.log(data)">

通过js获取数据

<form
    onsubmit="$(this).request('onHandleForm', {
        success: function(data) {
            console.log(data);
        }
    }); return false;">

异常

使用AjaxException类抛出AJAX异常

throw new AjaxException([
    'error' => 'Not enough questions',
    'questionsNeeded' => 2
]);

注意：抛出此异常类型时，partials 将正常更新。

调用前执行代码

利用onInit方法，就可以在ajax方法调用前执行前置代码了这涉及了页面执行的生命周期钩子

function onInit()
{
    // From a page or layout PHP code section
}

你可能会在组件类或后端widget小部件类中定义init方法

function init()
{
    // From a component or widget class
}

partial更新

调用方法通过pushing 或 pulling 一些数据来更新partials

Pulling partial updates 拉取partial更新

当客户端浏览器执行AJAX请求时，它可能会请求服务器更新部分内容，这被认为是在进行内容更新。以下代码在调用onRefreshTime事件处理程序后，在页面上的myDiv元素内呈现mytime部分。

<div id="myDiv">{% partial 'mytime' %}</div>

数据属性API使用data-request-update属性。

<!-- Attributes API -->
<button
    data-request="onRefreshTime"
    data-request-update="mytime: '#myDiv'">
    Go
</button>

JavaScript API使用update配置选项：

<!-- JavaScript API -->
$.request('onRefreshTime', {
    update: { mytime: '#myDiv' }
})

update语法

update语法与json很像

左侧为partial名字
右侧为要更新的目标元素

以下内容是用mypartial内容更新#myDiv元素。

mypartial: '#myDiv'

多个partial之间用逗号分隔。

firstpartial: '#myDiv', secondpartial: '#otherDiv'

如果partial名称包含斜杠或破折号，则在左侧“加引号”很重要。

'folder/mypartial': '#myDiv', 'my-partial': '#myDiv

target元素将始终在右侧，因为它也可以是JavaScript中的HTML元素

mypartial: document.getElementById('myDiv')

追加和前置内容

如果选择器字符串前面带有@符号，则将从服务器接收到的内容append该元素后面，而不是替换现有内容。

'folder/append': '@#myDiv'

如果选择器字符串前面带有^符号，则内容将填充到元素前面

'folder/append': '^#myDiv'

Pushing partial updates 推送partial更新

相比之下，AJAX可以将内容更新从服务器端推送到客户端浏览器。为了推送更新，处理方法返回一个数组，其中键是要更新的HTML元素（使用简单的CSS选择器），值是要更新的内容。
以下示例将使用mypartial内部的内容更新ID为myDiv的页面上的元素。 onRefreshTime调用renderPartial方法来渲染PHP中的部分内容

function onRefreshTime()
{
    return [
        '#myDiv' => $this->renderPartial('mypartial')
    ];
}

注意：密钥名必须以标识符或类开头。用于触发内容更新的字符。

传递变量给partial

根据执行上下文的不同，AJAX调用方法为部分变量提供了不同的可用性。

在页面或布局PHP部分中使用$this[]。
在组件类中使用$this->page[]。
在后端区域使用$this->vars[]。
这些示例将为每个上下文的分部提供结果变量：

// From page or layout PHP code section
$this['result'] = 'Hello world!';

// From a component class
$this->page['result'] = 'Hello world!';

// From a backend controller or widget
$this->vars['result'] = 'Hello world!';

然后，可以使用Twig在以下部分中访问此值：

<!-- Hello world! -->
{{ result }}