README

配置驱动的 WordPress 短代码。

这是一个 WordPress 短代码组件，允许您通过配置文件定义短代码，包括依赖项、本地化和 Shortcake UI。

安装

使用此组件的最佳方式是通过 Composer

composer require brightnucleus/shortcodes

基本用法

要使用此组件，您需要

实例化 ShortcodeManager 类；
通过其构造函数注入实现 BrightNucleus\Config\ConfigInterface 的对象；
调用其 register() 方法。

use BrightNucleus\Config\ConfigFactory;
use BrightNucleus\Shortcode\ShortcodeManager;

$config = ConfigFactory::create( __DIR__ . '/../config/example_config.php');
$shortcode_manager = new ShortcodeManager(
	$config->getSubConfig( 'ShortcodeManager' )
);
$shortcode_manager->register();

配置架构

$shortcodes_config = [

	/* For each shortcode you wish to define, you'll need one separate entry at
	 * the root config entry passed in to ShortcodeManager. The name of that
	 * entry is used as the shortcode tag.
	 */
	'shortcode_tag' => [

		/* Path to a template that is used to render the shortcode.
		 * The path is relative to the configuration file.
		 */
		'view' => __DIR__ . '/../views/shortcodes/view_file.php',

		/* Customised ShortcodeInterface implementation. (optional)
		 * You can use this to completely customize the standard shortcode
		 * class behavior.
		 * Omit to use default `Shortcode` class.
		 * This can be either a fully qualified class name or a callable.
		 */
		'custom_class' => '\BrightNucleus\Shortcodes\Shortcode',

		/* Customised ShortcodeAttsParserInterface implementation. (optional)
		 * You can use this to completely customize the way shortcode attributes
		 * are parsed.
		 * Omit to use default `ShortcodeAttsParser` class.
		 * This can be either a fully qualified class name or a callable.
		 */
		'custom_atts_parser' => '\BrightNucleus\Shortcodes\ShortcodeAttsParser',

		/* Collection of attributes that can be used with the shortcode.
		 * These attributes will be processed by the
		 * `ShortcodeAttsParserInterface` implementation that is being used.
		 */
		'atts' => [

			/* Shortcode attribute name.
			 * These are the optional attributes that you can append to your
			 * shortcode within the WP editor: [shortcode att_name='value'].
			 * NB: lower-cased by WP, so no camelCase or UPPER_CASE.
			 */
			'attribute_name'    => [

				/* Provided that you use the default `ShortcodeAttsParser`
				 * implementation, you can define a `default` value for each
				 * attribute, as well as an optional `validate` callable that
				 * gets evaluated to a boolean.
				 */
				'default'  => 'default_value',
				'validate' => function ( $att ) {
					return some_validation_function( $att );
				},
			],
		],

		/* Customised ShortcodeUIInterface implementation. (optional)
		 * You can use this to completely customize the standard shortcode
		 * user interface class behavior.
		 * Omit to use default `ShortcodeUI` class.
		 * This can be either a fully qualified class name or a callable.
		 */
		'custom_ui' => '\BrightNucleus\Shortcodes\ShortcodeUI',

		/* Besides one additional keys that ShortcodeManager recognizes, the
		 * 'ui' subkey gets passed as is to the Shortcake UI plugin.
		 * Refer to the Shortcake documentation for details about the syntax:
		 * https://github.com/wp-shortcake/shortcake/wiki/Registering-Shortcode-UI
		 */
		'ui'   => [

			/* Whether the shortcode UI (along with its dependencies) is needed
			 * within the current context or not. If this is a callable, it gets
			 * executed and its result evaluated to boolean.
			 */
			'is_needed' => function ( $context ) {
				return true;
			},

			// [ Shortcake configuration keys. ]

		],
	]
];

注册基本短代码

对于以下示例，我们将注册一个新的短代码，提供一个简单的 [button] 短代码。我们希望短代码可以通过 Shortcake 进行配置。

配置文件

首先，我们需要通过配置文件定义短代码。

<?php namespace Example\Plugin;

/* ShortcodeManager configuration.
 */
$shortcodes = [
	// Let's define a new button.
	'button'          => [
		'view' => __DIR__ . '/../views/shortcodes/button.php',
		'atts' => [
			// It will accept a caption...
			'caption' => [
				'validate' => function ( $att ) {
					return ( null !== $att )
						? esc_attr( $att )
						: null;
				},
				'default'  => 'Straight to Google!',
			],
			// ...and a URL.
			'url'     => [
				'validate' => function ( $att ) {
					return ( null !== $att )
						? esc_attr( $att )
						: null;
				},
				'default'  => 'https://www.google.com/',
			],
		],
		// We also want a user interface for that button.
		'ui'   => [
			// Let's call it "Example Button".
			'label'         => esc_html__(
				'Example Button',
				'example-plugin'
			),
			'listItemImage' => 'dashicons-search',
			// We only want to make it available when editing a "page".
			'post_type'     => [ 'page' ],
			// It is always needed, so no extra checks to load it conditionally.
			'is_needed'     => function ( $context ) { return true; },
			// We also need to configure the Shortcake input fields.
			'attrs'         => [
				[
					'label'       => esc_html__(
						'Caption',
						'example-plugin'
					),
					'description' => esc_html__(
						'The caption that is shown on the button.',
						'example-plugin'
					),
					'attr'        => 'caption',
					'type'        => 'text',
					'value'       => 'Straight to Google!',
				],
				[
					'label'       => esc_html__(
						'URL',
						'example-plugin'
					),
					'description' => esc_html__(
						'Target URL where the button will lead to when pressed.',
						'example-plugin'
					),
					'attr'        => 'url',
					'type'        => 'url',
					'value'       => 'https://www.google.com/',
				],
			],
		],
	],
];

/* Plugin settings.
 */
$plugin_settings = [
	'ShortcodeManager'  => $shortcodes,
];

/* Return with Vendor/Package prefix.
 */
return [
	'Example' => [
		'Plugin' => $plugin_settings,
	],
];

模板文件

然后，我们需要编写一个可以被短代码渲染的模板。

<?php namespace Example\Plugin;

/**
 * Button Shortcode Template
 */

// The `$atts` array (as well as the inner `$content` variable) will be
// available from within this template.

?>
<div class="example button class">
	<a class="button radius"
	href="<?php echo esc_url( $atts['url'] ); ?>"><?php echo esc_html( $atts['caption'] ); ?></a>
</div>

初始化

最后，我们需要使用配置文件初始化 ShortcodeManager，并让它 register() 其短代码。

<?php namespace Example\Plugin;

use BrightNucleus\Config\ConfigFactory;
use BrightNucleus\Shortcode\ShortcodeManager;

const PLUGIN_PREFIX            = 'Example\Plugin';
const SHORTCODE_MANAGER_PREFIX = 'ShortcodeManager';

// If this file is called directly, abort.
if ( ! defined( 'WPINC' ) ) {
	die;
}

// Load Composer autoloader.
if ( file_exists( __DIR__ . '/vendor/autoload.php' ) ) {
	require_once __DIR__ . '/vendor/autoload.php';
}

// Load configuration file.
$config = ConfigFactory::create( __DIR__ . '/config/example.php' );

// Initialize Shortcode Manager.
$shortcode_manager = new ShortcodeManager(
	$config->getSubConfig( PLUGIN_PREFIX, SHORTCODE_MANAGER_PREFIX )
);

// Hook Shortcode Manager up to WordPress action.
\add_action( 'init', [ $shortcode_manager, 'register' ] );

使用自定义类

以下接口的实际实现可以通过配置文件进行更改

BrightNucleus\Shortcode\ShortcodeInterface
BrightNucleus\Shortcode\ShortcodeAttsParserInterface
BrightNucleus\Shortcode\ShortcodeUIInterface

配置文件接受一个键来覆盖这些中的每一个。您可以通过完全限定的类名或作为工厂的调用传递。

当使用调用时，传递给该调用的参数与为这些的默认实现构造函数得到的参数相同。

使用相对视图

底层实现使用 brightnucleus/view 包来渲染每个短代码的实际视图。默认行为已经处理了绝对路径，并且可以渲染 Views 引擎可以处理的所有类型的视图。如果没有注入 ViewBuilder 的特定实例，则 ShortcodeManager 将依赖于由 Views Facade 提供的实例。

要调整视图引擎查找相对视图 URI 的位置或配置可用的渲染引擎，您可以调整通过 Facade 可用集中实例化的实例，或者，更理想的是，将您自己的自定义 ViewBuilder 实例注入到 ShortcodeManager 中作为第三个构造函数参数。

一旦您以这种方式添加了一个或多个位置，您就可以在配置文件中使用相对 URI。它们甚至不需要包含扩展名，只要视图构建器已知的引擎可以推断出来即可。这使得在以后覆盖视图非常灵活，不仅可以覆盖插件中定义的短代码的标记，还可以使用与最初使用的不同的引擎。

有关如何配置 ViewBuilder 实例的说明，请参阅 brightnucleus/view 文档。

添加额外上下文

默认实现允许您向短代码添加add_context()，这将随后也传递给视图进行渲染。

例如，可以使用依赖注入器，在短代码已实例化后进一步准备带有额外数据的短代码。

使用外部 DI

要使用默认的Shortcode实现与外部依赖注入器，您可以将提供make( $class, $args )方法的对象传递给Shortcode::with_injector()方法。

您可能需要提供一个适配器来根据需要修改$args参数。

贡献

欢迎提供反馈/错误报告/拉取请求。

许可协议

本代码根据MIT许可证授权。

brightnucleus / shortcodes

维护者

详情