CMB2是一个开发者工具包,用于为WordPress创建元框表、自定义字段和表单,让你大开眼界。 您可以轻松管理帖子、术语、用户、评论的元数据,或创建自定义选项页面。
CMB2 是对 WordPress 自定义元框和字段的完全重写。 要开始使用,请按照附带的example-functions.php
文件中的示例操作,并查看基本使用说明。
您可以在此查看可用字段类型的列表。
(起步入门参考:https://github.com/CMB2/CMB2/wiki/Basic-Usage)
功能
- 创建元方框,用于帖子编辑界面。
- 创建用于选项页面的表单。
- 创建表单来处理用户元,并将其显示在用户配置文件添加/编辑页面上。
- 创建表单来处理术语元,并在使用分类法的任何地方显示。
- 灵活的应用程序接口(API)允许您在几乎任何地方使用 CMB 表单,甚至在前端也是如此。
- 包含多种字段类型。
- 自定义 API 钩子允许你创建自己的字段类型。
- 还有许多钩子和过滤器,让您可以修改库的许多方面(无需直接编辑)。
- 支持大多数字段类型的可重复字段以及可重复字段组。
- CMB2 可以安全地与任何项目捆绑。 它只会加载系统中的新版本。
翻译
如果您希望提供语言翻译文件,请通过WordPress 插件翻译进行。
文档
- CMB2 文档可在 github 上的CMB2 维基中找到。 此外,如果您喜欢阅读代码和内联文档,我们会尽量保留所有函数和方法的内联文档。
第三方资源
Custom Field Types
- CMB2 字段类型: CMB 附加帖子字段 源自coreymcollins:
custom_attached_posts
,用于将帖子附加到页面。 - CMB2 字段类型: 帖子搜索 Ajax byalexis-magina:
post_search_ajax
将帖子相互附加。 方法与CMB2 附加帖子字段相同,但使用 Ajax 请求、多/单选项和不同的用户界面。 - CMB2 字段类型: Ajax 搜索 fromrubengc: 3 个不同的字段,在 AJAX 中具有相同的用户界面,可以搜索(使用查询参数)用户、帖子类型和分类术语。
- CMB2 字段类型: CMB2 用户搜索字段 源自Mte90:
user_search_text
增加了一个用户搜索对话框,用于搜索/附加其他用户 ID。 - CMB2 字段类型: 谷歌地图 来自mustardBees: 用于谷歌地图的自定义字段类型。
pw_map
字段存储纬度/经度值,您可以使用这些值在主题中显示地图。 - CMB2 字段类型: 传单地图 来自villeristi: 传单地图的自定义字段类型。
- CMB2 字段类型: Select2 来自mustardBees: 使用Select2脚本的自定义字段类型:
- The
pw_select field
acts much like the default select field. However, it adds typeahead-style search allowing you to quickly make a selection from a large list - The
pw_multiselect
field allows you to select multiple values with typeahead-style search. The values can be dragged and dropped to reorder
- The
- CMB Field Type: Slider from mattkrupnik: Adds a jQuery UI Slider field.
- WDS CMB2 Date Range Field from dustyf of WebDevStudios: Adds a date range field.
- CMB2 Remote Image Select from JayWood of WebDevStudios: Allows users to enter a URL in a text field and select a single image for use in post meta. Similar to Facebook’s featured image selector.
- CMB Field Type: Sorter: This plugin gives you two CMB field types based on the Sorter script.
- CMB Field Type: Tags: WordPress-Tags-like field type for CMB2. note: this does not set the post tags, but simply provides a unique text input
- CMB Field Type: Link Picker: Using the Link Picker for CMB2 control, you can choose a link from your WordPress site, or manually enter a link. You can also identify if the link should open in a new window, or not.
- CMB Field Type: MultidatesPicker: Creates a CMB2 field type that enables a multiple date calendar. It uses a plugin called MultiDatesPicker v1.6.3 for jQuery UI.
- CMB Field Type: CMB2-radio-image: Image as radio buttons.
- CMB2 Term Select: Special CMB2 Field that allows users to define an autocomplete text field for terms. Note: this will set the taxonomy terms, but has the option (
'apply_term' => false
) to disable and save the term ids as data instead (like for options pages, etc). - CMB2 Related Links: Allows users to add a related links via a repeating field group. Field inputs are powered by the CMB2 Field Type: CMB2 Post Search field documented above, and so each link can be populated with existing WordPress content by clicking on the search button. Note: this is not a standard field type, but instead a function you use in combination with CMB2::add_field().
- CMB2 Field Type: Order by rubengc: Allows users to define custom order of predefined options.
- CMB2 Field Type: Animation by rubengc: Allows users to pickup an animation from Animate.css (includes preview of chosen animation).
- CMB2 Field Type: Ajax Search by rubengc: Based on CMB2 Field Type: Post Search Ajax, adds the ability to attach posts/users/terms, and the ability to limit the maximum number of attached objects.
- CMB2 Field Type: Visual Style Editor by rubengc: Custom field for CMB2 which allows customizing style from a small set of controls.
- CMB2 Field Type: Content Wrap by rubengc: Custom field for CMB2 to store a content wrap values (padding, margin or border width).
- CMB2 Field JS Controls by rubengc: Show any field similar to WordPress publishing actions (Post/Page post_status, visibility and post_date submit box field).
- CMB2 Field Type: Position by rubengc: CMB2 field type to setup a jquery UI position values.
- CMB2 Field Type: CMB2 Roadway Segments by pixelwatt: This plugin adds a new CMB2 fieldtype for drawing roadway segments onto a map and provides a shortcode for display.
- CMB2 Field Type: Font Awesome by serkanalgur: This plugin adds a new CMB2 field type for selecting Font Awesome icons.
- CMB2 Field Type: Typography by eduplessis: This plugin adds a new CMB2 field type “Typography” and it use jQuery fontselect for the font-family selection.
- CMB2 Field Type: Markdown by Rekenna: This plugin adds a new CMB2 field type “CMB2 Markdown” where you can type in markdown and view a live preview of the results or convert to html with a button.
- CMB2 Field Type: Switch Button by themevan: This plugin adds a Custom Switch Button field type for CMB2.
- CMB2 Field Type: select_plus from manzoorwanijk: Select field type which acts much like the default
select
field. However, it adds the support foroptgroup
and saving of values withmultiple
attribute. - CMB2 Field Type: Address by scottsawyer: Just a simple, repeatable address field. It’s really just the snippet from CMB2 Snippet Library converted to a plugin.
- CMB2 Field Type: Link by scottsawyer: Create a link field with some attributes. Very nice for styling links.
- CMB2 Field Type: Widget Selector by scottsawyer: Need a field that lets you ( or your editor ) select / display an existing widget instance? Then this is the plugin for you.
其他有用资源
- CMB2 WooCommerce HPOS 订单: 为新的 WooCommerce HPOS 订单页面添加自定义字段的功能。
- CMB2 管理扩展: 添加一个用户界面,以便从 WordPress 管理中创建 CMB2 元盒。 也在wordpress.org 上。
- WordPress 快捷键按钮: 使用 CMB2 字段为简码输入模式生成字段。
- WDS-Simple-Page-Builder: 使用当前活动主题中的现有模板部件,创建一个带有可重新排列元素的自定义页面。 使用 CMB2 构建。
- CMB2 示例主题: 演示如何在主题中加入 CMB2,以及一些很酷的提示和技巧。
- FacetWP-cMB2: FacetWP 与 CMB2 的集成。
- 来自origgami 的CMB2-grid: 用于 WordPress CMB2 库的网格系统,可创建列以改善管理布局。
- 来自rogerlos 的CMB2 Metatabs Options: CMO 可轻松创建带有多个元方框的选项页面–以及可选的 WordPress 管理选项卡。
- 来自jcchavezs 的CMB2 Conditionals: 允许开发人员将字段关联起来,使一个字段的显示以另一个字段值为条件。
- 来自willthemoor 的CMB2 元组代码生成器:跳过无聊的部分。 使用此生成器可轻松创建功能齐全的 CMB2 元组框。 现在可批量输入!
- Caldera Metaplate(由CalderaWP 提供):并非专门针对 CMB2,但允许创建模板以输出自定义字段。
- Yoast CMB2 字段分析 WP 插件(作者:alexis-magina):此插件添加了一种基于 js 的方法,用于在更新页面内容(特别是通过 CMB2 库添加的自定义元字段)时重新计算 Yoast SEO 的内容分数。
- Skeletonbyawethemes: 适用于 WordPress 的完整框架,使用 CMB2 引擎。
- WP Simple Iconfonts,由awethemes 提供: 一个图标字体管理器,并为 CMB2 提供了一个字体图标选择器。
- 由nsrosenqvist 制作的CMB2 导航菜单: 让您在导航菜单条目中使用 CMB2…
已知问题
- 目前,包含所见即所得编辑器的元框无法移动或以可重复方式使用(这是 TinyMCE 的问题)。
- 并非所有字段都能在可重复组中正常工作。
== 安装 ==
如果从 wordpress.org 安装插件:
- 将整个
/CMB2
目录上传到/wp-content/plugins/
目录。 - 通过 WordPress 的 “插件 “菜单激活 CMB2。
- 将
example-functions.php
(如需要可重命名)复制到您的主题或插件目录中。 - 编辑后只包含您需要的字段,并重命名函数。
- 获利。
如果在插件或主题中包含库:
- 将 CMB 目录放在主题或插件中。
- 将
example-functions.php
复制(如有需要可重命名)到 CMB 目录上方的文件夹,或将其全部内容复制到主题的functions.php
文件中。 - 编辑后只包含您需要的字段,并重命名函数(CMB 目录应保持不变,以便轻松更新库)。
- 收益。
== 常见问题 ==
常见问题通常会出现在github 维基中。
快速开始
打开example-functions.php并将所有代码复制/粘贴到 中functions.php
。创建一个新页面,您应该会在页面编辑器中看到所有示例元框。使用get_post_meta()获取/使用数据。
入门
首先,您需要获取引导程序并启动引擎。为此,请将以下代码添加到functions.php
。将 CMB2 包含在插件或主题中有一些注意事项。请在下面查看。
注意:如果您从WordPress.org安装插件,则可以跳过此步骤,因为它由插件处理。
/** * Get the bootstrap! * (Update path to use cmb2 or CMB2, depending on the name of the folder. * Case-sensitive is important on some systems.) */ require_once __DIR__ . '/cmb2/init.php';
笔记:
init.php
需要在任何 hook 之外被 require 。它需要尽早加载。- 不要进行任何类型的条件加载,例如
if ( ! class_exists....
。CMB2 将处理该加载。
创建元框
现在您已经包含了 CMB2 引擎,您可以开始使用以下代码添加元框functions.php
:
add_action( 'cmb2_admin_init', 'cmb2_sample_metaboxes' ); /** * Define the metabox and field configurations. */ function cmb2_sample_metaboxes() { /** * Initiate the metabox */ $cmb = new_cmb2_box( array( 'id' => 'test_metabox', 'title' => __( 'Test Metabox', 'cmb2' ), 'object_types' => array( 'page', ), // Post type 'context' => 'normal', 'priority' => 'high', 'show_names' => true, // Show field names on the left // 'cmb_styles' => false, // false to disable the CMB stylesheet // 'closed' => true, // Keep the metabox closed by default ) ); // Regular text field $cmb->add_field( array( 'name' => __( 'Test Text', 'cmb2' ), 'desc' => __( 'field description (optional)', 'cmb2' ), 'id' => 'yourprefix_text', 'type' => 'text', 'show_on_cb' => 'cmb2_hide_if_no_cats', // function should return a bool value // 'sanitization_cb' => 'my_custom_sanitization', // custom sanitization callback parameter // 'escape_cb' => 'my_custom_escaping', // custom escaping callback parameter // 'on_front' => false, // Optionally designate a field to wp-admin only // 'repeatable' => true, ) ); // URL text field $cmb->add_field( array( 'name' => __( 'Website URL', 'cmb2' ), 'desc' => __( 'field description (optional)', 'cmb2' ), 'id' => 'yourprefix_url', 'type' => 'text_url', // 'protocols' => array('http', 'https', 'ftp', 'ftps', 'mailto', 'news', 'irc', 'gopher', 'nntp', 'feed', 'telnet'), // Array of allowed protocols // 'repeatable' => true, ) ); // Email text field $cmb->add_field( array( 'name' => __( 'Test Text Email', 'cmb2' ), 'desc' => __( 'field description (optional)', 'cmb2' ), 'id' => 'yourprefix_email', 'type' => 'text_email', // 'repeatable' => true, ) ); // Add other metaboxes as needed }
注意:有关更多 metabox 示例,请参阅example-functions.php
以下是一个很酷的视频概述,介绍了该文件将提供的内容example-functions.php
:
![](https://tkwlkj.com/wp-content/uploads/2024/07/cmb2.jpg)
使用插件创建元框
您还可以通过创建标准 WordPress 插件并将上述代码粘贴到插件标题下方来创建元框。
显示元数据
后,您需要能够提取元数据并使其发挥作用。在您的主题或插件文件中,使用 get_post_meta ()函数显示您的元数据。请记住,您必须传递帖子 ID!
<?php // Grab the metadata from the database $text = get_post_meta( get_the_ID(), 'yourprefix_text', true ); // Echo the metadata echo esc_html( $text ); ?>
假设您创建了一个包含上面列出的字段的元框,并希望在单页模板上显示它:
<?php /** * The template for displaying all pages. * * This is the template that displays all pages by default. * Please note that this is the WordPress construct of pages * and that other 'pages' on your WordPress site will use a * different template. * * @package WordPress * @subpackage Twenty_Eleven * @since Twenty Eleven 1.0 */ get_header(); ?> <div id="primary"> <div id="content" role="main"> <?php while ( have_posts() ) : the_post(); ?> <?php get_template_part( 'content', 'page' ); ?> <?php $text = get_post_meta( get_the_ID(), 'yourprefix_text', true ); $email = get_post_meta( get_the_ID(), 'yourprefix_email', true ); $url = get_post_meta( get_the_ID(), 'yourprefix_url', true ); echo esc_html( $text ); echo is_email( $email ); echo esc_url( $url ); ?> <?php comments_template( '', true ); ?> <?php endwhile; // end of the loop. ?> </div><!-- #content --> </div><!-- #primary --> <?php get_footer(); ?>
有关使用帖子元数据的更多信息,请参阅 Codex 页面中的get_post_meta(),或查看Post Meta Bootcamp。请记住,转义所有数据!使用帖子元数据时使用适当的数据验证是正确的做法。不要相信任何人!
有关更多示例代码,请参阅example-functions.php
将元框添加到用户个人资料
要将自定义元框添加到用户个人资料页面,您可以将参数设置object_types
为,array( 'user' )
以指示元框应显示在用户个人资料上(而不是特定的帖子类型),并且元信息应存储在 user_meta 而不是 post_meta 中。
可以在example-functions.php中看到一个示例元框
请注意,Metaboxdescription
和name
参数不会显示。您可以通过添加title
字段作为第一个字段来标记用户设置部分。
捆绑和包含 CMB2 的注意事项。
本节重点介绍包含 CMB2 时的一些注意事项。CMB2 有一种智能方法,可以只加载其自身的一个版本,而且只加载新版本(我们还严格承诺向后兼容,以便新版本不会破坏使用以前版本构建的代码)。如果您没有正确包含它,可能会导致意想不到的后果。有关 CMB2 如何/为何这样做的更多背景信息,请阅读此帖子。
- 要做:直接从主题或插件中包含文件。例如: require_once __DIR__ . ‘/includes/cmb2/init.php’;
- 不要:包含来自钩子的文件。例如: // DON’T DO THIS add_action( ‘init’, ‘wprpt_initialize_cmb_init’, 10 ); function wprpt_initialize_cmb_init() { require_once __DIR__ . ‘/includes/cmb2/init.php’; }
- 要做:对包含文件使用区分大小写的路径。例如: require_once __DIR__ . ‘/includes/CMB2/init.php’;或者 require_once __DIR__ . ‘/includes/cmb2/init.php’;如果您从 WordPress 插件仓库下载 CMB2,它将是一个小写的目录,
cmb2
。但是,由于 Github 的命名约定,如果您克隆此仓库,或下载它,或在发布页面上下载发布版本,它将是一个大写的目录,CMB2
。显然,当您将其捆绑/包含在主题或插件中时,您可以将目录命名为您想要的任何名称。 - 不要:在包含之前进行
class_exists()
检查。(CMB2 可以自行处理该魔法。) // DON’T DO THIS if ( ! class_exists( ‘Some_CMB2_Class’ ) ) { require_once __DIR__ . ‘/includes/cmb2/init.php’; } - 要做:使用正确的 CMB2 包。Composer是一种不错的推荐方式,但如果您要将 CMB2 捆绑到主题/插件中,请从WordPress 插件库下载 zip 文件。
- 不要:将 repo 克隆到您的项目中。您将克隆所有仅用于开发的文件/文件夹。如果将您的主题与 CMB2 捆绑在一起提交到 WordPress 主题 repo,您可能会因包含这些开发文件而被拒绝。