README

这是一个具有偏见的Craft CMS入门级项目，使用DDev进行本地开发，Tailwind CSS，Alpine Js和Laravel Mix。

安装Craft 5版本

要安装此软件包，请运行 composer create-project createsean/craft-starter .

安装Craft 4版本

要安装此软件包，请运行 composer create-project createsean/craft-starter . --prefer-dist 4.2.31

安装Craft 3版本

要使用Craft 3版本安装，请运行 composer create-project createsean/craft-starter . --prefer-dist 1.14.0

本地开发

设置您的本地开发环境，如果您正在使用DDev进行本地开发，则所有内容都应该为您正常工作。如果您没有使用DDEV进行本地开发，请跳过此部分，并按照通常的方式设置本地开发环境（Valet、Mamp等），请确保导入种子数据库 db.sql.gz

打开 .ddev/config.yaml 并将第15行更新为要使用的端口号。必须在您的本地计算机上对所有ddev网站是唯一的
打开 .ddev/config.yaml 并根据需要更新php版本（第4行）和mysql_version（第11行）
更新dotenv变量，特别是SITE_NAME_EN、SITE_NAME_FR、PRIMARY_SITE_URL、SITE_PATH、ASSET_BASE_URL
更新dotenv的邮件设置以进行测试/生产。当前设置与ddev中的mailhog兼容。要打开mailhog，请运行 ddev launch -m
运行 ddev start，然后网站应该启动。
运行 ddev import-db --file=db.sql.gz 这将导入带有设置、通道等的种子数据库。
运行 php craft setup/security-key
运行 php craft setup/app-id
运行 ddev launch access 将打开Craft CP
要从您的宿主机访问数据库，请运行 ddev describe，您将获得所需的连接详情

登录后，请务必更新您的密码

待办事项

确保默认模板通过无障碍性测试 - aria标签、alt文本等。
设置站点搜索。
联系表单。
将AlpineJs和插件从CDN移动到编译构建过程。
添加具有常见内容类型的构建器。
联系页面
关于/团队页面
添加带有不同选项的英雄（例如，滑块、无滑块、无图片仅标题）。
使用Sprig使新闻类别正常工作。
添加新闻_entry模板。
添加带有Sprig分页的新闻列表。
添加通知栏选项。
添加404模板。
添加安装说明。
用CKEditor长格式替换matrix内容构建器
尽可能更新模板以使用 .eagerly()

构建过程

Tailwind使用Tailwind-jit进行编译，这比之前快得多。它还确保在 watch 构建过程中文件大小较小。然而，我仍然建议在部署之前运行生产任务。

图像和svg文件应复制到src/img和src/img/svg。运行npm run production后，这些文件将被优化并分别复制到/public/assets/images和/public/assets/images/svg（如果您不想运行生产环境，请将文件复制到两个位置）

您需要NodeJS版本14+。您可以选择升级到14+或如果您需要多个版本的node，请安装Node Version Manager Windows / Mac。

运行npm install或npm i

通过运行npm install <package-name> --save-dev添加您需要的任何脚本或css。然后您可以通过在webpack.mix.js中添加正确文件的路径来将所需的javascript或css文件合并并最小化（在64-70行(js)或74-78行(css)）。运行npx mix watch后，所有内容将合并并输出到/public/assets/js或public/assets/css

在webpack.mix.js的75-85行更新被添加到css前面的横幅文本，以包含您的项目信息
在webpack.mix.js中更新12行的const baseUrl = 'https://craft-starter.ddev.site'为您的本地域名

  .banner({
    banner: (function () {
        return [
            '/**!',
            ' * @project        Craft Starter Website',
            ' * @author         Sean Smith, Caffeine Creations',
            ' * @Copyright      Copyright (c) ' + moment().format("YYYY") + ', Caffeine Creations',
            ' *',
            ' */',
            '',
        ].join('\n');
    })(),
    raw: true,
  })

运行npx mix watch以让Laravel mix编译tailwind，设置浏览器同步，并合并脚本。
1. 要使SSL与browsersync和DDEV一起工作，请按照以下说明操作
- DDev启用SSL。您必须先将SSL证书复制到Docker之外的地方。在项目根目录运行此操作Stack Overflow
```
docker cp ddev-router:/etc/nginx/certs ~/tmp/certs
```
1. 您可能需要在您的OS用户目录中创建tmp/certs目录
2. 您可能只需为1个项目做一次，然后所有项目都应该可以正常工作。
Tailwind Config Viewer已设置并使用以下命令。运行npm run tw-config-viewer将在localhost:4000加载查看器，而运行npm run export-tw-config将查看器导出到public/tw-viewer
Tailwind Container Queries插件已安装。请参阅（文档）[https://github.com/tailwindlabs/tailwindcss-container-queries]

将@container类添加到父div中，然后使用前缀来针对容器大小，如下所示@lg:bg-pink-400。默认情况下，矩阵块具有@container，因此可以直接使用容器。

<div class="@container">
  <div class="@lg:bg-pink-400">
    This div will have a pink background when the container is larger than 32rem.
  </div>
</div>

生产环境

当您准备好部署代码时，运行npx mix -p以优化/src/img/中的图像，优化后的图像将输出到/public/assets/images

这将还会运行critical css任务，您可以在143行通过添加url和模板数组进行配置

  urls: [{
      url: '',
      template: 'home'
    },
    {
      url: 'contact',
      template: 'singles/contact'
    },
  ],

Tailwind

在存储库的根目录有一个空的tailwind.config.js文件。根据需要添加配置设置，但我确实在所有项目中使用了一些约定。

对于颜色，使用colornameBrand，其中colorname是red、blue或任何颜色。对于字体家族，使用字体名称。下面是从另一个项目中取出的示例，取自extend键。

colors: {
  redBrand: {
    light: '#fce9e8',
    default: '#de242b',
    dark: '#990e3d',
  },
  grayBrand: {
    light: '#f2f2f2',
    default: '#637a84',
  },
  textBrand: {
    light:'#334960',
    default: '#3a4250',
  },
  blackBrand: '#041e26',
},
fontFamily: {
  karla: ['Karla', 'sans-serif'],
  montserrat: ['Montserrat', 'serif'],
},

无障碍性

我旨在确保默认模板通过可访问性测试 - 除了颜色对比度之外，因为那需要在设计阶段考虑。

夜间模式

暗模式切换按钮已内置，并通过在_includes/dark-mode的101行添加include进行添加。如果您不使用dark-mode，则取消注释此文件。暗模式有3个按钮：暗色、亮色和系统，如我在此Dark Mode with Alpine.js and Tailwind的文章中所描述的

更新样式以使用暗模式前缀，如下所示。

<div class="bg-gray-100 dark:bg-gray-800">
  <h2 class="text-black dark:text-white">My title goes here</h2>
  <!-- more code -->
</div>

主导航

主导航有2个选项：一个在点击时激活下拉菜单，另一个在悬停时激活。出于可用性和可访问性的考虑，点击下拉菜单是首选方法。然而，有时客户坚持使用悬停，因此也提供了相应的选项。

模板默认为点击下拉菜单，要更改为悬停下拉菜单，请注释第67行并取消注释第74行中的 _layout.twig。

    {#
      // main nav click dropdown this is better user experience
      // and better for accessibility
      // works with tertiary level dropdowns
    #}
    {% include '_includes/main-nav' %}

    {#
      // main nav hover dropdown
      // we use this when client insists on hover dropdowns
      // does NOT work with tertiary dropdowns
    #}
    {# {% include '_includes/main-nav-hover' %} #}

片段

片段是用于创建可重用内容的一个部分。通常，你需要在网站的不同位置重复使用“呼叫行动”。在这个部分中，你创建这个呼叫行动，然后使用内容构建器中的片段块将其拖入该条目。

其他用途可能包括包含相关条目的块、幻灯片或展示照片的画廊。

已经添加了一个片段，它是一个带有联系页面按钮的呼叫行动。

浮动标签

浮动标签已经添加到css中。要使用浮动标签，为输入字段设置HTML如下：

<div class="relative">
  <input
    type="text"
    id="city"
    class="w-full rounded-lg floating-input"
    name="city"
    value=""
    autocomplete="city"
    aria-label="City Name"
    placeholder="City Name">
  <label for="city" class="floating-label">{{ "City Name"|t }}</label>
</div>

对于选择框，使用以下方式：

<div class="relative">
  <select
    name="country"
    id="country"
    class="rounded-lg floating-select"
    {# on click works with mouse but not keyboard... hmmm #}
    onclick="this.setAttribute('value', this.value);"
    value="">
    <option value=""></option>
    <option value="Canadas">Canada</option>
    <option value="USA">United States</option>
  </select>
  {# <span class="highlight"></span> #}
  <label class="floating-label">Country</label>
</div>

粘性头部

布局模板中有一个被注释的头部标签，启用后会使导航粘性。当向下滚动时将消失，当向上滚动时重新出现。

图片元素

此方法使用包含来生成具有多个源（webp回退到jpeg）的图片元素。使用以下示例代码将图片添加到任何页面：

如果图片为空，则使用来自 placeholder.com 的 回退图片 - 这可以在 _includes/responsiveImage.twig 文件的第21行进行更新。

{{ include('_includes/responsiveImage', {
  image: image,
  transforms: [
    {
      mq:'(max-width: 767.9px)',
      crop: {
        width: 500,
        height: 200,
        mode: 'crop'
      }
    },
    {
      mq:'(min-width: 768px)',
      crop: {
        width: 500,
        height: 200,
        mode: 'crop'
      }
    },
    {
      mq:'(min-width: 1024px)',
      crop: {
        width: 300,
        height: 100,
        mode: 'crop'
      }
    },
    {
      mq:'(min-width: 1280px)',
      crop: {
        width: 700,
        height: 250,
        mode: 'crop'
      }
    },
  ],
  attributes: {
    alt: image.altText ?? image.title ?? null,
    class: '',
    loading: 'lazy',
    dataAttributes: ''
  },
}, with_context = false) }}

Craft插件

以下插件已安装并准备好在网站上使用。我更喜欢将插件使用量保持在最低，除非绝对必要，否则请不要安装插件。如果可以使用原生方法完成，则应该使用原生方法。

环境标签 - 在控制面板上添加一个颜色条，指示当前环境
Minify - 在生产中对html/css/js进行压缩
CKEditor - 富文本编辑器
Retcon - 额外的twig过滤器
SEOmatic - 用于所有SEO。
控制面板CSS - 向CP添加自定义样式
Hyper - 用于按钮和其他链接
~~用户手册 - 在CP用户手册中~~ 已移除，直到Craft 5版本可用
Knock Knock - 保护预发布站点（密码：letmein）
Typogrify
Sprig - 响应式组件
AssetRev - 使用manifest.json文件名链接到css和js文件

Typogrify

有关高级用法，请参阅 typogrify文档。对于基本用法，将排版过滤器添加到redactor字段，如下所示：

{{ entry.copy|typogrify }}

Sprig

Sprig添加响应式组件。请参阅文档和/或我的关于使用Sprig的响应式分页的文章以获取示例。

此外，注意，在使用构建过程中提供的 localhost:3000 URL时，sprig将只重新加载组件一次。当构建/测试sprig组件时，请手动使用您的localhost域名重新加载 - 例如 https://site.ddev.com。

联系表单

联系表单由第一方 contact form插件和Sprig提供支持。请确保更新dotenv中的电子邮件变量，以便电子邮件可以正确工作。转到 插件 > 联系表单 并更新电子邮件的发送文本和主题文本。

样式指南

样式指南将自动从您的 Tailwind 配置中创建颜色调色板。 注意： - 它只适用于自定义颜色，不适用于 Tailwind 颜色。此外，自定义颜色需要添加到 Tailwind 颜色之前，并且需要采用以下格式

  grayBrand: {
    light: '#DADADA',
    DEFAULT: '#373F41',
  },

如果您有一个没有其他选项的颜色，则使用上述格式，并将 DEFAULT 作为键。

每次您更新颜色时，都需要运行以下命令

npm run export-tailwind-config

这将导出在 templates/_tw-config 中的 json 列表。也请参阅 templates/styleguide 中的注释。

取消注释具有 .testing 类的块，然后将生成的类复制/粘贴到 templates/_whitelist.twig 文件中。

内容

英雄组件

英雄组件有三个选项

标准英雄 - 图片，英雄标题，副本，按钮
基本英雄 - 没有图片，只有一个标题和深色背景
滑块英雄 - 与标准英雄相同，但作为滑块操作 - 最多 5 张幻灯片

还有一个基本矩阵字段用于内容构建器。一旦我有更多时间，我将创建一个长篇内容 CKEditor 字段来替换矩阵内容构建器。

Composer nuke

如果您需要删除供应商文件夹并基本上重置所有 composer 项，请运行此命令

composer nuke

这将删除供应商文件夹，composer.lock，清除 composer 缓存，然后运行 composer update。您可以在 composer.json 的脚本部分找到完整命令。

sean / craft-starter

维护者

详细信息