pgchamberlin/chintz

语言: CSS

git: https://github.com/pgchamberlin/chintz

README.md (中文)

印花棉布

什么是印花棉布

除了作为华丽模式的(有时是贬义的)名称之外,Chintz是用于以面向原子组件的方式存储和呈现静态前端元素的规范。

Chintz diagram

通过以与语言无关,面向组件的方式存储前端组件,它们变得更加便携,更可重用,更易于维护,更易于测试。

在BBC新闻中,我们主要使用PHP和Ruby,因此我们已经开始在这些语言中为Chintz实现客户端。从长远来看,我们希望建立一个JS,并对其他实现持开放态度。在PHP中,我们在~110 LOC和Ruby~50 LOC中破解了客户端的核心实现,因此您可能会发现将Chintz支持移植到您选择的语言是相当简单的。

工作正在进行中

这个规范正在进行中并且是无法实现的,并且几乎只是两天黑客攻击的产物,但正在积极维护,并有望成长为一个稳定和完整的系统。

印第安人图书馆

1.什么是印花棉兹图书馆?

Chintz库是符合此规范的任何存储库或目录树。它可以被指定的任何有效Chintz Parser消耗(见下文)。

2. Chintz Library:目录结构

Chintz库具有以下基本目录结构:

.
├── elements
│   ├── atoms
│   ├── molecules
│   └── organisms
└── fixtures

3.元素

元素是模板,静态依赖项和/或其他元素的任何分组。

从模式实验室获取线索,每个元素可以分为原子,分子或有机体。这些之间的界限有时可能会模糊,但我们将每个视为元素的概括。就任何解析器而言,它们都是一样的。它为组织的其他部分(UX利益相关者,产品利益相关者)增加了价值,以便能够根据这些分类来考虑前端元素。

4.元素目录结构

每个元素在/ atoms,/ molecules或/ organisms中都有自己的目录。在每个目录中都有   - YAML格式的清单   - 零个或多个模板文件   - 您选择的解析器支持零或更多CSS,SCSS,JS或其他静态依赖项

一个示例Chintz目录树

.
├── elements
│   ├── atoms
│   │   └── exampleAtom
│   │       ├── exampleAtom.yaml
│   │       ├── exampleAtom.mustache
│   │       └── someJs.js
│   ├── molecules
│   │   └── exampleMolecule
│   │       ├── exampleMolecule.yaml
│   │       ├── exampleMolecule.mustache
│   │       └── someCss.css
│   └── organisms
│       └── exampleOrganism
│           ├── exampleOrganism.yaml
│           ├── moreCss.css
│           ├── anotherJs.js
│           └── exampleOrganism.mustache
└── fixtures

清单

清单必须指明   - 元素的名称

清单也可以列出   - 依赖性   - 支持的数据类型

如果元素有自己的模板   - 模板将存储在目录中   - 模板将与元素具有相同的名称

一个例子Chintz清单

name: exampleElement
dependencies:
  css: [ base/base.css, base/typography.css ]
  js: [ exampleElement/someOtherFilename.js ]
  elements: [ anotherThing ]

Chintz Parser

1.什么是Chintz Parser?

Chintz Parser是任何可以解析Chintz库并提供下述功能的代码库。这是一个松散的规范,但任何实现都应该满足以下所有目标。

2.目标

2.1理解Chintz清单

解析器应该能够读取Chintz Manifest并确定以下信息:

  • 元素的名称是什么
  • 该元素具有哪些依赖关系

2.2解决依赖关系

解析器应该能够解决

  • 所有静态依赖项的文件位置
  • 所有元素依赖关系的模板位置和静态依赖关系

2.3渲染模板

解析器应该能够呈现模板,通常但不一定使用诸如Mustache之类的引擎。

3.建议的界面

3.1初始化

应该可以使用依赖项初始化Parser

  • 模板引擎的实例,例如Mustache
  • 用于解析特定依赖关系的零个或多个格式化程序实例,应在Parser实例中注册

3.2公共方法

Chintz Parser应该公开以下方法:prepare,render和getDependencies。

准备

准备方法应该:

  • 采取一个论点;单个元素名称或它们的数组/列表
  • 读取每个元素的清单,并解决其依赖关系 - 在其他元素的情况下递归
  • 在适当的位置注册每个元素的模板路径到模板渲染器
给予

render方法应该:

  • 拿两个论点;元素名称和直接可渲染格式的数据参数
  • 将这些参数传递给初始化的模板渲染器
getDependencies

getDependencies方法应该:

  • 采用单个参数,在Manifest中键入依赖项的名称,例如'js'
  • 默认情况下,返回在准备步骤中已解析的指定依赖关系的数组/列表
  • 如果存在依赖项的已注册格式化程序,则在该实例上调用format方法,传递默认数组/列表并返回结果

4.国家

Chintz Parser的单个实例应该能够准备任何合理数量的元素,以便可以使用任何数据呈现它们中的任何一个,以任何顺序调用。

Chintz Parser的实例应该只维护一组依赖项,这是由实例准备的元素的所有依赖项的重复数据删除总和。

常问问题

是否有任何解析器实现?

是的,有一个PHP实现:chintz-parser-php和Ruby实现:chintz-ruby。两者都在进行中,但请随意分叉并做出贡献。

有演示吗?

是的,有一个演示回购:chintz-parser-php-demo。你可以在这里看到它。它使用PHP Chintz解析器,chintz-parser-php。

为什么“元素”而不是“组件”

“组件”一词表示一个完整的抽象,它映射到一个可模板化的前端视图,而在这个规范中,没有假设任何给定的元素都有一个视图。元素可以仅表示一组CSS依赖项或一组字体。因此,组件可以由许多元素组成,并且元素可以表示组件。遗憾的是,这可能会与HTML中的元素概念产生混淆,但我还没有想到更好的名称。

本文使用googletrans自动翻译,仅供参考, 原文来自github.com

en_README.md

Chintz

What is Chintz

Aside from being a (sometimes derogatory) name for flowery patterns, Chintz is a spec for storing and rendering static front end elements in atomic component-oriented way.

Chintz diagram

By storing front end components in a language-agnostic, component-oriented way, they become more portable, more reusable, more maintainable, and easier to test.

In BBC News we are working mainly with PHP and Ruby, so we have begun implementing clients for Chintz in those languages. In the long term we hope to build a JS one, and are open minded about other implementations. In PHP the we hacked up the core implementation of the client in ~110 LOC, and in Ruby ~50 LOC, so you might find porting Chintz support to your language of choice is fairly straightforward.

Work in progress

This spec is work in progress and is unversioned, and pretty much just the product of a two-day hack, but is being actively maintained and will hopefully grow into a stable and complete system.

Chintz Library

1. What is a Chintz Library?

A Chintz Library is any repository or directory tree which conforms to this specification. It can be consumed by any valid Chintz Parser as specified (see below).

2. Chintz Library: directory structure

Chintz libraries have the following base directory structure:

.
├── elements
│   ├── atoms
│   ├── molecules
│   └── organisms
└── fixtures

3. Elements

An Element is any grouping of templates, static dependencies, and/or other elements.

Taking cues from Pattern Lab, each Element can be classified as either an Atom, Molecule, or Organism. The boundaries between these can sometimes be blurry, but we treat each as a generalisation of an Element. As far as any parser is concerned they are all the same thing. It adds value in other parts of the organisation (UX stakeholders, product stakeholders) to be able to think about the front end elements in terms of these classifications however.

4. Element Directory Structure

Each element has its own directory within either /atoms, /molecules, or /organisms. Within each directory there is
- A manifest in YAML format
- Zero or more template files
- Zero or more CSS, SCSS, JS, or other static dependencies supported by your parser of choice

An example Chintz directory tree

.
├── elements
│   ├── atoms
│   │   └── exampleAtom
│   │       ├── exampleAtom.yaml
│   │       ├── exampleAtom.mustache
│   │       └── someJs.js
│   ├── molecules
│   │   └── exampleMolecule
│   │       ├── exampleMolecule.yaml
│   │       ├── exampleMolecule.mustache
│   │       └── someCss.css
│   └── organisms
│       └── exampleOrganism
│           ├── exampleOrganism.yaml
│           ├── moreCss.css
│           ├── anotherJs.js
│           └── exampleOrganism.mustache
└── fixtures

5. The manifest

The manifest must specify
- The name of the element

The manifest may also list
- Dependencies
- Supported data types

If the element has its own template
- The template will be stored in the directory
- The template will have the same name as the element

An example Chintz manifest

name: exampleElement
dependencies:
  css: [ base/base.css, base/typography.css ]
  js: [ exampleElement/someOtherFilename.js ]
  elements: [ anotherThing ]

Chintz Parser

1. What is a Chintz Parser?

A Chintz Parser is any code library which can parse a Chintz Library and provide the functionality described below. This is intentionally a loose specification, but any implementation should satisfy all of the following goals in general terms.

2. Goals

2.1 Make sense of Chintz manifests

The Parser should should be able to read a Chintz Manifest and determine the following information:

  • What is the name of the element
  • What dependencies does the element have

2.2 Resolve dependencies

The Parser should be able to resolve

  • File locations for all static dependencies
  • Template locations and static dependencies for all element dependencies

2.3 Render templates

The parser should be able to render templates, typically but not necessarily using an engine such as Mustache.

3. Proposed interface

3.1 Initialisation

It should be possible to initialise the Parser with dependencies

  • An instance of a templating engine, such as Mustache
  • Zero or more instances of formatters for the resolution of specific dependencies, which should be registered in the Parser instance

3.2 Public methods

The Chintz Parser should expose the following methods: prepare, render, and getDependencies.

Prepare

The prepare method should:

  • Take a single argument; either a single element name or an array/list of them
  • Read the Manifest for each element, and resolve its dependencies - recursively in the case of other elements
  • Register each element's template path where appropriate to the template renderer
Render

The render method should:

  • Take two arguments; an element name and a data parameter in a directly renderable format
  • Pass these params into the initialised template renderer
getDependencies

The getDependencies method should:

  • Take a single argument, the name of the dependency as keyed in the Manifests, for example 'js'
  • By default return an array/list of the specified dependency as resolved during the prepare step
  • If there is a registered formatter for the dependency, call a format method on that instance, passing the default array/list and returning the result

4. State

A single instance of the Chintz Parser should be able to prepare any reasonable number of Elements, so that any of them can be rendered with any data, being called in any order.

An instance of a Chintz Parser should only ever maintain a single set of dependencies, which is the deduplicated sum of all the dependencies of the elements prepared by the instance.

FAQ

Are there any parser implementations?

Yes, there is a PHP implementation: chintz-parser-php, and a Ruby implementation: chintz-ruby. Both are work in progress, but please feel free to fork and contribute.

Is there a demo?

Yes, there is a demo repo: chintz-parser-php-demo. You can see it in action here. It uses the PHP Chintz parser, chintz-parser-php.

Why "element" rather than "component"

The word "component" suggests a complete abstraction which maps to a templateable front end view, whereas within this spec there is no assumption that any given element will have a view. An element may just represent a set of CSS dependencies, or a set of fonts. So a component may be made up of many elements, and an element may represent a component. It is unfortunate that this may create confusion with the concept of an element in HTML, but I haven't thought of a better name yet.