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 将作为指定文件夹下的子文件夹安装。

将 Queulat 作为 mu-plugin 加载

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_Map
• 输入
  • 输入文本
  • 隐藏输入
  • 输入邮箱
  • 复选框输入
  • 数字输入
  • 单选框输入
  • 提交输入
  • URL输入
• Recaptcha
• 选择
• 文本区域
• UI_Select2
• WP_Editor
• WP_Gallery
• WP_Image
• WP_Media
• WP_Nonce
• 是_否

验证表单

@todo

创建新的表单视图

@todo

使用Node_Factory实例化表单元素

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

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

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

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

• 属性：HTML元素属性，如class、id、type等，作为关联数组。
• 子元素：嵌套元素，也可以使用Node_Factory作为数组创建。
• 标签：用于标记表单元素的文本。
• 名称：用于表单提交的字段“name”。
• 选项：元素选项的关联数组（用于如输入单选框、复选框、选择等字段）。
• 属性：用于表单视图或什么的任意节点属性数组，作为关联数组。
• 节点文本内容。
• 值：表单字段值。

不支持的元素参数将被跳过。

你可以使用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

实现此接口的对象（元素或组件）用作表单对象。它们有一个"名称"，用于将数据发送到服务器，一个"值"和一个"标签"。

Form_Control_Trait帮助实现此接口中的"标签"和"名称"的获取器和设置器。"值"的获取器和设置器应由您自己的自定义组件定义。

Node_List_Interface

扩展ArrayAccess、SeekableIterator、Countable和Serializable。

通常用于从Node获取类似数组的子集。

Option_Node_Interface

由复选框、单选按钮、选择框以及用户可以选择的任何组件（他们可以选择多个选项）等控件使用。

使用Options_Trait来帮助实现此接口。

Properties_Interface

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

使用Properties_Trait来帮助实现此接口。

View_Interface

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