README

轻量级无依赖的dom更新引擎，适用于 earc 框架。

在用户输入时获取或更新服务器端资源是一个常见任务。在获取资源的同时更新DOM。当你的应用的部分与JavaScript纠缠在一起时，服务器端会失去唯一的真实来源。现在必须了解客户端和服务器端才能理解应用。有些人可能试图将全部真实信息拉到客户端，并构建由RESTful接口驱动的单页应用。这个包使你能够反向操作。它为你提供了一个基于客户端html-data-attribute的接口。如果你正确使用这个接口，你可以写出复杂的动态应用而无需写一行JavaScript代码。

安装

$ composer require earc/router

引导

在您的资产管道中注册文件 vendor/earc/dom-resource-update-engine/src/dom-resource-update-engine.js 或将其复制/链接到您的Web目录，并在Web页面中导入它。

<script type="text/javascript" src="/js/dom-resource-update-engine.js"></script>

在页面体最后一行调用 domResourceUpdateEngine 的 init() 函数。

        // ...
        <script>domResourceUpdateEngine.init();</script>
    </body>
</html>

您就可以开始使用了。

配置

大多数情况下，您不需要配置这个包。其他情况将在 TODO 部分中讨论。

基本用法

DOM资源更新引擎基于三个html-data-attribute

data-update-id
data-update-events
data-update-resources

和一个基于JSON的指令 update-directive。

data-update-id 为引擎提供元素标识符。

data-update-events 将JavaScript事件绑定到预定义和用户定义的引擎操作。

data-update-resources 属性将操作绑定到资源调用。

update-directive 使用元素标识符和预定义的引擎操作来更新DOM。

数据更新ID

data-update-id 属性的值是HTML元素的标识符。您可以随意命名它。

数据更新事件

data-update-events 属性的语法是一个JSON对象，包含JavaScript事件类型作为属性名。例如 click 或 submit 是有效的属性名。属性包含具有 data-update-ids 作为属性名的对象。值是动作名称的数组。

语法转换为在每个事件类型上附加到当前元素的监听器。如果事件触发监听器，则对具有相应 data-update-id 的元素运行动作。

您可以使用 ~ 作为当前元素的缩写ID。

<button data-update-events='{ "click": { "target-element": ["user-defined-action"] }}' 
>click me!</button>
<div data-update-id='target-element'>... to run an user defined action on me.</div>

提示

请注意，JSON表示法只接受双引号。
监听器在调用 init() 或在它们的html-fragment添加到DOM后立即附加。

数据更新资源

data-update-resources 也是一个 JSON 对象。属性名是要调用的 URL，而值是数组，指定了触发 URL 调用的动作。

data-update-resources 符号有两个具有特殊意义的动作。

load 动作在事件监听器附加后立即触发一次调用。
如果在一个表单元素上运行 submit，则使用表单的方法发送表单数据。

<form 
        method="POST"
        data-update-id='my-form' 
        data-update-resources='{ "/the/url/called/on/submit":["submit"] }'
>
    // ...
    <button data-update-events='{ "click": { "my-form": ["submit"] }}'>submit it!</button>
</form>

提示

JavaScript 的 load 事件不会触发 load 动作。同样，load 动作也不会触发 load 事件。
JavaScript 的 submit 事件不会触发 submit 动作。同样，submit 动作也不会触发 submit 事件。
如果您监听 submit 事件，则在其上调用 preventDefault()，防止表单正常提交。

更新指令

由数据更新资源调用的服务器有一个响应。响应必须是 JSON 对象。参数名为 data-upload-ids。值是对象，参数名引用以下预定义动作之一：

replace：用解析为 HTML 的值替换元素。
update：用解析为 HTML 的值替换元素的子元素。
delete：删除元素。
beforebegin：在元素之前插入解析为 HTML 的值。
afterbegin：在第一个子元素之前插入解析为 HTML 的值。
beforeend：在最后一个子元素之后插入解析为 HTML 的值。
afterend：在元素之后插入解析为 HTML 的值。

{ "data-update-id-of-the-elment": { "update": "<div>This divs will replace the children</div><div>...</div>"}]

有两个特殊元素与一个特殊动作相关联。

{ 
    "console": { "log": "This string will be printed to the console."},
    "error": { "throw": "An error will be thrown. This is its message."},
    "an-element": { "replace": "an-element will not be replaced as the error kills the script" }
}

获取属性

为了能够在没有表单的情况下发送数据，data-update-resources 可以获取属性。使用哈希 # 将 URL 段替换为具有相同名称的元素的属性。要获取另一个元素的属性内容，请将哈希与元素的 HTML id 预先添加。

<span class="form user-content" id="getMyAttribute">...</span>
<input 
        type="number"  
        value=""        
        data-update-ressources='{ "/url/path/#value/getMyAttribute#class": ["user-defined-action"]}'
/>

提示

被属性内容替换的 URL 部分必须以斜杠开始和结束，或者必须是以斜杠开始的 URL 的最后一部分。
如果属性为空或不存在，则 URL 的该部分替换为字符串 string null。

待办事项：高级用法文档

UPDATE-DIRECTIVE: { "Tmpl:Instance::ID|~": { action: "[HTML]"|<|>}, ... }

data-update-events="{ click: { "Tmpl:Instance:ID"|~ : [action1, action2, ...]|*, ...}, ...}"

data-update-filter="[action1, action2]"

data-update-id="Tmpl:Instance::ID"

data-update-resources="{ "URL"|"URL/elm-id#attrName/#otherAttr": [action1, action2]|*,...}"

data-update-directives="UPDATE-DIRECTIVE"

ID-MAPPING: { "oldId" : { action|* : { id: "newId", action: "newAction" }}}

earc / dom-resource-update-engine

维护者

详细信息