october cms-官方文档-ajax

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获取数据

<formonsubmit="$(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 -->
<buttondata-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 }}