README

安装

通过将仓库克隆到您的WordPress主题目录下并移除git跟踪来手动安装主题

设置

首先，您需要安装所需的npm包以开始开发。在您的主题根目录下运行

npm install

命名空间

该主题使用命名空间 \TMS\Theme\Base。WordPress不支持模板文件的命名空间，因此它们不遵循命名空间。

翻译和文本域

翻译和主题文本域从 /lang 目录加载。使用大小写敏感的搜索和替换，在所有项目文件中将 tms-theme-base 字符串替换为您主题文本域。然后，将 /lang 目录下的 .pot 文件重命名为新的主题文本域。

Polylang

该主题内置了对 Polylang 的支持。如果已安装并激活Polylang，语言切换器将自动显示在主导航中。

高级自定义字段

如果已安装并激活 Advanced Custom Fields，则主题设置将可用。可以在主题设置中更改的示例包括徽标和页脚内容。

语言特定的主题设置在同时安装了高级自定义字段和Polylang时可用。

Bulma和Bulmally

该主题已设计为利用 Bulma CSS 框架和 Bulmally 可访问性前端组件框架。有关模态框、手风琴、选项卡和其他动态组件的信息，请参考该存储库。

主题信息

命名空间: \TMS\Theme\Base

请确保在 style.css 中更改主题和作者信息。

主题目录结构

DustPress 主题由以下目录组成

/assets - 脚本和样式。
/lang - 主题本地化文件。
/lib - 符合 PSR-4 Autoloader 规范的主题后端库。
/models - DustPress 模型。
/partials - DustPress 部分视图。
/utils - 用于主题开发的实用脚本。

部分目录结构

The DustPress 主题中的部分视图已按以下方式组织

/partials/ - 部分视图根目录中的 dust 文件是每个模型的主体部分（page.dust、single.dust...）
/partials/views/<VIEW> - 包含仅用于特定视图的部分。例如，/partials/views/archive 包含仅用于 archive.dust（或其子项）的 dust 文件。
/partials/shared - 视图共享的部分。每页只需要的部分。例如，/partials/shared/header/header.dust
/partials/ui - 可重复使用的 ui 组件，可以在许多地方多次使用。例如，/partials/ui/ratio-image 用于存档卡片和单个文章（帖子）的特色图片。

请随意以您希望的方式更改部分视图结构。

主题开发指南

帖子类型

主题中定义的所有帖子类型都应该在实现 TMS\Theme\Base\Interfaces\PostType 接口的类中的 PostType 目录下编写，并通过 hooks() 方法在所需钩子中注册自己。

默认类

主题自带了WordPress默认帖子类型的预定义类。使用这些类来处理它们的数据。

TMS\Theme\Base\PostType\Post：默认帖子类型 post 的类表示。
TMS\Theme\Base\PostType\Page：默认帖子类型 page 的类表示。
TMS\Theme\Base\PostType\Attachment：默认帖子类型 attachment 的类表示。

分类法

主题中定义的所有分类法都应该在实现 TMS\Theme\Base\Interfaces\Taxonomy 接口的类中的 Taxonomy 目录下编写，并通过 hooks() 方法在所需钩子中注册自己。

用户和角色

请使用我们的 devgeniem/wp-geniem-roles 包来修改用户和角色。

高级自定义字段

ACFController 类处理从 lib/ACF 目录加载 ACF 字段。该目录下的文件仅由控制器需要，因此所有逻辑都必须由开发者自行实现。

模板和模型

主题包含一个基础模型 BaseModel，它具有默认的子模型绑定。

日志记录

\TMS\Theme\Base\Logger 处理与 syslog 兼容的日志级别。

记录的消息最终传递给 error_log() 函数，该函数部分使用配置的日志目标。

要控制最终输出到日志的内容，您可以更改 GENIEM_LOG_LEVEL 环境变量。以下是快速表，其中包含级别（用于控制日志级别）、类方法和在代码中使用时的描述。

使用日志记录器的最简单方法是

try {
    throw new Exception( 'This is an example.' );
}
catch ( \Exception $e ) {
    ( new \TMS\Theme\Base\Logger() )->error( $e->getMessage(), $e->getTrace() );
}

资产和 Webpack

webpack 用于编译资产。使用 npm 安装包，并在 assets/scripts/main.js 中引入 JavaScript 文件，在 assets/styles/main.scss 中导入 SCSS 文件。构建资产的目录是 assets/dist。

您只能在主题的 PHP 代码中排入位于 assets/dist 下的文件！要使用节点模块，将它们导入到主题脚本中。

用于资产的 URL 已在 /lib/Setup.php 中定义，为 DPT_ASSET_URI 常量。默认情况下，它指向 https://{site_domain}/{path_to_themes_folder}/themename/dist。要使用其他资产源，可以更改此值，例如在 wp-config.php 文件中定义自定义 URI 的常量。

资产版本控制

样式和脚本文件会自动带有当前主题版本进行排入。要清除浏览器缓存以更新资产，请在 style.css 文件注释中更改主题版本。

开发

在本地环境中在主题根目录下运行 webpack。

使用 npm 脚本运行

npm run watch

这些命令将编译 未压缩 版本的资产。

生产

使用 npm 脚本构建用于生产的压缩版本

npm run build

此命令将编译压缩版本的资产。

使用 Browsersync 进行测试

项目包括一个 BrowserSync 设置，该设置将您的站点代理到 localhost:3000 以及本地网络上的一个 IP 地址。这使您能够同时使用多个浏览器和设备进行开发、测试，并具有滚动和点击同步功能。Browsersync 的设置在 webpack.config.js 中。

您应该至少更改wpProjectUrl常量，使其指向您的本地开发服务器。默认情况下，Browsersync会监控CSS、JS、PHP和Dust文件的变化，并自动重新加载所有浏览器。有关可用设置等信息，请阅读webpack插件文档和Browsersync文档。

JavaScript开发指南

主题的Webpack配置使用Babel将ES6编译成ES5。因此，我们使用ES6中引入的类和其他酷炫功能。在此处查看ES6功能的完整列表。

启用Babel编译

如果您使用ES6功能添加npm包，请记住在webpack.config.js文件中包含它们以供Babel加载器使用！

// List paths to packages using ES6 to enable Babel compiling.
{
    include: [
        path.resolve( __dirname, 'assets/scripts' ),
        path.resolve( __dirname, 'node_modules/foundation-sites' )
    ]
}

当运行npm run build时，如果尝试压缩未包含在Babel加载器中的ES6脚本，TerserJS很可能会产生错误！

主题脚本

主题的主要JS文件theme.js包含主主题类。当文档准备就绪时，Theme类会自动运行其他主题JS类。为了在JS端启用自动加载，请按以下方式定义您的模板脚本

为每个WordPress模板创建一个单独的脚本文件，例如page-frontpage.js。您也可以创建无论模板如何都加载的脚本文件。
定义一个模拟您的DustPress模型的JS类，并导出类引用，例如export default class PageFrontpage {}。
文档的html元素将自动从您的模型获得一个类，例如<html class="PageFrontpage">。如果您为特定模板添加更多脚本，请将相应的类名添加到html元素的classlist中，使用dustpress/document_class过滤器。

在theme.js中导入您的脚本，并将它们添加到适当的控制器列表中。如果需要从其他脚本类访问方法，脚本顺序很重要。

// First import the scripts you want to use
import Common from './common';
import PageFrontpage from './page-frontpage';

// Add your global scripts here.
const globalControllers = {
    Common
};

// Add your template-specific scripts here.
const templateControllers = {
    PageFrontpage
};

当文档就绪时，Theme类将自动运行一个名为docReady的方法。请记住在您的模板类中定义它！

`Theme`类

Theme类控制主题脚本类。类实例在全局范围内可访问，因此Theme是我们主题中的一个保留JavaScript对象名称。Theme在相应的类属性下持有所有脚本。

全局脚本在_globalControllers下，模板特定脚本在_templateControllers下。这些属性是哈希表，意味着每个控制器都位于一个以类名称定义的键下

class Theme {
  constructor() {
      // [...]
      this._templateController = {
        className: classInstance
      }
      // [...]
  }
}

控制器类由main.js中运行的设置方法（setGlobalControllers和setTemplateControllers）实例化。因此，在文档准备就绪和加载之前创建了一个类实例并可以访问。只有当DOM中的html元素定义了相应的样式类名称时，才会实例化模板控制器。如果模板控制器类未实例化，您仍然可以通过调用Theme.{ClassName}以静态方式访问它。

不要修改此类！使用其他脚本文件在您的主题中执行魔法！

访问控制器

例如，在某个内联脚本中访问类实例，请按以下方式获取

var frontpageInstance = Theme.getController("PageFrontpage");

例如，要访问类引用，请按以下方式获取

var commonClass = Theme.Common;

类引用在需要全局静态方法时很有用。例如，您可能可以在common.js下创建一个静态全局Vanilla JS查询选择器

export default class Common {
    // Select a list of matching elements, context is optional.
    static $(selector, context = undefined) {
        return (context || document).querySelectorAll(selector);
    }
}

...然后按以下方式使用它

let element = Theme.Common.$('.my-element');

`docReady`方法

如果您需要动态操作DOM并且需要重新运行当前模板中的所有docReady方法（由当前html元素的classlist控制），请使用类方法运行它

Theme.runDocReady();

或者，您可以运行单个控制器实例的docReady

Theme.getController('PageFrontpage').docReady();

`init`方法

Theme类运行名为init的方法，用于所有全局脚本，并在所有脚本实例化后执行当前定义的模板脚本。如果您想在类构造函数中访问其他脚本类，由于require顺序，它们可能还不可用。通过在init方法中运行您的脚本，所有其他脚本类都已加载和实例化。以下是一个示例用法

class PageFrontpage {
    init() {
      // I need to acces the sidebar!
      this.Sidebar = Theme.getController('Sidebar');
      // Now we can run stuff before the docReady..
      this.Sidebar.frontPageMakesMeDoStuff();
    }
}

`Common`类

主题资源包括一个名为Common的默认通用脚本类。将其用作所有全局方法和属性的默认类。例如，您可能会在Common类中处理主菜单。

不要膨胀这个类！如果您的脚本文件太长，不要害怕引入更多的全局控制器类！无论您做什么，请记住：D.R.Y！

`Common`下的有用方法

`stop`

此静态方法使您能够在事件监听器回调中安全地停止默认事件。以下是如何使用它

function myEventCallback(e) {
  Theme.Common.stop(e);
  // Do some other stuff with the event..
}

`$`

此静态方法包装了querySelectorAll函数，并允许您选择一组匹配的元素。为了优化查询，添加一个上下文元素，并在其下进行查询。

let elements = Theme.Common.$('.my-element', myParentElementObject);

`$1`

此静态方法包装了querySelector函数，以从DOM中选择单个元素。为了优化查询，添加一个上下文元素，并在其下进行查询。

let element = $1('.my-element', myParentElementObject);

全局事件监听器和data-cmd属性

主题类添加了全局点击事件监听器，您可以通过向您的html元素添加data-cmd和data-ctrl属性来使用它，其中data-ctrl定义了JavaScript控制器类，而data-cmd定义了要调用的方法。

<button data-cmd="doSomething" data-ctrl="MyAwesomeController" />

该方法接收两个参数。第一个参数是事件，第二个是具有data-cmd和data-ctrl属性的元素。

因此，在MyAwesomeController类中，我们可以有一个像这样的方法

class MyAwesomeController {
    /**
     * Set aria-expanded to true when element is clicked.
     *
     * @param {object|Event}              e  The button click event.
     * @param {object|HTMLElement|jQuery} el The dom object of the element that was clicked.
     * @return {void}
     */
    doSomething(e, el) {
        el.setAttribute('aria-expanded', 'true');
    }
}

外部库

jQuery

所有脚本都依赖于WordPress将jQuery作为外部库排队。WordPress在全局上下文中公开jQuery作为公共库。要使用$缩写，请将以下内容添加到脚本文件的开头

const $ = jQuery;

Lodash

Lodash是一个现代JavaScript实用库，提供模块化、性能和附加功能。有关使用说明，请参阅文档。要导入Lodash，请将以下内容添加到脚本文件的开头

import _ from 'lodash';

贡献者

我们的贡献者

devgeniem / tms-theme-base

维护者

详情

README

安装

设置

命名空间

翻译和文本域

Polylang

高级自定义字段

Bulma和Bulmally

主题信息

主题目录结构

部分目录结构

主题开发指南

帖子类型

默认类

分类法

用户和角色

高级自定义字段

模板和模型

日志记录

资产和 Webpack

资产版本控制

开发

生产

使用 Browsersync 进行测试

JavaScript开发指南

启用Babel编译

主题脚本

Theme类

访问控制器

docReady方法

init方法

Common类

Common下的有用方法

stop

**$**

$1

全局事件监听器和data-cmd属性

外部库

jQuery

Lodash

贡献者

`Theme`类

`docReady`方法

`init`方法

`Common`类

`Common`下的有用方法

`stop`

`$`

`$1`