README

初学者是一个可扩展的设计系统/模式库，用PHP编写。默认情况下，它使用Twig进行模板化，使用Markdown/YAML进行文档。

安装

要创建一个新的初学者项目，请运行以下命令

composer create-project rareloop/primer my-primer-folder --remove-vcs

使用

最快的方法是使用内置的PHP独立服务器

composer server

然后在浏览器中打开以下URL https://:8080。

如果您需要指定端口，可以将此作为命令的参数传递

composer server 1234

入门

初学者有三个独立的部分

文档 - 存储您设计系统书面文档的地方。
模式 - 一个模式库，其中记录了系统中的所有组件。
模板 - 一种查看系统中可用的各种页面模板的方式。

模式

模式是系统的构建块，初学者提供了一个简单的方法来查看整个目录、选择或单个项目。模式位于resources/patterns文件夹中，并且本身就是一个包含所有相关文件的文件夹。

模式的结构

每个模式都有一个隐含的id和title。

id是用于在模式文件夹下识别它的路径，例如elements/forms/input。

模式title是从模式的文件夹名称构建的，例如elements/lists/ordered-list => 有序列表。

每个模式文件夹可以包含以下内容

模板用于构建模式HTML的Twig模板（template.twig）
一个或多个数据文件 提供模板文件所需的状态数据的文件

状态数据

出厂时，初学者支持两种状态数据的格式，PHP或JSON。

PHP状态数据

PHP状态数据文件命名为data.php，必须返回一个键/值数组。然后在渲染时将此数据传递给您的Twig模板。

<?php

return [
    'title' => 'Page Title',
];

JSON状态数据

状态数据也可以作为JSON文件提供，这些文件命名为data.json。然后在渲染时将此数据传递给您的Twig模板。

{
    "title": "Page Title"
}

替代状态数据

在构建模式库时，能够轻松测试组件可能处于的不同状态非常重要，初学者使这一点变得容易。可以通过向模式文件夹中添加额外的文件来提供替代状态，格式如下

data~statename.(php|json)

例如，为了显示输入组件的错误状态，您可以创建一个名为data~error.php的文件。

在模式之间包含

任何模式都可以通过使用标准的Twig include并引用模式的id来包含在另一个模式中，例如

{% include 'components/common/site-header' %}

模板

可以使用自定义HTML和模式include的混合来构建模板，并存储在resources/templates中。如果需要，可以通过添加文件夹来实现额外的分组/嵌套。

所有模板应继承自 primer-base.twig，并将自定义内容添加到 templateContent 块中，例如：

{% extends 'primer-base.twig' %}

{% block templateContent %}
    <h1>Example Template</h1>
    <p>This is an example page template that extends from the <code>primer-base.twig</code> file.</p>
{% endblock %}

文档

Primer 提供了一种简单的方式来使用 Markdown 文件展示您的 Design System 文档。

要添加新的文档页面，只需将 Markdown 文件（具有 .md 扩展名）添加到 resources/docs 文件夹中。您可以通过在结构中包含文件夹来创建分组/嵌套。

元数据

默认情况下，Primer 将根据文件名为您页面设置标题，但您可以通过在文件中添加 YAML 前置信息来覆盖此设置。例如，要指定标题和描述，您可以执行以下操作：

---
title: Page Title
description: This is a description
---
# Heading 1

Lorem ipsum dolor sit amet, consectetur adipisicing elit. Hic placeat iusto animi architecto quasi, praesentium.

title 和 description 都是 Primer 能够处理的关键字，但您可以自由地在前置信息中添加任何您喜欢的其他元数据。所有 Markdown 文件也会通过 Twig 环境，因此自定义元数据可以用来动态生成 HTML。

---
title: Page Title
description: This is a description
colours:
    - ff0000
    - 00ff00
    - 0000ff
---
# Colours

<ul>
{% for colour in colours %}
    <li>{{ colour }}</li>
{% endfor %}
</ul>

These are the colours we use!

添加前端资产

Primer 对您选择使用的前端栈没有特定意见。一旦您准备好向 HTML 添加 CSS 和 JavaScript 资产，您应该在 views/primer-base.twig 文件中这样做。这是所有 Primer 请求的共同祖先，这将确保您的模式和模板按照您的预期渲染。

稀疏循环/ 初学者

维护者

详细信息