@acanto/october-scripts 中文文档教程

Question

October scripts

Installation

首先进入项目根目录 cd myproject，然后：

npm i @acanto/october-scripts --save-dev

Usage

首先，您需要将以下内容添加到项目的 package.json 中：

  "scripts": {
    "start": "october-scripts start",
    "test": "october-scripts test",
    "page": "october-scripts page",
    "comp": "october-scripts component",
    "build": "october-scripts build",
    "setup": "october-scripts setup",
    "clean": "october-scripts clean",
    "deploy": "october-scripts deploy"
  }

您的根文件夹中运行：

# install dependencies
npm install

# run local development server with live reload
npm start

# generate a template, style and script for a specific page
npm run page my-page-name

# generate a template, style and script for a specific component
npm run comp my-component-name

# build the production code and start a local server running it
npm run test

# build the production code
npm run build

# clear OctoberCMS caches
npm run clean

# extract class names from page template and generate .scss file
october-scripts extract-page my-page-name

CI

然后从 部署运行：

# install dependencies
npm install

# build the production code ready for deployment
npm run deploy

Configuration

所有 gulp 配置都在 npm 上发布的独立包 @acanto/october-scripts 中，该项目仅使用其 package.json 文件来配置和运行脚本. 这样一个项目只有一个devDependency，脚本可以从每个项目中单独更新，这样每个项目都可以从更新中受益。

.env

如果未找到此文件，将自动生成尝试猜测值（执行数据库用户名和密码）

APP_URL=http://localhost/acanto/myproject
# BROWSER_SYNC_HOST=http://myproject.test
DB_HOST=myproject.acanto.net
DB_DATABASE=myproject_db
# DB_USERNAME=myuser
# DB_PASSWORD=mypassword

package.json

每个项目都需要设置 homepage 条目，并且可以覆盖 中脚本的一些基本配置>config 部分 package.json。 以下配置是必需的，需要根据您的特定项目进行相应更改：

  "homepage": "https://myproject.com",
  "config": {
    "favicons": {
      "background": "#fefefe"
    }
  }

Windows caveats

要在 Windows 上运行脚本，您可能需要转到系统属性和高级 - > 添加到环境变量-> 用户-> Path 附加以下变量：

• C:\Program Files\Git\cmd in order to be able to install npm packages directly from git remotes instead that from published versions git must be in the path source
• C:\Program Files\nodejs to run node scripts from the current directory

Features

• Live reload
• JS/SCSS modules bundling with webpack
• SCSS compilation with node-sass and postcss
• SCSS optimization combining media queries with css-mqpacker
• ES6 syntax support with babel
• CSS and JS files automatic splitting and cache busting
• SCSS and JS sourcemaps
• Page specific CSS inlining through October's partials
• Assets minification
• Images minification with imagemin
• SVG inline icons automatic generation from svg images
• Favicons auto-generation from single image with favicons
• License banner for compiled css and js files
• Page generator, .js, .scss and .htm templates
• TODO: Prettier for .htm templates

Folder structure

gulp 任务中使用的每个路径都可以在特定项目 package.json 文件中被覆盖（见下面的注释），但假设的理想和默认文件夹配置是以下内容：

  themes/
    acanto/
      assets/ # compiled files (.gitignored, DO NOT EDIT!)
      layouts/ # twig layout templates
      pages/ # twig page templates
        home.htm # page specific template
      partials/ # twig partials
        automated/ # compiled partials (.gitignored, DO NOT EDIT!)
        components/ # decoupled components to use across pages
          MyComponent.htm # component template
      src/ # sources of the assets that gets compiled
        components/ # decoupled components to use across pages
          MyComponent/ # component folder uses component name
            index.scss # component style
            index.js # component script
        config/ # conguration files
          index.scss # scss config (variables, mixins, functions, ecc.)
          index.js # js config (globals, settings, ecc.)
        pages # page specific and inlined in the corresponding template
          home.scss # page specific and scoped styles
          home.js # page specific and scoped scripts
        utils # utils generic components
          animations.scss # utils like styles
          animations.js # utils simple script
        vendor # custom vendor imports
          package-name.js # customised vendor import script
          package-name.scss # customised vendor import styles
        images/ # all images (will be compressed)
          icons/ # svg images that will be turned automatically in an icon font
        fonts/ # custom fonts for the specific theme
        theme.js # entry point with all js/scss imports

Dev notes

Environment variables

October 有一个内置功能用 dotenv-ready 代码替换配置变量，你可以从根目录运行 php artisan october:env。 这些更改了一些本地配置文件，我们感兴趣的是config/app.php、config/database.php和config/environment.php。

Cache issues

• lftp manual page. One option would be to use the lftp option --transfer-all but that would probably take more time than the touch gulp task.
• Related to October CMS caching issue see: https://github.com/octobercms/october/issues/446, https://octobercms.com/forum/post/caching-of-partials, https://octobercms.com/forum/post/cached-view-partials-can-not-clear?page=1

CSS/JS inlining

要在 HTML 中内联共享的 js/css 块，我们可以简单地这样做：

==
use Cms\Classes\Theme;

function onStart() {
  ...

  $appCssPath = themes_path(Theme::getActiveThemeCode() . "/assets/styles") . "/theme.css";
  $this['appCssRelativePath'] = '../assets/styles/theme.css';
  $this['appCssFilesize'] = filesize($appCssPath) / 1024;
}

==

{% if appCssFilesize < 52 %}
<style>{{ source(appCssRelativePath) }}</style>
{% else %}
<link href="{{ 'assets/styles/theme.5f616e7af5a515c60829.css'|theme }}" rel="stylesheet" />
{% endif %}

但是字体的相对路径会中断，我们应该根据环境为字体提供绝对路径。 另外，我们应该使用 webpack 生成一个非散列文件并小心，因为使用这种方法我们假设只有一个共享/公共块，但 js 动态导入可能会有更多。