README

为您的WordPress插件在WooCommerce风格下创建设置页面。

这个库是对实际WooCommerce代码的封装。这不是我的代码，而是WooCommerce的代码，以您可以用它来构建自己的插件的方式进行打包。

目前，这个库会不时手动与WooCommerce代码同步。但将来它将自动更新，每当WooCommerce向其仓库推送新版本时。

设置页面结构

设置页面在WordPress中的结构如下： 菜单 > 子菜单 > 标签页 > 部分[可选]。

这个库中最基本的元素是 标签页。这里每个设置页面都是一个标签页。

部分或字段部分？

部分：标签页下的菜单；
字段部分：每页上的字段组；

安装

composer require loureirorg/settings-as-woocommerce

用法I - 将子菜单添加到“用户”菜单中

$label = 'My Submenu';
$slug  = 'my_submenu';
$menu  = 'users';

$my_submenu = new Submenu( $label, $slug, $menu );
$my_submenu
  ->add_tab( new MyTab1() )
  ->add_tab( new MyTab2() );

用法II - 创建不带子菜单的自定义菜单

$my_menu = new Menu( 'My Menu', 'my_menu' );
$my_menu
  ->add_tab( new MyTab1() )
  ->add_tab( new MyTab2() );

用法III - 创建带子菜单的自定义菜单

$my_menu    = new Menu( 'My Menu', 'my_menu' );
$my_submenu = new Submenu( 'My Submenu', 'my_submenu', 'my_menu' );
$my_submenu
  ->add_tab( new MyTab1() )
  ->add_tab( new MyTab2() );

用法 - 标签定义

创建一个扩展 Tab 的类；
定义构造函数并设置 id 和 label 属性；
在构造函数末尾，调用父构造函数；
定义方法： get_fields 和 save；
[可选] 定义方法 get_sections，get_assets，get_inline_css，get_inline_js，get_inline_css，get_inline_js；

简单示例

class MyTab1 extends Tab {

  public function __construct() {
    $this->id    = 'my_tab1';
    $this->label = 'My First Tab!';
    parent::__construct();
  }

  public function get_settings() {
    $settings = array(
      array( 'type' => 'title', 'name' => 'My Field Group' ),
      array( 'type' => 'checkbox', 'name' => 'My checkbox 1', 'id' => 'my-checkbox-1' ),
      array( 'type' => 'checkbox', 'name' => 'My checkbox 2', 'id' => 'my-checkbox-2' ),
      array( 'type' => 'sectionend', 'id' => 'my-field-group-1-end' ),
    );
    return $settings;
  }

  public function save() {
    $this->update_options( $this->get_settings() );
  }

}

详细示例

class MyTab2 extends Tab {

  public function __construct() {
    $this->id    = 'my_tab2';
    $this->label = 'My Second Tab!';
    parent::__construct();
  }

  public function get_sections() {
    $sections = array(
      ''         => 'Section 1',
      'section2' => 'Section 2',
      'section3' => 'Section 3',
    );
    return $sections;
  }

  public function get_assets( $current_section = '' ) {
    if ( $current_section == 'section2' ) {
      return array( 'index.js', 'index.css' );
    }
    return array();
  }

  public function get_inline_css( $current_section = '' ) {
    if ( $current_section == 'section2' ) {
      return 'body { background-color: green }';
    }
    return null;
  }

  public function get_inline_js( $current_section = '' ) {
    if ( $current_section == 'section2' ) {
      return 'alert(1)';
    }
    return null;
  }

  public function get_settings( $current_section = '' ) {
    $settings = array();
    if ( '' === $current_section ) {
      $settings = array(
        array( 'type' => 'title', 'name' => 'My Section 1A' ),
        array( 'type' => 'checkbox', 'name' => 'My checkbox 1A', 'id' => 'my-checkbox-1a' ),
        array( 'type' => 'checkbox', 'name' => 'My checkbox 2A', 'id' => 'my-checkbox-2a' ),
        array( 'type' => 'sectionend', 'id' => 'my-section-1-end' ),
      );
    } else {
      $settings = array(
        array( 'type' => 'title', 'name' => 'My Section 1B' ),
        array( 'type' => 'checkbox', 'name' => 'My checkbox 1B', 'id' => 'my-checkbox-1b' ),
        array( 'type' => 'checkbox', 'name' => 'My checkbox 2B', 'id' => 'my-checkbox-2b' ),
        array( 'type' => 'sectionend', 'id' => 'my-section-1b-end' ),
      );
    }
    return $settings;
  }

  public function save() {
    $this->update_options( $this->get_settings() );
  }

}

使用WooCommerce动作和过滤器

您可以使用任何标准WC过滤器/动作。只需将 woocommerce 前缀替换为您的 子菜单slug。

示例

/** `woocommerce_settings_tabs_array` becomes `mymenu_settings_tabs_array`. */
add_action( 'mymenu_settings_tabs_array', 'add_settings_tab_callback' );

可选库动作

{menu}_load_page：当打开菜单/子菜单页面时触发。例如：my_submenu_load_page；
{menu}_load_tab_{tab}：当打开标签页页面时触发。例如：my_submenu_load_tab_my_tab；

可选菜单/子菜单设置

->set_page_title( '浏览器标签上的标题' )
->set_capability( 'list_users' )
->set_position( 90 )
->set_icon_url( '/assets/icon.png' )
->force_show_tabs()
->add_asset( 'index.js' )->add_asset( 'index.css' )
->set_inline_css( 'body { background-color: red }' )
->set_inline_js( 'alert(1)' )

可选标签辅助器

->get_current_section()
->update_options( $options )

用法 - 长版本：您可以直接使用WC代码，而不使用菜单/子菜单/标签类。

$wc = new Woocommerce\WC( 'mymenu' );
add_action( 'admin_menu', 'admin_menu_callback' )
...
add_action( 'mymenu_settings_tabs_array', 'add_settings_tab_callback' );

在哪里放置所有这些代码？

可以在您的插件构造函数中放置菜单定义，在您放置 add_action( 'admin_menu', 'admin_menu_callback' ) 的相同位置。

每个标签定义是一个独立的类定义。建议将每个定义放在单独的文件中。

待办事项

创建一个脚本来自动更新WooCommerce代码
为类 Tab，Menu，Submenu，Helpers 编写单元测试；
为自动更新代码编写单元测试；
使用GitHub Actions自动化测试；
改进README文件
- 将“用法”中的截图添加到以显示预期结果；
- 将截图添加到“设置页面结构”和“部分与字段部分”中；
- 显示徽章 - 测试、phpmd、phpcs、版本；
- 显示2个版本：1) 主版本：WC版本（用于packagist）；2) 我们包装的代码；
- 在“使用 - 长版本”中的完整功能示例： new WC() + 默认 WP 代码创建菜单 + 默认 WC 代码创建设置页面；
GitHub Actions - 当 WooCommerce 仓库发生变化时自动更新代码
- 对于每个新的 WC 版本，我们触发自动更新 + 运行测试 + 如果测试通过则部署新版本 + 使用新版本推送到 Packagist；
- 对于此代码仓库的每个新版本，我们应该在接受 PR（拉取请求）之前运行测试；
集成测试
- 下载 WP（就像 WP 的单元测试）；
- 自动更新 WC 代码；
- 自动安装一个显示设置页面的插件；
- 矩阵
  - 尝试 WP 支持的所有 PHP 版本（5.3 .. 7.*）；
  - 尝试最新的 WP 版本，以及旧版本；
  - 为了测试自动更新的弹性，我们应该尝试所有 WC 代码版本，从其 1.0 版本开始；
功能测试
- 确保菜单/子菜单/标签/部分/字段以它们应有的方式可见；
- 使用 Pupeteer 检查设置页面是否正确渲染？Selenium？

错误和改进

此项目的目标是成为一个简单且 笨拙的包装器，用于 WooCommerce 库。虽然我们有一些辅助函数如 set_inline_css()，但我正试图使此代码尽可能少地侵入 WooCommerce 代码，以实现代码更新的自动化。

这意味着如果您发现任何可以在 WooCommerce 上重现的问题，您应该要求他们修复它。如果问题是 WooCommerce 问题，这里不会修复。例如，假设您发现某些字段在没有适当清理的情况下被打印出来：请要求 WooCommerce 团队修复它。

此外，为了避免此代码成为比简单的包装器更多，我将拒绝大多数对其的改进和 PR。一般规则是 改进和错误应要求 WooCommerce 团队解决。

如果您不确定您的错误/改进是否符合此项目，如果您不确定您应该在这里还是向 WooCommerce 团队报告，请随时打开一个问题询问我。我不能保证它会修复和/或实施（大多数不会），但我会始终很高兴查看它 :)

loureirorg / settings-as-woocommerce

维护者

详细信息