README

这是 Steffen Wargalla 的 Kirby 3 Patterns 插件的分支和更新版本。

它做什么？

使用 Kirby Patterns，您可以使用干净的可重用模块构建您的网站，同时插件会自动为您创建一个活生生的样式指南。

视频演示

https://vimeo.com/153132557

屏幕截图

https://gist.github.com/bastianallgeier/27f604fc838a266be482#gistcomment-1677662

安装

安装 Kirby。我建议 Kirby 的 Plainkit
从 Github 下载 Kirby Patterns
将 patterns 文件夹复制到 /site/plugins（如果尚未创建，则创建插件文件夹）
在新的 /site/patterns 文件夹中创建您的图案。

Patterns readme.md

在安装后的第一步中，您应该在 /site/patterns 中放置一个 readme.md。这将被 Patterns 界面自动用于提供一个漂亮的简介页面。

选项

以下选项可以设置在您的 /site/config/config.php

return [
    'amteich.patterns.lock' => true,
    'amteich.patterns.title' => 'Kirby Pattern Lab',
    'amteich.patterns.path' => 'patterns',
    'amteich.patterns.directory' => '/var/www/yoursite.com/site/patterns',
    'amteich.patterns.error' => 'error',
    'amteich.patterns.preview.mode' => 'preview',
    'amteich.patterns.preview.background' => false,
    'amteich.patterns.preview.css' => 'assets/css/index.css',
    'amteich.patterns.preview.js' => 'assets/js/index.js'
];

patterns.lock

您可以将 Patterns 界面锁定，这样只有首先登录到 Kirby Panel 的用户才能访问。

patterns.title

设置在浏览器和 Patterns 界面顶栏中显示的标题。默认设置为 Patterns

patterns.path

您可以使用此选项更改 Patterns 界面的位置。默认情况下，它将位于 http://yourdomain.com/patterns。但请仅使用此选项设置路径。URL 必须省略。

patterns.directory

使用此选项设置您的图案目录的完整路径。默认情况下，图案目录必须位于 site/patterns

patterns.preview.mode

默认模式是显示具有 HTML 模板文件的 iframe 预览，以显示图案在您网站上的外观。但这可以将此选项更改为 twig 或 html 以默认切换到特定选项卡。

有效值

preview (默认)
twig
html

patterns.preview.background

您可以使用此选项来设置图案预览屏幕的默认背景颜色。可以使用任何有效的CSS值。默认情况下，未设置特定的颜色值。图案可以使用background选项（见下文）来覆盖此设置。

patterns.preview.css

使用此选项来设置您图案的最终CSS所在位置。所有指定的CSS文件将按顺序在预览屏幕中加载，以便适当地样式化您的图案。默认情况下，图案界面正在寻找一个/assets/css/index.css文件。

您可以通过传递文件数组来加载多个CSS文件。

'amteich.patterns.preview.css', ['assets/css/main.css', 'assets/css/theme.css']);

patterns.preview.js

使用此选项来设置您图案的最终JS所在位置。所有指定的JS文件将按顺序在预览屏幕（页脚）中加载，以便应用您的图案的行为。默认情况下，图案界面正在寻找一个/assets/js/index.js文件。

您可以通过传递文件数组来加载多个JS文件。

'amteich.patterns.preview.js', ['assets/js/jquery.js', 'assets/js/patterns.js']);

创建图案

您可以在/site/patterns下为每个图案添加一个子文件夹，甚至可以根据需要嵌套它们。

图案文件夹可以包含任何数量的文件，这些文件属于该图案。

您应该提供一个markdown文件来为您的图案添加文档。图案界面将自动解析markdown并将其转换为精美的文档页面。您甚至可以在markdown文件中使用Kirbytext。

图案模板

图案不一定需要模板文件，但如果您想在模板或片段中使用它们，您应该在图案文件夹中创建一个名为{patternname}.twig的文件。

在您的图案模板中，您可以使用Kirby的API中的所有方法和函数。您完全有权访问$site、$pages和$page变量以及 cheat sheet 中提到的所有其他内容。

图案配置

您可以在图案中添加一个可选的config.php文件来进一步设置它。

图案配置文件必须返回一个关联的PHP数组。

<?php 

return [
  // your pattern config goes here
];

标题

图案的默认标题是图案文件夹的名称。您可以在配置中更改它，使其更易于阅读。

return [
  'title' => 'Pattern Title'
];

默认值

使用defaults变量，您可以将数据传递给图案，当使用图案时，如果它没有被图案方法覆盖，将使用这些数据。

return [
  'defaults' => [
    'title' => 'Default title',
    'text'  => 'Default text'
  ]
];

背景

使用background变量，您可以确定图案预览的背景颜色。如果图案本身没有在CSS中定义背景颜色，但总是在另一个图案中使用，例如在深色背景上放置时，这可能很有用。可以使用任何有效的CSS颜色值。

return [
  'background' => '#000'
];

隐藏

有时在模式文件夹中创建一个模式可能很有用，这个模式在模式界面中不应可见。您可以使用 hide 变量来隐藏特定的模式。

return [
  'hide' => true
];

预览

预览回调选项可以在模式在模式界面中渲染之前执行代码。这有助于为模式生成动态默认值，这些默认值仅用于预览，而不会在您网站上使用该模式时使用。

可选地，回调可以返回一个关联数组，该数组将用于设置/覆盖模式的默认值。

return [
  'preview' => function() {

    site()->visit('some/page');

    return [
      'title' => page('blog/article-xyz')->title(),
      'text'  => 'Lorem ipsum…'
    ];

  }
];

使用模式

要在您的 Kirby 模板或片段中使用模式，您可以使用新的 pattern() 方法，该方法将在插件安装后立即可用。

<?php pattern('header/logo') ?>

向模式传递选项

您可以向模式传递额外的变量和选项，并以此方式覆盖其默认值。

<?php pattern('header/logo', ['class' 'logo logo-on-black']) ?>

嵌套模式

您可以直接在模式模板文件中使用 pattern() 方法来嵌套模式。

构建过程示例

由于所有 CSS 和 JS 文件都应该直接与模式存储，因此您可能需要某种构建过程来预处理/后处理、连接和压缩它们。插件不会强迫您采用任何特定的工作流程。这里有一个简单的 gulp 文件示例，尽管我将其用作项目的模板

var gulp   = require('gulp');
var concat = require('gulp-concat');
var rename = require('gulp-rename');
var uglify = require('gulp-uglify');
var cssmin = require('gulp-cssmin');
var sass   = require('gulp-sass');
var image  = require('gulp-image');

gulp.task('js', function() {

  return gulp.src([
      // array of js files. i.e.:
      // 'site/patterns/js/jquery/jquery.js',
      // 'site/patterns/gallery/fotorama/fotorama.js'
    ]) 
    .pipe(concat('index.js')) 
    .pipe(gulp.dest('assets/js'))
    .pipe(rename('index.min.js'))
    .pipe(uglify()) 
    .pipe(gulp.dest('assets/js'));

});

gulp.task('css', function() {

  return gulp.src('site/patterns/site/site.scss')
    .pipe(sass().on('error', sass.logError)) 
    .pipe(rename('index.css'))
    .pipe(gulp.dest('assets/css'))
    .pipe(rename('index.min.css'))
    .pipe(cssmin()) 
    .pipe(gulp.dest('assets/css'));    

});

gulp.task('images', function() {
  gulp.src('site/patterns/**/*.{jpg,gif,png,svg}')
    .pipe(image())
    .pipe(gulp.dest('assets/images'));
});

gulp.task('default', [
  'css', 
  'js', 
  'images'
]);

gulp.task('watch', ['default'], function() {
  gulp.watch('site/patterns/**/*.scss', ['css']);
  gulp.watch('site/patterns/**/*.js', ['js']);
  gulp.watch('site/patterns/**/*.{jpg,gif,png,svg}', ['images']);
});

要使用此文件，您必须首先通过 npm 安装依赖项

npm install --save-dev gulp
npm install --save-dev gulp-concat
npm install --save-dev gulp-rename
npm install --save-dev gulp-uglify
npm install --save-dev gulp-cssmin
npm install --save-dev gulp-sass
npm install --save-dev gulp-image

之后，您可以通过运行 gulp 来构建资源，或运行 gulp watch 来在模式上工作并实时转换资源。

我绝对不是最好的前端开发者，因此我确信您将找到一种更聪明的设置构建过程的方法，无论是使用 grunt、gulp 还是 npm。

自定义模式界面的设计

默认的深色主题可能不适合所有人，但加载自己的样式表甚至 js 来自定义界面非常简单。应用程序正在寻找 /assets/patterns/index.css 和 /assets/patterns/index.js 文件。如果没有提供，它将加载默认主题。因此，通过添加这些文件，您可以覆盖任何想要覆盖的样式。

要求

Kirby 3.0.0+
PHP 7.1+
Kirby-Twig 插件 - https://github.com/amteich/kirby-twig

许可证

https://open-source.org.cn/licenses/mit-license.php

作者

amteich / kirby-patterns

维护者

详细信息