README

使用 Composer 安装

composer require felipelavinz/queulat:dev-master

Composer 将会在 wp-content/mu-plugins/queulat 上安装

如果您需要在不同的文件夹中安装，您应该在项目的 composer.json 中添加类似以下的内容

{
	"extra" : {
		"installer-paths" : {
			"htdocs/wp-content/mu-plugins/{$name}" : ["type:wordpress-muplugin"]
		}
	}
}

其中 htdocs/wp-content/mu-plugins/{$name} 是您 mu-plugins 目录的路径。Queulat 将作为指定文件夹下的子文件夹安装。

作为 mu-plugin 加载 Queulat

Queulat 使用 Composer 自动加载器来延迟加载大部分代码，因此您需要确保在初始化 Queulat 之前包含自动加载器。

此外，由于安装在子文件夹中的 mu-plugins 不会被 WordPress 自动加载，您必须手动包含主文件。

您可以通过在 mu-plugins 文件夹中添加单个文件来解决此问题，例如

<?php
/**
 * Plugin Name: Queulat Loader
 * Description: Load Queulat mu-plugin
 */

// Load Composer autoloader (ABSPATH it's the path to wp-load.php).
require_once ABSPATH .'/../vendor/autoload.php';

// Load Queulat main file.
require_once __DIR__ .'/queulat/queulat.php';

插件头部是可选的，但建议使用。

您也可以使用类似 Bedrock 的自动加载器，该自动加载器将加载所有安装在子文件夹中的 mu-plugins（您只需在 mu-plugin 文件夹中复制该文件，它将自动加载 Queulat）。

利用 Queulat 与 WordPress 架构

Queulat 致力于 改进我们为 WordPress 创建事物的方式，因此它不是从根本上改变它，而是试图使用熟悉的概念来构建更好的结构化事物，使用 自定义文章类型、自定义文章查询 和 自定义文章对象。

您可以使用它自己的 自定义文章类型插件生成器 来生成这些，该生成器在“工具”菜单上的管理员用户可用。

类型、查询和对象

每个自定义文章类型插件都由以下组成

• 一个入口文件，用于初始化插件
• 一个文章类型定义，例如：Song_Post_Type。这个类定义了注册文章类型到 WordPress 上的标签和其他参数。默认情况下，插件激活将为管理员添加所需的权限并刷新重写。如果您需要为文章类型定义自定义挂钩以提供额外功能，可以扩展这个类。
• 一个查询定义，如 Song_Post_Query。您可以使用这个类创建新的数据库查询，使用您可能希望为这种类型的内容定义的任何默认参数，并使用简单的 foreach 迭代结果，而不是经典的 WordPress 循环。
• 一个对象定义：Song_Post_Object，当使用自定义查询时将在 foreach 循环中返回。这样，您就可以向这个类添加任何自定义方法，这些方法将在 foreach 循环中可用。

使用 Queulat，您可以这样做

$tracklist = new Song_Post_Query( array(
	'tax_query'      => array(
		array(
			'taxonomy' => 'albums',
			'term'     => 'dark-side-of-the-moon',
			'field'    => 'slug'
		)
	)
) );

foreach ( $tracklist as $track ) {
	echo $track->title();
	echo $track->duration();
	echo $track->lyrics();
}

文章类型

@todo

文章查询

@todo

文章对象

@todo

元数据框

目前，在文章对象上定义元数据的主要方法是创建元数据框；扩展包含的 Queulat\Metabox 抽象类。

扩展类 必须 实现 get_fields( ) : array 和 sanitize_data( array $data ) : array 抽象方法；例如

<?php

use Queulat\Metabox;
use Queulat\Forms\Node_Factory;
use Queulat\Forms\Element\Input_Text;

class Track_Meta_Box extends Metabox {
	/**
	 * Must return the list of form fields to be included on this meta box
	 *
	 * @return Queulat\Forms\Node_Interface[] Array of form fields.
	 **/
	public function get_fields() : array {
		return array(
			Node_Factory::make(
				Input_Text::class,
				array(
					'name'                   => 'length',
					'label'                  => 'Track length',
					'attributes.class'       => 'regular-text',
					'properties.description' => _x( 'Track duration, such as: 01:23:45 (1 hour, 23 minutes, 45 seconds)', 'length field description', 'track_cpt' ),
				)
			),
			Node_Factory::class(
				Input_Checkbox::class,
				array(
					'name'  => 'colour',
					'label' => 'Colour',
					'options' => array(
						'red'   => 'Red',
						'green' => 'Green',
						'blue'  => 'Blue',
						'any'   => 'Any colour'
					)
				)
			)
		);
	}

	/**
	 * Sanitize data from the metabox form.
	 *
	 * @param array $data Form data from the meta box (not the full $_POST).
	 * @return array Sanitized data.
	 **/
	public function sanitize_data( array $data ) : array {
		return queulat_sanitizer( $data, array(
			'length'   => array( 'sanitize_text' ),
			'colour.*' => array( 'sanitize_key' )
		) );
	}
}

Queulat 负责更新提交的数据作为文章元字段，并在元数据框表单中加载已保存的值。

对于数据清理，您可以使用您喜欢的任何方法。引用的 queulat_sanitizer() 函数是应用来自 $data 输入的匹配值的回调的一个相当简单的方法。您可以使用 * 匹配所有属性（使用点符号）。

请参阅有关可用表单字段或如何创建自己的表单的部分（使用 Queulat 表单）[#using-queulat-forms]，获取更多信息。

创建管理页面

使用 Queulat 表单

@todo: 添加一般描述

可用表单字段

@todo: 为每个表单字段添加描述

• 按钮
• Div
• Fieldset
• 表单
• Google 地图
• 输入
  • 输入文本
  • 隐藏输入
  • 电子邮件输入
  • 复选框输入
  • 数字输入
  • 单选按钮输入
  • 提交输入
  • URL 输入
• Recaptcha
• 选择
• 文本区域
• UI_Select2
• WP 编辑器
• WP 相册
• WP 图片
• WP 媒体
• WP_Nonce
• 是/否

验证表单

@todo

创建新的表单视图

@todo

使用 Node_Factory 实例化表单元素

Node_Factory是一个简单的工厂类，能够创建任何类型的表单元素。

它公开一个单独的make方法，可以实例化和配置一个元素。此方法接受两个参数：

1. 一个字符串形式的“元素名称”，该名称应该是表单元素或组件的完全限定名称。
2. 一个关联数组形式的“参数”，用于配置对象。

默认情况下，Queulat 配置为处理以下属性：

• attributes: HTML 元素属性，如 class、id、type 等；作为关联数组。
• children: 嵌套元素，也可以使用 Node_Factory 作为数组创建。
• label: 标识表单元素的文本。
• name: 表单提交时使用的字段 "name"。
• options: 元素选项的关联数组（例如输入单选按钮、复选框、选择等）。
• properties: 可以由表单视图或任何其他东西使用的任意节点属性的数组。
• text_content: 节点的文本内容。
• value: 表单字段值。

不支持元素参数将被忽略。

您可以使用Node_Factory::register_argument()扩展支持的参数。

用法

<?php

use Queulat\Forms\Element\Div;
use Queulat\Forms\Node_Factory;
use Queulat\Forms\Element\Button;

$submit = Node_Factory::make(
	Div::class, array(
		'attributes' => array(
			'class'  => 'col-md-4 col-md-offset-8',
			'id'     => 'form-buttons'
		),
		'text_content' => '* required field',
		'children'     => array(
			Node_Factory::make(
				Button::class,
				'attributes' => array(
					'class'  => 'btn-lg',
					'type'   => 'submit'
				),
				'text_content' => 'Submit'
			)
		)
	);
);

echo $submit;

Node_Factory

注册新参数处理程序

您可以使用register_argument方法注册 Node_Factory 使用的新参数。

此方法接受一个Node_Factory_Argument_Handler，需要：

• 一个$argument（字符串），即您将处理的参数键的名称。
• 一个$method（字符串），即接收工厂方法参数的方法的名称。
• 一个可选的$call_type（字符串），它确定$method 如何处理接收到的配置值。

$call_type可以是以下之一：

Node_Factory::CALL_TYPE_VALUE：将所有参数作为单个数组传递给处理程序。这是默认设置。示例：$obj->$method( $args );

Node_Factory::CALL_ARRAY：将参数作为单独的参数传递给处理程序。示例：call_user_func_array( [ $obj, $method ], $args );

Node_Factory::CALL_KEY_VALUE：对于每个项目在参数中，将键和值作为参数传递给处理程序。示例

foreach ( $args as $key => $val ) {
	$obj->$method( $key, $val );
}

Node_Factory::CALL_TYPE_VALUE_ITEMS：对于参数中的每个项目，使用值作为处理程序的参数。示例：array_walk( $args, [ $obj, $method ] );

接口

Node_Interface

节点是应与表单一起使用的最低级别的对象

使用 Node_Trait 帮助实现此接口或 Childless_Node_Trait。一般来说，元素应该使用前者，而组件应该使用后者。

Component_Interface

扩展 Node_Interface 和 Attributes_Interface。

Element_Interface

扩展 Node_Interface 和 Attributes_Interface。此外，还添加了 get_tag_name 方法。

HTML_Element_Interface

扩展 Element_Interface 和 Properties_Interface。

Form_Element_Interface

扩展 HTML_Element_Interface 和 Form_Node_Interface。

Attributes_Interface

"Attributes" 是实现此接口的对象使用的特殊属性。它们被渲染为 HTML 属性 key="val"

使用 Attributes_Trait 帮助实现此接口。

Form_Node_Interface

实现此接口的对象（元素或组件）用作表单对象。它们具有一个“name”，用于将数据发送到服务器，一个“value”和一个“label”。

Form_Control_Trait 帮助实现此接口中的“label”和“name”获取器和设置器。应由您的自定义组件定义“value”获取器和设置器。

Node_List_Interface

扩展了 ArrayAccess、SeekableIterator、Countable 和 Serializable。

通常用于从一个节点获取类似数组的子节点集。

Option_Node_Interface

由复选框、单选按钮、选择框以及所有向用户提供多个选择组件的控件使用。

使用 Options_Trait 帮助实现此接口。

Properties_Interface

节点属性（不要与常规对象属性混淆）可以存储任意数据，如视图设置、错误数据或验证状态。

使用 Properties_Trait 帮助实现此接口。

View_Interface

用于表单视图的基本接口。