Learning Textpattern tags

Notes
Posted 1000 words

Textpattern 标签是 Textpattern 不可或缺的功能。它们提供了一种类似标记的方法来使用 Textpattern 的核心功能，而无需了解任何 PHP。函数本身表示内容组件、它们的源以及显示它们的方法。

标记可以通过多种方式添加到页面和/或表单模板中，具体取决于您要实现的目标。这些标记充当内容的占位符，当用户从您网站中的一个页面移动到另一个页面时，这些内容将替换为它们提取的动态内容输出。

本页介绍的标签基础知识将帮助您启动并运行 Textpattern 标签。如果您只追求引用，则可以在标签引用中找到当前标签、语法和示例的完整列表。

内容

标签剖析

与 HTML/XML 标签一样，Textpattern 标签有两种主要风格：自封闭标签和容器标签。有些可能两者兼而有之，具体取决于您希望如何使用它们。第三种类型与容器相关，是一种条件，允许您在满足某些条件时采取行动。

自封闭标签

自闭标签是 Textpattern 标签的最基本形式。它的结构类似于 HTML 中的自闭标签（例如 ），最显着的是包含终止正斜杠。<br />

大多数 Textpattern 标签都是自封闭标签，具有以下语法结构：

<txp:tagname_here />

当 Textpattern 显示网站页面时，该标签将替换为相关的动态数据库内容。

自闭合标记通常采用用于配置或更改显示内容的属性。例如，以下 article 标记演示了如何使用 和 属性：form``limit

<txp:article form="form-name" limit="15" />

容器标签

容器标记由开始标记和结束标记元素组成，赋予它们以下语法结构：

<txp:tagname_here>
    …content…
</txp:tagname_here>

在容器标记之间添加的内容可以是文本、HTML 或其他 Textpattern 标记。

典型的容器标签是 permlink 标签和所有条件标签。当某些东西必须被标签_包起来_而不是被标签_替换_时，就会使用容器标签。<txp:permlink></txp:permlink>

链接就是一个很好的例子：你有一个文本字符串（或标题标签），你想在它周围包装一个 HTML 锚元素：

<txp:permlink>
    <txp:title />
</txp:permlink>
…article content…
<txp:permlink>
    Read more…
</txp:permlink>

上面的示例将呈现为如下所示：

<a href="/articles/this-article-title">This article title</a>
…content…
<a href="/articles/this-article-title">Read more…</a>

条件标记

容器标签非常适合制作列表，您可以使用条件标签来提供帮助。在引入此类标签之前，值得注意的是，您的访问者处于两个_视图_之一，或者 Textpattern 术语中的上下文：

  1. 单个（单篇文章）上下文
  2. 列表（或登录页面）上下文

您无需担心管理哪个是哪个，因为 Textpattern 会为您处理这个问题，但您可以决定当访问者在任一状态下查看您的网站时要采取什么作。这就是条件标签的用武之地。从语法上讲，它们采用与容器相同的形式：

<txp:if_condition>
…content if condition is met…
</txp:if_condition>

如果需要在_不满足_条件时采取措施，也可以使用标记：<txp:else />

<txp:if_condition>
…content if condition is met…
<txp:else />
…content if condition is not met…
</txp:if_condition>

有许多条件标签可以帮助您对访问者在浏览您的网站时可能发现的许多不同类型的情况或上下文采取行动。

标签示例：显示类别列表

这些标签类型的强大功能可以在页面模板中编织在一起，在非常简单易读的标签集中创建一些复杂的逻辑。

当您向访问者展示文章时，您可以选择使其所属的类别可超链接。如果访问者选择其中一个链接，他们将被带到一个类别列表，其中显示同一类别中的其他文章。Textpattern 会自动从_单个文章_切换到_列表_上下文，因此您的单页模板可以使用容器和条件相当简单地处理这两种情况。

在默认文章页面上，您可能会看到如下内容：

<txp:if_category>
    <!-- Category landing page (list context) -->
    <h2>
        <!-- Display category title -->
        <txp:category title />
    </h2>
    <!-- Display up to 5 hyperlinked article titles plus each
         article's excerpt beneath, all wrapped in a div -->
    <txp:article limit="5" wraptag="div">
        <h3>
            <txp:permlink>
                <txp:title />
            </txp:permlink>
        </h3>
        <txp:excerpt />
    </txp:article>
<txp:else />
    <!-- Individual article context: show one article -->
    <txp:article wraptag="div" />
</txp:if_category>

逐块查看此内容，我们看到条件if_category确定访问者是否选择了类别超链接。如果他们有，我们就在列表上下文中。如果没有，则执行 else 部分。

在此示例中，else 部分中的文章被视为单个文章，因为它不是类别列表。在更复杂的页面中，它可能是更大的嵌套结构的一部分，因此可能是不同类型的列表（例如搜索结果），但现在我们将从表面上看它，并假设它是一篇单独的文章。

由于此标签中使用的唯一属性是 ，该标签将使用_默认_表单来呈现文章，并将整个内容包装在 HTML 标签中。如果您指定了自己的属性，则文章内容将由您选择的形式呈现。<txp:article />``wraptag``<div>``form

有趣的部分是访问者是否正在查看列表。在这种情况下，发生的第一件事是在 HTML 标签中显示类别标题。<h2>

接下来，我们调用标准文章标签，但我们不使用默认表单来呈现其内容，而是将标签用作容器。

由于我们处于列表上下文中，因此我们已将文章标签告知其输出，并且每页最多只显示 5 篇文章。同样，我们将文章列表包装在 HTML 标签中。limit``<div>

_文章_容器内的标签决定了我们将如何呈现列表中的每篇文章。在此示例中，我们将显示每篇文章的标题，这些标题都包裹在标签中，并永久链接到其各个文章内容。每个标题下方都是相应文章的摘录。<h3>

So, in just a few simple tags you have automatically rendered a list of articles. The tags have:

  1. Determined if the visitor is browsing a category list or not.
  2. Displayed a list of 5 article titles and associated excerpts.
  3. Displayed a single article if they are viewing an individual article.

That is the fundamental building block of how container and conditional tags can make building lists of things easy.

One thing to note: containers are great for simple content like this but if you find yourself repeating the same contained content over and over in Page templates or across a series of pages, you can make it easier to maintain by using Form templates instead. You then just write the container content once and use the attribute in self-closing article tags to use it, as many times as you need.form="my-contained-stuff"

Closing tags correctly

Textpattern tags behave like XML tags insofar as they must be closed correctly. Any containing tag must have both an opening tag and a corresponding closing tag (marked with a preceding slash):

<txp:some_tag>
    …content…
</txp:some_tag>

If the tag is a conditional tag, check to make sure that any else tag is employed correctly:

Right:

<txp:if_some_condition>
  …true branch…
<txp:else />
  …false branch…
</txp:if_some_condition>

错：

<txp:else>
</txp:else>
</txp:else />

单个（自动关闭）标签的末尾必须有一个斜杠：

<txp:some_single_tag with="attributes" />

还要检查尖括号是否没有错误地进行 HTML 编码，例如：

&lt;txp:some_tag /&gt;

标签嵌套

与 HTML 类似，Textpattern 允许您在标签中嵌套标签，只要您以正确的顺序关闭它们（即标签关闭不能重叠）。

此处使用缩进来显示哪些标签属于包含内容的哪些位。请注意标签的打开和关闭顺序;它遵循标准的 HTML 和 XML 原则：

<txp:if_section name="archive">
    <txp:if_category>
        Category list within the archive section
    <txp:else />
        Not a category list
    </txp:if_category>
<txp:else />
    Some other section
</txp:if_section>

嵌套深度没有限制，您可以在自身中嵌套相同的标签：

<txp:if_section name="article">
    My Articles
<txp:else />
    <txp:if_section name="about">
        About this website
    <txp:else />
        Erm… something else!
    </txp:if_section>
</txp:if_section>

标记上下文不正确

上下文之前已经谈到过：Textpattern 根据访问者在浏览您的网站时导航到的 URL 类型自动切换上下文。条件标签可以响应此上下文来执行作，但某些 Textpattern 标签仅用于特定位置。如果您在不正确的上下文中使用标签怎么办？在这种情况下，当您的站点处于_测试_或_调试_模式时，Textpattern 通常会向您发出类似于以下内容的消息：

“文章标签不能在文章上下文之外使用。”

这告诉您不应在放置命名标签的位置使用命名标签。

“文章”表单标签仅在文章上下文中有效。它们引用了一篇文章，因此它们只能在标识一篇特定文章的上下文中使用。具体来说，它们可用于：

  • 在单个文章页面模板上。
  • 在已使用 or 标签显示的“article”类型的表单模板中。<txp:article … />``<txp:article_custom … />
  • 在列表页模板上，如果标签包装在 中。<txp:if_individual_article>…</txp:if_individual_article>

文章上下文标签不能直接在文章列表页面模板中工作，因为列表页面不与任何单个文章相关联。

同样，“Comment”表单标签只能用于用于显示每个单独评论的表单（通常名为 ）;“File”表单和“Link”表单标签的工作原理类似。comments

Textpattern 可识别以下上下文：

品

任何单个文章

作者

任何类型的 URLexample.org/author/Author+Name

类别

该类型或容器内的任何 URL。example.org/category/category-name``<txp:category_list>…</txp:category_list>

类别资产

任何类型的 URL：、、、example.org/category/article/category-name``example.org/category/image/category-name``example.org/category/file/category-name``example.org/category/link/category-name

评论

文章中的评论区。

图像

使用属性时或容器内的任何单个图像。id``<txp:images>…</txp:images>

文件

使用属性时或容器内的任何单个文件id``<txp:file_download_list>…</txp:file_download_list>

链接

使用属性时或容器内的任何单个链接。id``<txp:linklist>…</txp:linklist>

部分

使用属性时或容器内的任何单个部分。name``<txp:section_list>…</txp:section_list>

属性

大多数 Textpattern 标签允许您将属性指定为键/值对以覆盖默认行为。例如：

<txp:tag key="value" />
<txp:category type="image" title />

Textpattern 标签中属性的用法类似于 HTML 中的属性。

需要记住的一些重要规则：

  • 属性值必须始终用双引号（或单引号）分隔。单引号具有特殊含义，因此默认使用双引号。
  • 属性键必须为小写。
  • 对于插件开发人员：属性键可以由字母“a”到“z”和下划线（尽管不是第一个或最后一个字符）组成。

属性值转义

几乎任何字符都可以在属性值中使用。与 HTML 不同，不需要对 和 等字符使用转义代码。事实上，属性值根本不应该包含 HTML 转义代码，因为标签本身应该负责正确的转义。>``<``&

但是，有一个例外：分隔符。属性值由一对双引号（或单引号）分隔，这对在属性值内使用分隔符施加了限制。

假设你想将此用作属性值：

Reward for "good" behaviour

不正确：

<txp:tag key="Reward for "good" behaviour" />

对于人类来说，很容易理解这是如何理解的，但对于 Textpattern 来说，属性值以“good”之前的双引号结尾。属性值的其余部分使其成为格式不正确的标记（导致它在生成的 HTML 代码中按原样显示）。

如果单引号没有特殊含义，可以通过使用单引号分隔属性值来解决此问题：

<txp:tag key='reward for "good" behaviour' />

虽然这在本例中按预期工作，但它不考虑同时包含单引号和双引号的属性值。Textpattern 采用了一种约定，即用作属性值一部分的重复分隔符被解释为文字字符而不是分隔符。例如：

<txp:tag key="reward for ""good"" behaviour" />
<txp:tag key='reward for ''good'' behaviour' />

如果你仔细看第二个例子，你会发现在属性值中，单词“好”的每一边都有两个单引号，而不是双引号。

最后一个例子展示了什么是可能的：

<txp:tag key="let's use ""double"" quotes & <html> here" />

唯一需要转义的字符是所选的属性分隔符本身，它出现在属性值内（在本例中为双引号）。

注意：在 Textpattern 4.0.6 及更早版本中，分隔符转义不存在，并且标签解析器也无法处理包含 .>

解析的属性值

在大多数情况下，您希望将属性值仅视为一串文本，但在某些情况下，让 Textpattern 解析属性值本身会很有用。

不解析双引号的属性值，因此，如果您的属性值包含一个看起来像标记的值，但应被视为文字文本，则必须始终使用双引号。事实上，除非您希望解析属性值，否则您应该始终使用双引号来分隔属性值。原因很简单：速度。解析属性值比将其视为纯文本要慢。

这一切意味着什么？下面是一些示例，从未解析的属性值开始：

<txp:tag key="plain text" />
<txp:tag key="literal <txp:tag />" />

在上面的示例中，属性都被视为纯文本;不解析文字标记。如果您希望解析属性值中的标签并返回标签的实际结果，则应像这样编写，在属性值周围使用单引号（撇号）：

<txp:tag key='parsed <txp:tag />' />

解析标签示例

使用具有名为“email”的自定义字段（包含电子邮件地址）和自定义字段“name”（包含“Donald Swain”）的文章：me@example.com

<txp:email
    email='<txp:custom_field name="email" />'
    linktext="Send email"
    title='Send email to <txp:custom_field name="name" />'
/>

因为解析了单引号的属性值，所以解析属性值后，它看起来像这样：

<txp:email
    email="me@example.com"
    linktext="Send email"
    title="Send email to Donald Swain"
/>

如果只是一篇文章，则不需要属性解析，但如果您在这样的自定义字段中有许多具有不同电子邮件地址的文章，这将非常有用。

属性值解析没有实际限制。在解析的属性值中，您可以：

  • 具有无限数量的标签。
  • 将纯文本与标签混合使用。
  • 使用容器标签（是的，偶数）、自闭标签和 if/else 构造。<txp:php>
  • 甚至可以将属性内标签的属性解析到无限深度，前提是您使用正确的属性值引用和转义。

将引号嵌套在引号中...

参考上面的最后一点，如果你想将一个标签插入到一个已经是一个属性的标签的属性中，事情可能会变得“有点毛”！但是保持你的智慧，你可以做这样的事情：

<txp:variable name="file_count" value='<txp:file_download_list form="file_cat" category=''<txp:l10n_get_lang type="short" />'' />' />
<txp:if_variable name="file-count">
    <h3>Some Header</h3>
    <txp:file_download_list category='<txp:l10n_get_lang type="short" />' wraptag="ul" break="li" />
<txp:else />
    <p>No files for this language.</p>
</txp:if_variable>

在第一个语句中，注意到 category 属性内的单撇号对吗？它们是转义单引号所必需的，这样解析器就不会将它们视为标签中 value 属性的末尾。在每个嵌套级别，标签周围的单引号数量通常会加倍，以保持语句的完整性;除非你保持头脑清醒，否则这会变得非常有趣！<txp:variable />

在上面的示例中，表单返回一些标记（在本例中，只是指向相关文件的一系列链接），这些标记都分配给名为“file_count”的变量的值。file_cat

结果是，可以用 if_variable 测试这个变量，看看它是否包含任何东西，如果包含，则可以显示文件列表。相反，如果没有该语言的文件，则显示条件语句的 else 部分。

全局属性

从 Textpattern 4.7.0 开始，一些常用的属性是_全局_的，即它们可用于任何（核心或插件）标签。重要的是要知道全局属性不能干预标签的内部处理，并且仅应用于标签的输出。 例如：

<txp:variable name="test" value="   " />

<txp:if_variable name="test" trim value>
    there is something to test
<txp:else />
    the variable is blank
</txp:if_variable>

不会像您预期的那样工作，因为全局将应用于 的输出。由于 'test' 变量 （） 的值不为空，因此条件的 'true' 分支返回：trim``<txp:if_variable name="test" value />``" "


    there is something to test

将 应用于该值，最终返回： ，即修剪掉周围的空间。trim``there is something to test

请注意，如果标签已经_具有_与全局属性同名的属性，则将处理标签_自己的_属性，并丢弃全局属性。

全局属性列表

下面列出了 Textpattern 可以处理的所有全局属性。

break="value"

其中 value 是一个 HTML 元素，指定时不带括号（例如 ）或一些字符串来分隔列表项。break="li"

默认值：br（参见中断交叉引用）。

breakby="integer(s)"

用于在按 分隔时对列表项进行分组。可能的值是整数列表，例如（2 个项目的组）或（1 个和 2 个项目的交替组）。否则，在每个循环上计算值，并在更改后立即发生“中断”。请注意，“字符串”必须用双引号括起来。break``2``1,2

默认值：1（未设置）（请参阅中断交叉引用）。

breakform="form name"

用作 'break' 的形式，通常与 'breakby' 属性一起使用。这种形式的特殊“<+>”模式将被中断发生时累积的列表“块”所取代。

默认值：未设置（参见 breakform 交叉引用）。

class="class name"

应用于包装器的 HTML。class

值：任何有效字符串。

默认值：未设置。

default="value"

如果标记的输出为空，则要显示的值。

值：任何。

默认值：未设置。

escape="list, of, transforms"

要应用于输出的转换。有关详细信息，请参阅标签转义。

值：、、 any taghtml``js``json``url``float``integer``number``ordinal``spell``lower``upper``title``[r|l]trim``quote``tags``textile

默认值：html。

evaluate="number list"

更改表单/容器内顶级标记的处理顺序。标签通常从上到下执行。如果您想更改此顺序，请想象 Textpattern 标签在容器内从 1 开始递增编号。要先处理标签 3 和 5，然后处理 1、2 和 4，请在容器标签中指定。evaluate="3, 5"

值：与容器内主（顶级）标记的数字位置相对应的任何逗号分隔数字。

默认值：未设置。

html_id="value"

应用于包装器的 HTML。id

值：任何有效字符串。

默认值：未设置。

label="value"

要在输出之前显示的标签。

值：任何有效字符串。

默认值：未设置。

labeltag="tag"

用于包装标签的标签（不带尖括号）。

值： 任何有效的 HTML 标签，例如 或。h3``div

默认值：未设置。

not="boolean"

切换部件。

值：0（否）或 1（是）。

默认值：未设置 （0）。

replace="string"

替换通过属性剥离的内容。trim

值：任何有效字符串。

默认值：未设置。

trim="string or regex"

从输出中删除匹配的模式。

值： 任何。 用于触发正则表达式匹配，否则该值将逐字被视为一组要修剪的字符。/value/

默认值：未设置。

wrapform="form name"

要用作 的表单 .如果 wraptag 模式太长或被重复使用，则很方便。wraptag

值： 任何已定义的表单名称。

默认值：未设置。

wraptag="tag or pattern"

用于包装输出的标签（不带尖括号）。

值： HTML 标签或包含将被输出替换的模式的字符串。<+>

默认值：未设置。

标签转义

可以使用全局属性，该属性适用于所有不原生处理它的标签（核心标签和插件标签）。它的值是一个以逗号分隔的“转换”列表，将按给定顺序应用于内容。 例如：escape

<txp:variable name="hello" escape="trim, textile">
    Hello, _world_!
</txp:variable>

<txp:variable name="hello" escape="html" />

将输出：

<p>Hello, <em>world</em>!</p>

可用的转义值

escape="html"（默认）

对特殊 HTML 字符 （） 进行编码。"'&<>

escape="url"

URL 对除 . 之外的所有字符进行 URL 编码。.-_

escape="db" 版本 4.8.6+

对内容进行编码，以便可以安全地将其用作数据库查询的一部分。

escape="json"

JSON 编码，不带引号。""

escape="quote"

用撇号括住内容。''

escape="trim" (ltrim,rtrim)

从内容中删除周围（左、右）空格/换行符。

escape="tidy"

从内容中删除多余的空格/换行符并触发更彻底的处理模式。

escape="number" (integer,float)

将内容格式化为指定类型的数字。

escape="tidy, number"

删除空格/换行符并将内容格式化为更严格的数字（强制浮点或小数优先）。

escape="tidy, integer"

删除空格/换行符并将内容格式化为更严格的整数（确保它首先遵循整数）。

escape="trim, integer"

从整数列表中删除零值和无效值。

escape="spell"

拼出数字内容（需要 PHP 扩展名）。NumberFormatter

escape="ordinal"

将内容格式化为序数（需要 PHP 扩展名）。NumberFormatter

escape="upper" (lower,title)

将内容转换为大写、小写或句子（标题）大小写。

escape="textile"

通过 Textile 解析器传递内容。

escape="tidy, textile"

删除空格/换行符，在前面添加一个空格以删除周围的标签，然后 Textile 内容。<p>

escape="tags"

从内容中去除所有 HTML 标签和注释，只留下内容的文本/数据。

escape="some-tag"

剥离任何自动关闭，或解开内容物中的任何容器。<some-tag />``<some-tag>…</some-tag>

escape="tidy, some-tag"

删除空格/换行符，转义任何正则表达式字符，然后剥离任何自闭合，或解包内容中的任何容器。<some-tag />``<some-tag>…</some-tag>

示例：从变量中提取数字

<txp:variable name="amount" value="Price: £1 234.78" />

<txp:variable name="amount" escape="number" />
<txp:variable name="amount" escape="tidy, number" />

输出不带（变量不是数字）和带 的。0``tidy``1234.78``tidy

示例：使用 Textile 格式化变量

<txp:variable name="test">
*This*
is

a _test_
</txp:variable>

<txp:variable name="test" escape="textile" />
<txp:variable name="test" escape="tidy, textile" />

没有它输出：tidy

<p><strong>This</strong><br />is</p>
<p>a <em>test</em></p>

有了它输出 .tidy``<strong>This</strong> is a <em>test</em>

示例：从摘录中删除所有图像

<txp:excerpt escape="img" />

示例：验证 AMP 所需的 JSON-LD

通过在各种代码上与 smd_thumbnail 插件一起使用，为 AMP 页面的部分创建有效的 JSON-LD。<head>``escape="json"

<script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@type": "BlogPosting",
    "headline": "<txp:title escape="json" />",
    "mainEntityOfPage": "<txp:permlink />",
    "datePublished": "<txp:posted format="iso8601" />",
    "dateModified": "<txp:modified format="iso8601" />",
    "description": "<txp:meta_description format="" escape="json" />",
    "author": {
      "@type": "Person",
      "name": "<txp:author escape="json" />"
    },
    "publisher": {
      "@type": "Organization",
      "name": "ExampleCorp",
      "logo": {
        "@type": "ImageObject",
        "url": "<txp:site_url />assets/img/amp-publisher-logo.png",
        "width": "320",
        "height": "60"
      }
    },
    "image": {
      "@type": "ImageObject",
      <txp:if_article_image><txp:images limit="1"><txp:smd_if_thumbnail type="amp-696w390h">"url": "<txp:smd_thumbnail type="amp-696w390h" display="url" />",<txp:else />"url": "<txp:site_url />assets/img/amp-article-image-fallback.png",</txp:smd_if_thumbnail></txp:images><txp:else />"url": "<txp:site_url />assets/img/amp-article-image-fallback.png",</txp:if_article_image>
      "width": "696",
      "height": "390"
    }
  }
</script>

集成标记符号与混合标记符号

Textpattern 和 HTML 标签可以混合在一起以实现各种目标。虽然这种区别使人们更容易看到这两种标签类型，但它可能会使标记更加冗长。随着您对 Textpattern 标签变得更加熟悉，您可以选择以更_集成_的方式编写标记，其中 HTML 在 Textpattern 标签属性中定义，而不是用作单独的标签。

一个非常简单的例子是前面的一个例子，其中类别标题被包装在 HTML 标签中显示：<h2>

    <h2>
        <txp:category title />
    </h2>

所有 textpattern 标签都可以采用一个属性，该属性将动态内容包装在给定标签中。所以你可以像这样获得相同的结果：wraptag

    <txp:category title wraptag="h2" />

等等，要输入的字符多了 3 个字符（不包括空格），那么怎么能更好呢？答案在于如果内容为空会发生什么。在原始 HTML 版本中，如果 category 标记未返回任何内容，则页面上会留下一个空。在集成版本中，如果没有内容，则也不会渲染包装的标签。<h2></h2>

在这个简单的例子中，这没什么大不了的，但当事情变得更加复杂时，这个概念可以对缩短标签结构产生很大的影响，因为你可能不需要额外的条件标签。

混合标记示例：图片和标题

考虑以下标准 HTML 标记块，它定义将图像显示为图形和标题：

<figure>
    <img src="/path/9.jpg">
    <figcaption>content</figcaption>
</figure>

这很好，但您使用 Textpattern 的原因是自动化内容输出并使事情更加动态。因此，让我们以混合方式添加一些相关的 Textpattern 标签：

<figure>
    <txp:images id="9">
        <img src="/path/<txp:image_info type="id" /><txp:image_info type="ext" />">
        <figcaption>
            <txp:image_info type="caption" />
        </figcaption>
    </txp:images>
</figure>

为了清楚起见，让我们浏览一下标记。HTML 标签中紧接着是一个 Textpattern images 容器标签：<figure>

…
    <txp:images id="9">
        …
    </txp:images>
…

我们需要添加这个额外的标签容器，以利用相应的image_info标签功能。这是唯一的原因。许多 Textpattern 标签都是相互关联的，其中包含父标签启用某些子标签，或迭代事物列表。

我们首先多次看到这一行中使用的标签：<txp:image_info />

…
    …
        <img src="/path/<txp:image_info type="id" /><txp:image_info type="ext" />">
        …
    …
…

在之后再次在块中：

…
    …
        …
        <figcaption>
            <txp:image_info type="caption" />
        </figcaption>
    …
…

在 的每个实例中，标记都在为上下文中的图像提取特定数据值 - id 为 9 的图像。第一行返回图像的 ID 号和文件扩展名。请注意，ID 和扩展名值之间没有添加，因为属性的值已包含所需的句点。<txp:image_info />``.``ext``type=""

在第二行中，是提取图像的标题值，您应该_始终_将其包含在每个图像的图像编辑面板区域中。<txp:image_info />

虽然混合标记在功能上更具动态性，但它总体上也是一个更大的标记块，因为没有将 HTML 与 Textpattern 标签集成。作为参考框架，整个混合标记块长 182 个字符，不包括换行符和缩进。

集成标记示例：图像和标题

现在考虑上面相同的标记功能块，但这次我们将 HTML _集成_到 Textpattern 标签中。没有功能差异;它的作用与上面的混合标记完全相同。它只是使用 Textpattern 标签属性的强大功能编写得更紧密：

<txp:images wraptag="figure">
    <img src="/images/<txp:image_info type="id, ext" />">
    <txp:image_info type="caption" wraptag="figcaption" />
</txp:images>

强调主要区别：

首先，我们从代码中删除了图片 ID 属性。这不是综合符号的反映，而是利用了“文章上下文”。在这种情况下，我们可以假设标记块用于文章的上下文，并且图像 ID 号已添加到应用该标记的文章的“文章图像”字段中。通过做这么多，我们不必将 ID 值声明为标签中的属性。<txp:images>``<txp:images>

接下来，_这是一个_集成符号的示例，我们添加了属性，它将整个图像包装在 HTML 容器中。使用此模式，如果没有与本文关联的图片，则会自动跳过标签，并且也不会应用相应的换行。因此，无需进行条件检查。wraptag``<figure>``<txp:images>``<figure>``<txp:if_article_image>

请注意，我们还通过同时声明图像 ID 和文件扩展名属性，将图像文件路径减少为单个实例。你不能对所有标签属性参数任意这样做，但在这种情况下是可能的，并且缩短结果是显而易见的。<txp:image_info />

最后，我们再次通过使用 Textpattern 的 presentational 属性来消除 HTML 标签的显式使用 .该属性是所有 Textpattern 标记的多个全局表示属性之一。<figcaption>``wraptag``image_info

此标记块的生成字符数为 149 个字符，在功能上与之前的长格式版本相同。比混合标记表示法略短，但与在混合方法中留下空标记相比，如果图像丢失，则具有跳过整个块的额外好处。无论哪种方式，它肯定比完整的 HTML 版本更长，但这是具有动态功能的代价。在更复杂的结构中可以获得更显着的收益。

使用短标签减少打字

从 Textpattern 4.7.0 开始，您可以使用短标签和快捷属性表示法来减少编写 Textpattern 标签时涉及的键入量。

要从此功能中受益，您必须在“首选项”面板中启用短标记功能。默认情况下，它是打开的，但在进一步深入研究本节之前值得检查。它受设置控制的原因是因为它的使用会带来_很小_的性能损失。通常没有什么值得打扰的 - 由于大量的解析器优化，在微秒级 - 但如果您有非常复杂的页面模板需求或容量有限的托管环境，并希望从 Textpattern 的精益框架中榨取每一盎司的性能，您可能希望禁用此功能。

短标签结构

首先，让我们回顾一些 Textpattern 标签的基础知识，其中包括插件标签的使用方式。文本模式标签名称可以是单个单词（即 ），也可以是带有下划线的复合名称（即 ）。标签也可以是自闭标签或容器标签。name``compound_name

短标签结构仅涉及具有复合名称的标签（包括插件标签），无论是自闭合的还是用作容器的。

这是一般规则：如果启用了短标签，并且标签具有复合名称，则可以：

  1. 删除前缀。txp:
  2. 将下划线的第一个实例与双冒号交换。::

因此，像 这样的自闭标签变成 。<txp:article_id />``<article::id />

容器标签，例如：

<txp:if_article_id>
    …
<txp:else />
    …
</txp:if_article_id>

成为：

<if::article_id>
    …
<txp:else />
    …
</if::article_id>

这同样适用于插件标签。例如这个：

<txp:smd_if>
    …
<txp:else />
    …
</txp:smd_if>

成为：

<smd::if>
    …
<smd::else />
    …
</smd::if>

请注意，在后一个示例中，插件前缀可用于标签，该标签仅与用作容器的插件标签相关。else

使用无价值属性来减少键入

标签以特殊方式解释没有任何给定值的属性。您可以像在 HTML 中一样快捷“布尔值”（1 或 0）属性。所以这两个标签是等价的：

<txp:section link="1" />
<txp:section link />

假设您需要显示包含任何信息的内容，即不为空。在 Textpattern 4.7.0 之前，您可以这样做：<txp:variable name="test" />

<txp:if_variable name="test" value="">
<txp:else />
    display something if variable has content
</txp:if_variable>

从 Textpattern 4.7.0 开始，这更简单：

<txp:if_variable name="test" value>
    display something if variable has content
</txp:if_variable>

在这种情况下，valueless 属性被解释为“一些不空的值”。对于其他标签，无价值属性的含义可能不同。通常，它们以最“自然”或“有用”的方式解释，如上所述。希望处理无值属性的插件开发人员应该注意，在内部，它们解析的值是布尔值。value``true

使用否定缩短标签结构

同样从 Textpattern 4.7.0 开始，可以使用 否定标签。not

<txp:if_section not name="contact, articles">
    <!-- Do something if we're not in the contact or articles section -->
</txp:if_section>

您可以使用以下方法之一来测试变量是否不包含值：

<txp:if_variable name="test" value="">
    display something if variable is empty
</txp:if_variable>
<txp:if_variable name="test" not value>
    display something if variable is empty
</txp:if_variable>

using 否定整个标签的结果，包括它可能具有的属性的任意组合。它不会否定单个属性。此功能还扩展到所有插件，无需插件作者执行任何作。not

自定义短标签：短代码

启用短标签后，您还可以通过创建特定的可重用表单模板（我们称之为“短代码”）来生成自定义短标签。创建短代码表单时，您可以使用任何表单类型。

短代码就像您可以在 Textpattern 表单中开发的任何其他部分代码一样，但它的设计目的是与相关的自定义短标签相关。这个新功能在概念上类似于 smd_macro 或 rah_beacon 插件，这两个插件现在都已经过时了，而不是这个新的自定义短标签/短代码功能。

核心短标签和自定义短标签之间的一个区别在于标签。每当您创建用作短代码表单的 Textpattern 表单时，它都会自动提供与表单同名的自定义短标签。<txp:output_form>

以前面的带有标题的图像为例，可以设计一个短代码表单来输出包装良好的图像作为 HTML 。如果您永远不需要其他类型的图形短代码表单，您甚至可以将表单命名为 figure。通过这样做，您现在有一个自定义短标签可用于：figure

<txp::figure />

注意双冒号：这很重要！

如果您将短代码命名为 _Form，imagefigure，则该标签将用作：

<txp::image_figure />

等等。

无论您是否选择在“首选项”面板中禁用短标签功能，您仍然可以使用短代码表单。如果它的名字不是纯字母数字，情况也是如此。无论哪种情况，都可以通过如下标记继续：output_form

<txp:output_form form="image_figure" />
<txp:output_form form="my figure" />

使用 yield 属性

如果需要，可以在标签中将属性显式定义为属性的值：yield

<txp::figure yield="id, caption" />

请注意，在以下示例中省略 and 属性意味着它们将被视为全局属性并相应地进行处理：class``wraptag

<txp::figure yield="id, caption" id="123" wraptag="div" class="picture" />

创建短代码表单的关键是使用 Textpattern 标签 ，以及与后者相关的 。yield``if_yield``else

该标签用于创建要在自定义标签中处理的属性：如果要设置默认值，以防该属性未传递到表单中，请将该属性添加到其中。yield``<txp:yield name="your-attribute" />``default

容器标记（和标记）可用于确定是否已提供属性：if_yield``else

<txp:if_yield name="your-attribute"> … </txp:if_yield>

就是这样！

解析器及其传递

Textpattern 解析器是在呈现页面时将标签转换为动态内容的主力。从本质上讲，它是一个线性解析器，这意味着它逐行、逐个标签地浏览您的页面模板和表单，外部标签递归调用内部标签。<txp:...>

如果你有相对简单的页面模板，它可以在一次扫描中完成此作 - 我们称之为传递。对于更复杂的用途 - 例如在存在某些标签依赖关系的情况下 - 解析器可能需要多个通道来转换所有标签。它会根据需要多次返回文档以转换所有标签，然后将最终结果呈现给网站访问者。每次它遍历页面时，它都会将传递计数器增加 1：传递 1、传递 2、传递 3，依此类推。

让我们举一个只需要一次传递的标签的简单示例：

<txp:article />
…
<txp:link_to_next>Next article</txp:link_to_next>

遇到第二个标签后，解析器拥有获取下一篇文章、处理标签并将其替换为准备显示的内容所需的所有信息。<txp:link_to_next />

延迟或延迟输出

现在，让我们更进一步。假设您希望将下一篇文章的链接显示在文章上方：

<txp:link_to_next>Next article</txp:link_to_next>
...
<txp:article />

这可能会抛出警告，因为您试图在 Textpattern 知道哪篇文章是当前文章之前显示指向下一篇文章的链接。

解析器的多次传递可以对您有利，以明确延迟处理，直到达到特定传递。这允许您控制在哪个阶段获取信息，从而允许您在稍后的阶段处理页面较早出现的标签。

该标签用于向解析器隐藏其内容，以便您可以在模板中放置注释，而不必担心它们出现在呈现给访问者的输出中。但它有一个属性，允许您控制内容的实际“隐藏”程度。<txp:hide />``process

如果为属性提供整数，则仅当达到指定传递时才会执行内容：process

<txp:hide process="2">
   <txp:link_to_next>Next article</txp:link_to_next>
</txp:hide>
...
<txp:article />

在第一次通过后，标签将被建立，以便 Textpattern 知道这是哪篇文章。因此，在第二遍中，可以安全地执行先前隐藏的内容，并将链接呈现在文章内容_上方_的屏幕上，即使内容是事后确定的。<txp:article>

实际上，标签“知道”它需要当前文章数据，因此如果这些数据尚不可用，它会自动推迟到下一次。因此，在这种情况下，您不需要手动“隐藏”它，但在更复杂的结构中可能需要更改解析顺序。<txp:link_to_next />

选项，选项......我该怎么办？

通过所讨论的内容，您似乎必须学习使用 Textpattern 标签的更高级方法。那不是真的。没有对错之道，只有让你更容易理解的方式。如果这是有意义的，那么编写混合标记并没有错。

人们的自然倾向是从混合标记方法开始，然后随着时间的推移通过更多地依赖 Textpattern 标签来收紧他们的标记。结果通常是总体上更少的加价。当使用此类功能时，这可以帮助抵消插件标签的额外标记。

但这不是给定的。有时需要更多的字符来完成真正复杂的事情——真正的文本模式魔法。因此，对综合优势持保留态度。

比字符数更重要的是您对生成的标记的理解——或者您的客户的标记，如果您正在构建一个网站并将其移交给不同的管理员——无论标记是如何编写的。只要标记将内容与静态结构分开，并且您（或客户端）理解它，您就做得很好。

总之，混合标记通常更容易让新的 Textpattern 用户掌握，直到他们更加熟悉 Textpattern 标签功能的范围。Textpattern 的高级用户通常更喜欢集成符号，因为它可以节省字符空间，并且通常以更少的条件提供更强大的结构。但无论哪种方式都无关紧要，只要标记是根据 Textpattern 的功能正确构造的。

标签参考索引

现在您已经了解了有关标签、属性、解析器、上下文以及这些组件如何交互的所有信息，您可以深入了解完整的标签引用，以发现 Textpattern 提供的许多标签，以帮助从数据库中获取动态内容并将其显示给网站访问者。

每个标签文档都表示：

  • 标记的类型（单个、容器或条件）。
  • 它的作用的描述。
  • 它接受的属性列表及其默认值。
  • 标记接受的常见表示属性列表，无论标记如何，这些属性通常功能相同。
  • 标记在上下文中的使用示例，有时与链接以实现快速导航的其他标记一起使用。
  • 标签的谱系，以便可以发现其发展历史和功能。

如果您只是想知道哪些属性被哪些标记使用，则该属叉引用会按字母顺序列出所有属性，以便您可以找到使用特定属性的特定标记。

现在就去释放 Textpattern 标签的力量，为您的网站访问者构建一些很棒的东西吧！


Categories Notes, Web