README

这是一个有偏见的、基础入门主题，用于在 Harvest Media 构建 CraftCMS 网站。它旨在节省我们的开发人员时间并提高项目之间的连贯性，同时遵循性能的良好实践。

关于 CraftCMS

CraftCMS 是我们的首选工具。它是一个灵活、可扩展的 CMS，用 PHP (7+) 编写，基于 Yii 2 框架构建。它可以连接到 MySQL (5.5+) 和 PostgreSQL (9.5+) 以存储内容。

文档 – 阅读官方文档。
指南 – 跟随官方指南。
服务器要求
安装说明

假设

我们围绕 Harvest Media 的最常见用例设计了此入门主题，包括

在由 Linode VPS 提供并由 Laravel Forge 配置的托管上
- 使用 nginx 网络服务器
当用户将代码推送到 master 分支时自动部署

但当然，这也可以在任何其他可以运行 CraftCMS 的 LAMP 环境中工作。

此入门主题的功能

页面/导航（原生 Craft 部分）
博客（原生 Craft 部分）
内容块构建器（原生 Craft Matrix）
联系表单（通过 Craft Contact Form 插件）
服务器端静态页面缓存（通过 CacheFlag）
CSRF 保护（Craft 内置）
SEOMatic（第三方插件，以保持 SEO 一致性、简便性和灵活性）

插件依赖项

SEOMatic
CacheFlag
LinkIt（用于内容块/构建器）

可选插件

目录结构

文件夹

config（用于 CraftCMS 配置设置 - craft 的配置文件夹中不应包含任何特定于客户端的信息）
modules（由 Craft 使用）
vendor（由 npm 使用，并在我们的仓库中被忽略）
public（网站根目录）
src（前端代码的源文件：css 和 js）
storage（由 Craft 使用）
templates（这些是 TWIG 模板文件，我们将在这里花费大部分的开发时间）
translations（由 Craft 用于更改控制面板或前端应用程序中某些单词的翻译）
vendor（由 Composer 使用，并在我们的仓库中被忽略）

文件

.env（Craft 的主配置文件，其中还包含特定于客户端的信息。这将针对每个项目进行编辑，并在每个环境中不同：开发、预发布和生成环境。）
composer.json & composer.lock（由 Craft 使用 - 通常不手动编辑）
craft & craft.bat（Craft 的命令行文件）
favicon.master.png（一个透明的正方形标志图像，我们用它在这里构建我们的 favicons：https://realfavicongenerator.net ）
package.json 及 package-lock.json（由 npm 使用 - 通常不手动编辑）
README.md（我们正在查看的文件 :-)
tailwind.config.js（扩展 TailwindCSS 默认配置，包括客户端品牌颜色或其他类。）
webpack.mix.js（我们的 Laravel Mix 配置文件，用于配置 SCSS、PostCSS 和 JS 构建）

注意：此起始主题假定目录结构中 public 作为 Web 根目录（不是 "web" 或 "public_html"）。如果您更改 Web 根文件夹名称，则需要更新 Laravel Mix 配置文件和 Craft 的 config/general.php 文件。

使用 Laravel Mix 开发前端

跟上现代 Web 的步伐具有挑战性，但我们努力保持与潮流同步并遵循当天的推荐做法。目前，我们使用 Laravel Mix，自称是针对 80% 使用情况的 Webpack 的优雅包装。在 WebPack 配置冗长且复杂的情况下，Laravel Mix 相对简短且易于使用。

查看存储库根目录中的 webpack.mix.js 文件。

本地开发

从终端，使用 cd 进入项目目录，并运行 npm install。

以下命令可用。（您可以在 package.json 中找到它们）。

npm run watch 在 localhost:3000 启动带有 BrowserSync 的本地开发
npm run prod 构建 CSS 和 JS 用于生产（包括 PurgeCSS）

注意：Laravel Mix 还支持通过 npm run hot 使用 Hot Module Replacement (HMR)，但这似乎主要是为单页 JavaScript 应用或 .vue 文件设计的。我们尚未破解如何使用它的代码。

查看 Laravel Mix 配置文件以获取详细信息。

CSS（SCSS 和 PostCSS）

起始主题在 src/css/theme.scss 中有一个主 CSS 文件。它使用

Foundation Sites 用于基本样式、布局以及其中的一些内置组件
TailwindCSS 用于自定义样式和组件

我们只包含我们想要的 Foundation 部分，而不是整个框架。

大部分样式将在 html 中使用 TailwindCSS 提供的 tw- 工具类来完成。

在构建生产环境时，首先处理 SASS/SCSS，然后运行 PostCSS 插件。

JS

主题的主 JS 文件位于 src/js/theme.js。

对于任何需要 JavaScript 的 Foundation 插件，我们将其与 jQuery 一起包含。

我们建议将 JS 保持到最小。

使用 JS 进行 CSRF 保护

注意：我们通过 jQuery 代码实现 CSRF 保护。

if (
  $("input[name='CRAFT_CSRF_TOKEN']").length > 0
) {
  $(() => {
    $.ajax({
      url: "/get-token",
      success: response => {
        $("input[name='CRAFT_CSRF_TOKEN']").val(
          response
        );
      }
    });
  });
}

英文总结如下：

检查页面上任何 CSRF 表单输入。
向只包含 CSRF 令牌的 CraftCMS 模板发出 AJAX 请求。
将 AJAX 响应（当前有效的 CSRF 令牌）添加到表单输入。

模板化

使用宏

部分和宏（特别是）将帮助您避免在 TWIG 模板中的重复。请随意使用它们。

SVG 图标

Craft 允许我们从 public 文件夹中的一个文件直接将单个 SVG 内联到我们的 HTML 中。这比构建图标精灵容易得多，并允许我们轻松地只包含页面上实际使用的图标。

以下是我们使用的代码

{{ svg('@webroot/assets/svg/YOUR_FILE_NAME_HERE.svg')|attr({class:'YOUR_CLASSES_HERE',role:'img'})|append('<title>YOUR_TITLE_HERE</title>', 'replace') }}

关注服务器端性能

Craft 中的预加载元素将产生显著差异，而且做起来很简单。请参阅 Craft 文档中的说明。

本地开发和测试

除了在您的网络上通过IP地址进行测试外，您还可以使用 ngrok 来进行跨设备和远程（在您的网络之外）测试。

我们建议在本地进行最终测试时，将环境从 dev 改为 staging。

harvest-media / craft-business

维护者

详细信息