README

您是一名开发者，希望为Bricks构建器添加动态数据标签？这个包就是为您准备的。从现在开始，您只需3行代码就可以添加您的动态数据标签。它自动注册标签，解析过滤器，甚至允许您添加您自己的模式解析。

功能概述

• 动态数据标签的简单注册
• 自动解析过滤器
• 自定义模式解析
• 使用wp_kses进行输出过滤

安装

要安装此包，您可以使用composer。在您的终端中运行以下命令

composer require juvo/bricks-dynamic-data-tags

您应该尽早初始化注册。最佳位置是在您的插件主文件或主题的functions.php中。

add_action('init', function() {
    juvo\Bricks_Dynamic_Data_Tags\DDT_Registry::getInstance();
});

用法

要注册一个简单的动态数据标签，您可以使用以下代码片段。第一个参数是标签名称，第二个参数是标签标签，第三个参数是标签组，最后一个参数是返回标签输出的回调。

DDT_Registry::getInstance()
    ->set('my_tag', 'My Tag', 'My Tag Group', function($post, $context, array $filters = []) {
        return "Hello World";
    });

要向同一组注册另一个标签，只需这样做

DDT_Registry::getInstance()
    ->set('my_tag2', 'My Tag 2', 'My Tag Group', function($post, $context, array $filters = []) {
        return "Hello World 2";
    });

过滤注册的标签

juvo/register_dynamic_tags 过滤器允许您修改要注册的标签。此过滤器将此时添加的数据标签作为数组传递。您可以使用此功能删除标签。

apply_filters('juvo/dynamic_tags/register', $tags);

过滤标签模式

juvo/dynamic_data_tag/parse_tag 过滤器允许您修改所有标签的解析方式。此过滤器将标签模式和标签名称作为参数传递。它允许您为数据标签解析自定义结构。要添加传递给回调的新变量，请确保使用正则表达式将其作为命名捕获组添加。

// Adds "modifier" as a named capturing group to the tag pattern
add_filter("juvo/dynamic_data_tag/parse_tag", function($pattern, $tag) {
    $pattern = str_replace("}/", "", $pattern);
    return $pattern . "(\~(?<modifier>[0-9a-zA-Z_-]+(\~[0-9a-zA-Z_-]+)*))?}/";
}, 10, 2);

您的回调现在需要一个额外的参数

DDT_Registry::getInstance()->set( 'single_tag', 'Single Tag', 'Custom Tags', function( $post, $context, array $filters = [], array $modifier = [] )

按标签名称过滤标签模式

juvo/dynamic_data_tag/parse_tag 过滤器允许您修改特定标签的标签模式。

apply_filters("juvo/dynamic_data_tag/parse_tag/$tag", $pattern, $this->tag);

修改传递给回调的数据

如果您使用了其中一个parse_tag过滤器来向标签添加您自己的结构和变量，您可以使用此过滤器来修改该变量本身。例如，如果您可以将新的结构添加多次，则需要这样做。默认情况下，参数使用“:”分割，过滤器使用“|”分割。如果您添加了一个使用例如“~”分割的新结构，您应该使用此过滤器来相应地分割数据。

add_filter("juvo/dynamic_data_tag/parse_tag/pattern_modifier", function($value) {
    return explode("~", $value);
});

使用命名过滤器

您可以注册如下动态数据标签：{single_tag:tag=tag_slug:link=true}。在您的回调中，您需要解析过滤器值以处理键值对。此示例允许您显示标签，通过slug过滤要显示的标签，并过滤标签名称是否应该包裹在指向术语本身的链接中。

DDT_Registry::getInstance()->set( 'single_tag', 'Single Tag', 'Custom Tags', function( $post, $context, array $filters = [] ) {
    // Parse filters to be key-value pairs
    $parsed_filters = [];
    foreach ( $filters as &$item ) {
        list( $key, $value ) = explode( '=', $item );
        $parsed_filters[ $key ] = $value;
    }
    $filters = $parsed_filters;
    
    $tags = get_the_terms( get_the_ID(), 'post_tag' );
    if ( empty( $tags ) || is_wp_error( $tags ) ) {
        return '';
    }
    
    // Filter to select a specific tag
    $selected_tag = $filters['tag'] ?? '';
    $output       = [];
    
    foreach ( $tags as $tag ) {
        if ((!empty($selected_tag) && $tag->slug === $selected_tag) || empty($selected_tag)) {
    
            // Check if we need links or not
            if ( isset( $filters['link'] ) && $filters['link'] === 'true' ) {
                $output[] = '<a href="' . esc_url( get_term_link( $tag ) ) . '">' . esc_html( $tag->name ) . '</a>';
            } else {
                $output[] = esc_html( $tag->name );
            }
        }
    }
    
    return implode( ', ', $output );
    } );

在这个例子中

修改允许的HTML标签

回调的输出使用wp_kses进行过滤，以防止XSS攻击。您可以使用wp_kses_allowed_html过滤器修改允许的标签。此过滤器将允许的标签和上下文作为参数传递。您可以使用此功能修改允许的HTML标签。

add_filter("wp_kses_allowed_html", function($allowedtags, $context) {
    if ($context !== "juvo/dynamic_data_tag") {
        return $allowedtags;
    }
    $allowedtags['iframe'] = [
        'src' => true,
        'width' => true,
        'height' => true,
        'frameborder' => true,
        'allow' => true,
        'allowfullscreen' => true,
        'title' => true,
    ];
    return $allowedtags;
        }, 10, 2);

要为每个动态数据标签允许不同的HTML标签，还有一个特殊的钩子。如您在代码片段中所见，首先过滤通用标签，然后将其传递到特定于标签的过滤器。

$allowed_tags = wp_kses_allowed_html("juvo/dynamic_data_tag");
$allowed_tags = apply_filters("juvo/dynamic_data_tag/allowed_html_tags/$tag", $allowed_tags);

高级示例

iFrame

注册一个动态数据标签，该标签显示当前帖子嵌入的iFrame。

// Register '{collection}' tag
DDT_Registry::getInstance()
    ->set('collection', 'Collection', 'Collections', function($post, $context, array $filters = []) {
        return "<iframe src='" . get_permalink($post) . "'></iframe>";
    });

// Add custom allowed html tags for the collection tag. In this case we allow iframes.
add_filter("juvo/dynamic_data_tag/allowed_html_tags/collection", function($allowedtags) {
    $allowedtags['iframe'] = [
        'src' => true,
        'width' => true,
        'height' => true,
        'frameborder' => true,
        'allow' => true,
        'allowfullscreen' => true,
        'title' => true,
    ];
    return $allowedtags;
});

帖子数据

将动态数据标签 {post_data} 注册以显示帖子数据。一个过滤器可以用来选择显示哪些数据。另一个自定义过滤器“粗体”可以用来标记某些数据使其加粗。标签可以这样使用：{post_data:title:post_type~bold=post_type~bold=title} 将显示为 "标题，帖子类型"。

DDT_Registry::getInstance()->set(
    'post_data',
    'Post Data',
    'Posts',
    function( \WP_Post $post, string $context, array $filters= [], array $bold = [] ) {

        $output = [];
        foreach ( $filters as $filter ) {
            switch ( $filter ) {
                case 'title':
                    $output['title'] = get_the_title();
                    break;
                case 'excerpt':
                    $output['excerpt'] = get_the_excerpt();
                    break;
                case 'content':
                    $output['content'] = get_the_content();
                    break;
                case 'post_type':
                    $output['post_type'] = get_post_type();
                    break;
            }
        }

        // Add some of the filtered values tobe bold
        foreach($bold as $key) {
            if (in_array($key, $filters)) {
                $output[$key] = "<b>".$output[$key]."</b>";
            }
        }

        return implode( ', ', $output );
    }
);

// Add a custom pattern to introduce a "bold" capture group.
add_filter("juvo/dynamic_data_tag/parse_tag/post_data", function($pattern, $tag) {
    $pattern = str_replace("}/", "", $pattern);
    return $pattern . "(?:~bold=(?<bold>[0-9a-zA-Z_-]+))*}/"; // use ~bold= as separator
}, 10, 2);

// To allow the freshly added "bold" capture group to have multiple values we need to split the values by the separator
add_filter("juvo/dynamic_data_tag/parse_tag/pattern_bold", function($value) {
    return explode("~bold=", $value);
});