README

下载 | Packagist | Twitter | GitHub | 支持论坛 | 捐赠

Rah_external_output是一个可以用于创建自定义内容类型片段的Textpattern插件。这些片段可以通过公开可访问的URL进行请求，用作页面或作为JSON或XML形式的内容提供给JavaScript或跨域使用。

虽然这些片段可以作为页面使用，但它们独立于Textpattern的正常内容模型。片段不需要也不需要过多使用页面模板或部分。

这使得该插件非常适合生成各种公开可访问的片段，包括可以用于向JavaScript应用程序提供内容、构建应用程序层或跨域传输内容的XML馈送或JavaScript对象表示。

Rah_external_output使用Textpattern的表单部分来提供其片段功能。名为以rah_eo_开头的前缀的表单部分可以通过URL直接访问，创建自己的独立页面。术语外部直接指代与部分和页面模板的分离和独立性，同时仍然提供客户端内容。

特性列表

• 带有rah_eo_前缀的表单部分可以请求，并且可以通过公开的URL直接访问其输出。
• 除了正常的表单部分之外，这些特殊表单、片段还可以包含HTTP头部行。以分号开始的表单开头行被处理为头部。
• 可以通过附加文件扩展名到名称来使用不同的内容类型提供表单部分。

要求

Rah_external_output的最小要求

• Textpattern 4.4.1或更高版本。
• PHP 5.2.0或更高版本。

安装

使用Composer

$ composer require rah/rah_external_output:*

或者下载插件包。

基础知识

Rah_external_output将任何以rah_eo_前缀命名的杂项类型表单部分视为“外部”内容类型片段。这些特殊前缀的表单可以通过公开的回调URL访问。此URL遵循以下模式

http://example.com/?rah_external_output=FormNameWithoutPrefix

其中example.com是网站的URL，FormNameWithoutPrefix是表单名称，不包括前缀。上述URL将输出一个名为rah_eo_FormNameWithoutPrefix的杂项表单。

创建第一个片段

创建一个新的 rah_external_output 自定义表单的片段，将遵循与 任何其他表单 相同的步骤。转到“展示”下的“表单”面板，点击右侧列顶部的“创建新表单”按钮。这将打开一个新的空编辑器。

与任何表单片段一样，您可以在大代码字段中输入任何 Textpattern 标记。这个字段包含您的片段在通过其 URL 访问时将输出的内容。现在，在字段中输入 this

; Content-type: text/plain
<<txp:site_name /> says> Hello World!

然后，您可以在“名称”字段中为片段命名。此名称也将用于片段的 URL。要将表单片段注册为 rah_external_output 的片段，名称应以前缀 rah_eo_ 开头。现在，给表单命名为 rah_eo_hello_world。

最后但同样重要的是，是 类型。对于片段来说，最合适的类型是 其他，但如果您愿意，可以是任何类型。表单类型主要用于视觉上组织在管理端的内容，从“编写”面板的 覆盖表单 字段到标签构建器。

完成代码、命名并选择类型后，点击 保存 按钮。片段现在可以访问了。在保存编辑器后，您将注意到“名称”字段旁边有一个 查看 链接。通过点击链接，您将被带到片段生成的页面。

该页面是片段公开可访问的 URL，您可以将其自由用作页面，向应用程序提供内容并在客户端脚本中使用。对于您刚刚创建的片段 rah_eo_hello_world，此 URL 将是

http://example.com/?rah_external_output=hello_world

其中 example.com 是您站点的 URL，而 hello_world 是片段的名称。访问片段时，您应该看到以下输出

<MySiteName says> Hello World!

其中 MySiteName 是站点的名称。如您所注意到的，页面作为纯文本而不是 HTML 提供。这是由于片段代码中包含的 HTTP 标头行所致

; Content-type: text/plain

所有 rah_external_output 的片段都支持一些独特功能，包括自定义 HTTP 标头行和文件扩展名。

自定义 HTTP 标头

除了表单片段的正常功能外，rah_external_output 的特殊表单、片段还支持发送自定义 HTTP 标头，包括内容类型标头。

表单开头所有以分号 (;) 开头的行都作为 HTTP 标头发送。这些行应放置在表单的非常开头，从第一行开始。HTTP 标头行不能以任何空白或空行开头。

HTTP 标头行遵循您从 HTTP 标头字段定义中期望的正常语法。一行由一个标头属性组成，也通常称为字段，后面跟一个冒号 (:) 和一个值。

; Property: Value

一个表单支持无限数量的标头行。每个以分号开始的后续行都作为 HTTP 标头发送。

; Content-type: text/javascript
; Cache-Control: no-store, no-cache, must-revalidate, pre-check=0, post-check=0, max-age=0
; Expires: Sat, 24 Jul 2003 05:00:00 GMT
; Last-Modified: Wed, 1 Jan 2025 05:00:00 GMT
; Pragma: no-cache

使用这些 HTTP 标头行，可以重定向访客或更改文档的内容类型、编码、缓存或时间戳属性。以下标头行开始的表单将以纯文本形式发送

; Content-type: text/plain

<txp:article_custom limit="15">
	<txp:permlink><txp:title /></txp:permlink>
</txp:article_custom>

请注意，出于安全原因，HTTP 标头行不能包含 Textpattern 标签。标头是在处理任何 Textpattern 标签之前从源代码中收集的。这是为了防止可能发生的任何类型的标头注入。

内容类型和文件扩展名

除了自定义 HTTP 标头外，还可以通过将文件扩展名附加到表单名称来设置片段的内容类型。支持的扩展名有 .json、.js、.xml、.css、.txt 和 .html。

如果表单命名为 rah_eo_jsontable.json，当访问 http://example.com/?rah_external_output=jsontable.json 时，这段代码将以 JSON 格式呈现。

标签跟踪和调试

与 Textpattern 的常规页面模板一样，rah_external_output 的代码片段支持 标签跟踪。在 调试模式 下，标签跟踪将附加到每个以 .html 扩展名结尾的代码片段的 HTML 输出。与正常页面上的标签跟踪一样，跟踪会告诉你正在执行哪些 Textpattern 标签及其结果。

示例片段

由于插件可以用于提供任何类型的片段和内容，因此无法说明您是否应该使用它。为了提供一个简单的想法，说明您可以从插件中获得什么好处，请参阅我们位于 GitHub 的 示例目录。该目录包含一些基本但真实世界的示例。示例包括 XML 网站地图生成和一些 JSON 服务。

针对开发者的

此插件包含一些针对开发者的功能。

回调

这些开发者功能之一是在片段被查看时触发的回调事件。相关的回调名为 rah_external_output.snippet_end，并在片段的末尾执行。此回调可以像其他 Textpattern 回调事件一样使用。通过使用 register_callback() 函数来挂钩事件。

register_callback(callback, 'rah_external_output.snippet_end');

有关插件开发和回调的更多信息，请参阅 插件基础知识。

文件扩展名

Rah_external_output 允许扩展识别的 MIME 类型和扩展名。这可以通过修改一个全局变量来完成。该变量的名称为 $rah_external_output_mime，它接受一个 extension => mime/type 键值对的数组映射。

global $rah_external_output_mime;
$rah_external_output_mime['png'] = 'image/png';
$rah_external_output_mime['svg'] = 'image/svg+xml';

变更日志

版本 1.1.0 – 2014/03/18

• 新增：支持干净的 URL。现在可以通过名称请求代码片段，例如 http://example.com/snippet。

版本 1.0.4 – 2013/05/07

• 变更：安装程序不使用嵌入式版本号。安装程序的主要目的是处理迁移。

版本 1.0.3 – 2013/05/06

• 变更：Composer 软件包现在使用 textpattern/lock 和 textpattern/installer。该软件包在 Textpattern 中安装，无需任何额外配置。

版本 1.0.2 – 2013/04/23

• 修复：PHP 命名空间兼容性。
• 变更：在 Textpattern 4.6.0-dev 中添加了“查看”链接到新操作栏。
• 改进：内部清理。
• 改进：使用 Textpattern 分配的标志以确保未来的兼容性。
• 改进：不需要为内存创建首选项。

版本 1.0.1 – 2012/08/31

• 变更：现在不会使用插件卸载 rah_eo_ 前缀的表单部分。这些表单可以用于除插件片段之外的其他目的。
• 删除：用作插件缓存回退的代码路径。现在依赖于插件生命周期回调的存在。
• 删除：v0.6 中部署的迁移清理器。现在不再相关。

版本 1.0 – 2012/07/14

• 删除：插件自己的用户界面。现在插件使用 rah_eo_ 前缀的表单部分，并与表单面板集成。
• 删除：<txp:rah_external_output /> 标签。由于使用表单，因此可以使用正常的、更灵活的 output_form 标签。
• 删除：为了符合 r3706，删除了对原始 PHP 的支持。
• 新增：可以通过在名称中使用文件扩展名来设置片段的内容类型。
• 新增：迁移助手脚本。在安装时自动运行，将旧接口的 rah_external_output 片段迁移到表单中。
• 新增：为开发者提供 rah_external_output.snippet_end 回调事件。
• 更改：请求不存在的片段时，返回 404 页面而不是主页。
• 更改：不再可以通过 URL 参数控制 标签跟踪。当片段名称有 .html 扩展名且网站处于调试模式时，会添加标签跟踪。
• 现在需要 PHP5 或更高版本。
• 兼容 Textpattern v4.5.0。

版本 0.9 – 2011/09/03

• 修复：现在可以处理原始 PHP 标签。
• 更改：现在以与核心相同的方式解析标签结构。执行两次。在每种情况下都提供与核心相同的结果。
• 新增：通过添加 rah_external_output_trace 参数 (&rah_external_output_trace=1) 到片段 URL，并在网站的生产状态设置为 调试 时，显示标签跟踪和错误报告的能力。

版本 0.8 – 2011/07/26

• 新增：使用 Textpattern v4.4.1 中引入的核心函数实现 CSRF (会话骑行) 保护。
• 更改：确保插件接口全部使用一种语言。
• 更改：仅在可能且有必要时尝试删除旧数据库表。在从干净的更新到干净的更新时不要运行查询。
• 更改：在安装时设置临时版本号。消除了无理由运行安装程序两次的可能性。
• 现在需要 Textpattern 版本 4.4.1 或更高。

版本 0.7 – 2011/06/12

• 修复：在 <txp:rah_external_output /> 标签中的错误。
• 修复：在主列表视图中关闭了未关闭的 <thead> 标签。
• 修复：现在管理员端页面标题使用语言字符串。

版本 0.6 – 2011/04/15

• 修复：在更改名称时保存片段。
• 修复：现在在保存时出现错误时保留发送到编辑器的数据，而不是从数据库中检索旧数据。
• 新增：支持翻译。界面现在使用语言字符串。
• 新增：现在缓存从 <txp:rah_external_output /> 标签获取的结果。
• 新增：现在使用插件生命周期回调，并包含卸载程序。
• 新增：在插件面板中添加一个选项链接，该链接指向插件的管理员界面。
• 移除：Mime 接口。这很令人困惑，而且使用的人不多。尝试简化用户界面。
• 更改：用户界面和标记。删除标题，删除内联样式，向表格中添加 <tbody> 和 <thead> 标签。
• 更改：现在使用新的、改进的多选/编辑功能，类似于其他 rah 插件。
• 更改：现在使用 textpattern 回调，而不是在插件加载时立即输出片段。
• 更改：现在检查保存/更新是否成功，而不是期望。
• 现在需要 Textpattern 4.2.0（或更高版本）以实现全部功能兼容性。

版本 0.5 – 2010/04/11

• 新增：多编辑功能中的 禁用 和 激活 操作。

版本 0.4 – 2009/06/08

• 修复：遗忘的插入查询转义。

版本 0.3 – 2009/05/10

• 修复：由未设置的 $pretext（注意：TXP 加载顺序）引起的错误。
• 将 $pretext 索引设置为空：我们不在页面模板上。

版本 0.2 – 2009/05/09

• 修复：遗忘的解析调用。

版本 0.1 – 2009/05/09

• 初始发布。