README

Tree Methods 是一个为 Kirby 3 设计的插件，用于将字段值转换为 HTML 并通过更改标题层次结构、包装和过滤元素、操作标签名称、添加类或其它属性来适配生成的标记。该插件的主要目的是获取通常由格式化程序返回的静态字符串字段标记，并帮助网页设计师按照他们的需求调整它，并应用排版调整。因此，它允许

1. 选择和过滤内容,
2. 操作生成的标记,
3. 输出 HTML.

该插件与所有允许生成有效 HTML 的 Kirby 字段一起工作，如 Blocks 或 textareas。它还接受自定义方法将字段值转换为 HTML。

示例

操作标题层次结构

内容

Text:

# My first headline

## My second headline

模板

// Set the starting headline level to three,
// making the document start as `h3` instead of `h1`
<?= $page->text()->toTree()->level(3) ?>

输出

<h3>My first headline</h3>
<h4>My second headline</h4>

使用片段操作标记

内容

Text:

These are Markdown paragraphs that an editor wrote that needs to be wrapped with special markup.

But the editor shouldn't have to care about markup in his Markdown document.

模板

<?= $page->text()->toTree()->snippets('elements') ?>

片段 /site/snippets/elements/p.php

<div class="wrapper">
    <p<?=e($position === 1, 'class="intro"')?>>
        <?= $content ?>
    </p>
</div>

输出

<div class="wrapper">
    <p class="intro">These are Markdown paragraphs that an editor wrote that needs to be wrapped with special markup.</p>
</div>
<div class="wrapper">
    <p>But the editor shouldn't have to care about markup in his Markdown document.</p>
</div>

更改元素

字段值

This is _HTML_.

模板

<?= $page
    ->text()
    ->toTree()
    ->select('//em[text() = "HTML"]')
    ->setName('abbr')
    ->setAttribute('title' => 'HyperText Markup Language')
    ->clear()
    ->html() ?>

输出

<p>This is <abbr title="HyperText Markup Language">HTML</abbr>.</p>

包装元素

字段值

Text:

**Me:** May I ask a question?<

**You:** Yes, of course, you may!

What's your question?

模板

// Group elements, starting each group with a `strong` element
$page
    ->text()
    ->toTree()
    ->wrap()
        'div',
        'p[strong]',
        'p[following-sibling::*[1][strong]]',
        [
            'class' => 'question-or-answer',
        ]
    );

输出

<div class="question-or-answer">
    <p><strong>Me:</strong> May I ask a question?</p>
</div>
<div class="question-or-answer">
    <p><strong>You:</strong> Yes, of course, you may!</p>
    <p>What's your question?</p>
</div>

安装

下载

下载并将此存储库复制到 /site/plugins/tree-methods。

Git 子模块

git submodule add https://github.com/hananils/kirby-tree-methods.git site/plugins/tree-methods

Composer

composer require hananils/kirby-tree-methods

字段方法

在内部，该插件使用 DomDocument->loadHTML() 将 HTML 字符串转换为 DomDocument。内容预期使用 UTF8 编码。XPath 用于在树中过滤和查找元素，请参阅 https://en.wikipedia.org/wiki/XPath#Syntax_and_semantics_(XPath_1.0)。

toTree($formatter)

使用给定的格式化程序将字段值转换为 DOM 树。

• $formatter: 用于将字段内容转换为 HTML 的字段方法，例如 kirbytext 或 toBlocks。默认为 kirbytext。

全局默认值可以通过在配置中定义 hananils.tree.formatter 来设置。

选择

给定一个名为 text 的字段和 $tree = $page->text()->toTree()

$tree->select($xpath)

选择所有与给定 xPath 查询匹配的元素。

• $xpath: xPath 查询，请参阅 https://en.wikipedia.org/wiki/XPath

// Select all paragraphs
$tree->select('p');

$tree->first()

选择第一个元素。

$tree->last()

选择最后一个元素。

$tree->nth($position)

选择第 n 个元素。

• $position: 元素的位置

$tree->limit($number)

将当前选择限制为给定数量。

• $number: 限制。

$tree->offset(1)

将当前选择偏移给定数量。

• $number: 偏移。

$tree->clear()

清除当前选择并再次选择所有节点（保留所有操作）。

$isEmpty()

如果当前选择为空，则返回 true。

$isNotEmpty()

如果当前选择不为空，则返回 true。

has($query)

如果当前选择包含给定的元素，则返回 true。

• $query: 一个 xPath 查询，可以是元素的名称等简单。

count()

计算当前选择中的节点数。

操作

给定一个名为 text 的字段和 $tree = $page->text()->toTree()

$tree->level($start)

将标题层次结构调整为从给定级别开始。

• $start: 标题开始使用的级别。

// Make all `h1` a `h3`, all `h2` a `h4` …
$tree->level(3);

$tree->select($xpath)->setName($name)

选择所有匹配给定XPath查询的元素并更新元素名称。

• $xpath: xPath 查询，请参阅 https://en.wikipedia.org/wiki/XPath
• $name: 新的元素名称。

// Rename all `strong` to `em`
$tree->select('//strong')->setName('em');

$tree->select($xpath)->setAttribute($attribute, $value)

选择所有匹配给定XPath查询的元素并设置给定属性。

• $xpath: xPath 查询，请参阅 https://en.wikipedia.org/wiki/XPath
• $attribute: 属性名称。 $value: 属性值。

// Set the class `example` to all paragraphs
$tree->select('p')->setAttribute('class', 'example');

$tree->wrap($element, $from, $name, $attributes)

将给定元素中的所有元素（从……到）包裹起来，如果定义了则添加属性。

• $element: 包裹元素的名称。
• $from: 起始元素的XPath查询，见 https://en.wikipedia。
• $to: 结束元素的XPath查询，见 https://en.wikipedia。
• $attributes: 要设置在包裹元素上的属性数组。

$tree->wrap('div', 'h1', 'h2', ['class' => 'example']);

$tree->wrapText($string, $element, $attributes)

将给定元素中的所有字符串出现包裹起来，如果定义了则添加属性。

• $string: 要搜索的字符串。
• $element: 包裹元素的名称。
• $attributes: 要设置在包裹元素上的属性数组。

$tree->wrapText('Kirby', 'strong', ['class' => 'is-great']);

snippets($path, $data)

将片段应用于当前选择中的每个元素。首先查找具有元素名称的片段，其次使用名为 default 的片段，如果找不到则不更改元素。

• $path: 在片段文件夹中查找元素片段的路径。
• $data: 应传递给片段的附加数据。

默认情况下，每个片段都会传递这些数据

• $parent: 父字段，例如 $page 或 $site。
• $field: 字段。
• $node: DOM节点。
• $content: 元素的内HTML。
• $attrs: 元素现有的属性。
• $next: 下一个元素。
• $prev: 上一个元素。
• $position: 当前元素的位置。
• $positionOfType: 当前元素与其类型元素的相对位置。

请参阅介绍中的示例。

widont()

改进版本的Kirby方法，考虑DOM。

excerpt()

对Kirby方法的别名。

kirbytextinline()

改进版本的Kirby方法，考虑DOM。

smartypants()

改进版本的Kirby方法，考虑DOM。

输出

给定一个名为 text 的字段和 $tree = $page->text()->toTree()

$tree->html($clear)

返回当前选择的HTML。

• $clear: 是否清除当前选择的布尔标志，默认为 false。

$tree->content($clear)

返回当前选择的内容（文本和子节点）。

• $clear: 是否清除当前选择的布尔标志，默认为 false。

$tree->text($clear)

返回当前选择的文本值。

• $clear: 是否清除当前选择的布尔标志，默认为 false。

$tree->toDocument()

返回DomDocument对象。

$tree->toSelection()

返回当前选择的DomNodeList。

$tree->toField($type)

返回具有字段值设置为当前HTML（默认）、内容或文本值的字段实例。

• $type: 返回的内容类型，可以是 html、content 或 text。

许可证

此插件由 MIT许可证 提供，由 hana+nils · Büro für Gestaltung。
我们为数字和模拟媒体创建视觉设计。