README

这是一个基于意见的、基本的起始主题，用于在Harvest Media构建新的CraftCMS网站。它旨在节省我们开发者的时间并提高我们项目的一致性，同时遵循良好的性能实践。

关于CraftCMS

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

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

假设

我们设计了此起始主题，针对Harvest Media最常见的用例，包括

在由Laravel Forge配置的Linode VPS上托管
- 使用nginx web服务器
用户向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（一个透明正方形logo图像，我们在这里用它来构建我们的favicon：[https://realfavicongenerator.net](https://realfavicongenerator.net)）
package.json &amp package-lock.json（由npm使用 - 通常不手动编辑）
README.md（我们正在查看的文件 :-)
tailwind.config.js（扩展TailwindCSS默认配置以包含客户端品牌颜色或其他类。）
webpack.mix.js（我们的Laravel Mix配置文件，配置SCSS、PostCSS和JS构建）

注意：此启动主题假定目录结构以public作为网站根目录（不是“web”或“public_html”）。如果您更改网站根目录的名称，则需要更新Laravel Mix配置文件和Craft的config/general.php文件。

使用Laravel Mix进行前端开发

跟上现代网络是具有挑战性的，但我们努力跟上潮流，并遵循当天的推荐实践。目前，我们使用由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支持热模块替换（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 / craftcms-starter

维护者

详细信息