README

Sitegeist.Monocle

Neos 的动态样式指南

此包为 Neos 添加了一个样式指南模块，用于渲染标注有 @styleguide 的 Fusion 原型。

作者与赞助商

• Martin Ficzel - ficzel@sitegeist.de
• Wilhelm Behncke - behncke@sitegeist.de

此包的开发和公共发布得到了我们雇主 http://www.sitegeist.de 的慷慨赞助。

动态样式指南

Monocle 模块使用真实的 Fusion 代码渲染标注的独立原型。因此，样式指南始终是最新的，并且不会随着时间的推移而偏离实际代码库。

Monocle 是基于 Atomic-Design 和纯 Fusion（无流体）设计的，但实现不依赖于编码风格和模板引擎。您可以使用 Monocle 无限制地渲染基于流体的原型。

安装

Sitegeist.Monocle 通过 packagist 提供，可以使用命令 composer require sitegeist/monocle 安装。

我们使用语义版本控制，因此每次重大更改都会增加主版本号。

使用方法

创建样式指南条目

要渲染原型为样式指南条目，只需对其进行标注即可

prototype(Vendor.Package:Components.Headline) < prototype(Neos.Fusion:Component) {

    #
    # styleguide annotation to define title, description and props for the styleguide
    #
    @styleguide {
        title = 'My Custom Prototype'
        description = 'A Prototype ....'
        props {
            content = 'Hello World'
        }
        useCases {
            h2 {
                title = "My Custom Prototype as Headline 2"
                props {
                    tagName = 'h2'
                    content = 'Alternate styleguide content for h2'
                }
            }
        }
    }

    #
    # normal fusion props and renderer
    #
    tagName = 'h1'
    content = ''

    renderer = afx`
        <Neos.Fusion:Tag tagName={props.tagName}>{props.content}</Neos.Fusion:Tag>
    `
}

样式指南将渲染条目，而不包含通常的上下文。故意不在样式指南渲染中提供 site、documenNode 和 node 上下文变量。

因此，可以确保您的原型仅依赖于融合路径进行渲染，并且不受编辑器数据的影响。这对于组件的可靠测试非常重要。

要映射实际内容节点到组件原型，请使用单独的融合原型。

prototype(Vendor.Package:Content.Headline) < prototype(Neos.Neos:ContentComponent){
    content = ${q(node).property('title')}

    renderer = Vendor.Package:Components.Headline {
        @apply.props = ${props}
    }
}

这样，渲染原型与映射原型完全分离，因此具有高度的复用性。

渲染原型与映射原型的区分可以与 ReactJS 世界中的呈现组件与容器组件进行比较。

预览容器

通常组件必须在样式指南中作为另一个组件渲染。在这种情况下，可以在样式指南注释中定义一个 container。容器作为处理器应用于当前预览的原型，渲染内容作为 value 在上下文中可用。

prototype(Vendor.Site:ExampleComponent) < prototype(Neos.Fusion:Component) {
    @styleguide {
        container = Vendor.Site:ExampleContainer {
            content = ${value}
        }
    }

    renderer = afx`
        <h1>Hello World</h1>
    `
}

为了灵活性，建议在容器原型上定义一个属性 content = ${value}，确保容器可以作为处理器或通过 afx 使用标签子代。

prototype(Vendor.Site:ExampleContainer) < prototype(Neos.Fusion:Component) {
    content = ${value}
    renderer = afx`
        <div class="container">{props.content}</div>
    `
}

# Use of container as processor ... content passed via `value` context
example_processor = 'Hello World'
example_processor.@process.inContainer = Vendor.Site:ExampleContainer

# Use of container in afx ... content passed as `content`-prp
example_afx = afx`
    <Vendor.Site:ExampleContainer>Hello World'</Vendor.Site:ExampleContainer>
`

当多个样式指南元素嵌套时，请注意，仅渲染最外层元素的容器。对于所有嵌套元素，将省略容器。这也适用于由 Sitegeist.Monocle:Preview.Prototype 渲染的原型。

用例

样式指南注解中的 useCases 部分允许配置组件预览的场景。如果用例定义了 props 或 container，则将覆盖此组件的样式指南设置。 title 是可选的，将回退到用例定义的键。

prototype(Vendor.Site:Example.Component) < prototype(Neos.Fusion:Component) {

    @styleguide {
        title = "Example"

        container = Vendor.Site:Example.Container
        props {
            title = 'Hello world!'
        }

        useCases {
            case1 {
                title = "Use case with varying props"
                props {
                    title = Hello special world!'
                }
            }
            case2 {
                title = "Use case with another container"
                container = Vendor.Site:Example.AnotherContainer
            }
        }

属性集!!! 已弃用!!!

!!! PropSets 已弃用，不应与 UseCases 混合使用。Monocle 不会为具有 useCases 的组件显示 PropSet 选择器，并且 API 端点在选择用例后将忽略 propSets。如果 PropSet 功能给 monocle 维护带来额外的工作，它将在下一个主要版本中被移除 !!!

PropSets 允许为 props 指定额外的值，这些值将合并到组件的主要样式指南 props 中，以允许模拟更广泛的组件使用场景。

prototype(Vendor.Site:Example.Component) < prototype(Neos.Fusion:Component) {

    @styleguide {
        title = "Example"
        props {
            title = 'Hello world!'
        }
        propSets {
            longTitle {
                title = 'A very long title for testing ... because reasons'
            }
        }
    }
}

预览配置

有一些配置可用于配置预览。

Sitegeist:
  Monocle:
    preview:
        #
        # The fusion path that renders the preview.
        # the available context is has the values
        #  - sitePackageKey
        #  - prototypeName
        #  - propSet
        #  - props
        #
        fusionRootPath: '/<Sitegeist.Monocle:Preview.Page>'

        #
        # The fusion prototype that is rendered initially
        # Optional: Will default to the first found prototype
        #
        defaultPrototypeName: 'Vendor.Site:Prototype'

        #
        # The query selector that is used to extract the component html
        # from the preview to the html-view.
        # Optional: Default is 'body'
        #
        sourceQuerySelector: 'body'

要将您的样式和脚本包含到预览中，您可以通过与自定义 Neos.Neos:Page 相同的方式扩展 Sitegeist.Monocle:Preview.Page 原型。

//
// Add stylesheets to to the preview-prototype
//
prototype(Sitegeist.Monocle:Preview.Page) {
    head {
        stylesheets.main = Vendor.Site:Resources.Styles
        javascripts.main = Vendor.Site:Resources.Scripts
    }

    bodyScripts = Vendor.Site:Resources.BodyScripts {
        @position = 'before closingBodyTag'
    }
}

网格

monocle ui 配置中的 grids 键允许指定一个响应式布局网格可视化，可以在 monocle ui 或预览端点中激活。

每个网格有以下选项

• mediaQuery (字符串，必需) 网格将激活的媒体查询

• columns (整数，必需) 列数

• gap (字符串，必需) 列之间的间隙，CSS 单位如 "10px"

• gutter (字符串，必需) 网格周围的边框，CSS 尺寸如填充的 "0px 20px"

• label (字符串，可选) 网格配置的名称

• width (字符串，默认: 100%) 网格的 CSS 宽度。默认

• maxWidth (字符串，可选) 网格的 CSS 最大宽度

• margin (字符串，默认: "0px auto") 网格周围的 CSS 外边距

!!! 网格可视化假设文档的主体没有填充或外边距。如果不是这种情况，网格可能无法正确定位或尺寸化 !!!

Sitegeist:
  Monocle:
    ui:
      grids:
        small:
          mediaQuery: '(min-width:0px) and (max-width: 599px)'
          label: "Small"
          columns: 4
          gap: 16px
          gutter: 10px 20px
        medium:
          mediaQuery: '(min-width:600px) and (max-width: 1023px)'
          label: Medium
          columns: 8
          gap: 16px
          gutter: 10px 20px
        large:
          mediaQuery: '(min-width:1024px)'
          label: Large
          columns: 12
          maxWidth: 1024px
          gap: 16px
          gutter: 10px 20px

视口

要配置可用的视口预设，您可以更改以下配置。

Sitegeist:
  Monocle:
    ui:
      viewportPresets:
        xs:
          label: 'xtra small'
          width: 400
          height: 600
        md:
          label: 'medium'
          width: 600
          height: 400
        l:
          label: 'wide'
          width: 800
          height: 600

区域

如果您在组件中有翻译，您可以通过设置配置可用的区域。

Sitegeist:
  Monocle:
    ui:
      localePresets:
        en:
          label: 'English'
          fallback: ['en_UK', 'en']
        de:
           label: 'German'
           fallback: ['de', 'en']
        fr:
          label: 'French'

快捷键（实验性）

Monocle 的某些元素可以通过键盘控制。所有使用的快捷键都可以通过设置进行配置。但是，这似乎并不总是可靠 - 因此，请注意，在覆盖默认快捷键配置时，您可能会遇到奇怪的副作用。

Sitegeist:
  Monocle:
    ui:
      hotkeys:
        openNavigation: 'ctrl+f'
        closeNavigation: 'esc'
        navigateUp: 'up's
        navigateDown: 'down'
        openPreviewInNewWindow: 'ctrl+space'

结构

Monocles 导航机制的核心是原型选择器。在这个组件中，您将找到所有用 @styleguide 注释的组件，按可配置的准则分组。

此类组的一个可能的配置如下所示

Sitegeist:
  Monocle:
    ui:
      structure:
        base:
          position: 100
          match: Components?\.Base
          label: Base
          icon: icon-minus
          color: '#AAA'

在配置路径 Sitegeist.Monocle.preview.structure 下，您可以定义任意数量的组件组。每个组由以下内容组成

• 一个 label，将在 UI 中显示
• 一个 icon，将附加到组中的每个组件
• 一个 color，将应用于图标
• 一个 matcher - 一个正则表达式，将应用于组件原型的非包部分，从而确定组件属于配置的组。

Monocle 配备了一个默认的结构配置，试图表示类似 Atomic-Design 的结构。因此，配置包括 atoms、molecules、organisms 和 templates 的默认值。

不匹配任何配置组的每个组件将被放入 unknown 组。

隐藏组件

如果您不想显示组件，您可以如下定义 hiddenPrototypeNamePatterns

Sitegeist:
  Monocle:
    hiddenPrototypeNamePatterns:
      - 'Vendor.Site:*'
      - 'Another.Vendor.Site:Prototype'

即使组件匹配 hiddenPrototypeNamePatterns 模式，也可以将特定组件 "取消隐藏"

Sitegeist:
  Monocle:
    alwaysShowPrototypes:
      - 'Vendor.Site:Some.Component.ThatShouldBeShown'
      - 'Another.Vendor.Site:Prototype.ThatShouldBeShown'

这允许选择性地包含包的原型。

包特定配置

所有配置都可以为每个选定的站点包覆盖。

Sitegeist:
  Monocle:
    packages:
      'Vendor.Site':
        ui:
          viewportPresets:
              xxl:
                label: 'extra wide'
                width: 1600
                height: 1000

此包的配置也可以用于在风格指南中预览非站点包。

当非站点包的原型被渲染时，Monocle将只加载该特定包的Root.fusion和Monocle的Root.fusion。其他所有融合，包括默认融合，都必须显式包含。这模仿了用于Flow Controller Actions的FusionRendering的经典FusionView的行为。

Sitegeist:
  Monocle:
    packages:
      #add a key to the package list without package specific configuration
      'Vendor.Example': {}

融合

Sitegeist.Monocle提供了一些融合原型，您可以使用或根据您的需求调整。

Sitegeist.Monocle:Preview.Page

原型Sitegeist.Monocle:Preview.Page用于渲染原型的预览视图，为此它使用下面的Sitegeist.Monocle:Preview.Prototype。您可以扩展此原型以添加您的样式和脚本，就像使用Neos.Neos:Page一样。

prototype(Sitegeist.Monocle:Preview.Page) {
    head {
        metaViewport = '<meta name="viewport" content="width=device-width">'

        stylesheets.main =  Neos.Fusion:Tag {
            tagName = 'link'
            attributes.rel = 'stylesheet'
            attributes.href = Neos.Fusion:ResourceUri {
                path = 'resource://Vendor.Site/Public/Styles/main.css'
            }
        }

        javascripts.main = Neos.Fusion:Tag {
            tagName = 'script'
            attributes.src = Neos.Fusion:ResourceUri {
                path = 'resource://Vendor.Site/Public/JavaScript/main.js'
            }
        }
    }
}

您必须将相同的头部信息添加到Sitegeist.Monocle:Preview.Page和Neos.Neos:Page，以确保风格指南中渲染的结果与前端相同。为此，建议将这些信息集中到融合组件中。

Sitegeist.Monocle:Preview.Prototype

原型Sitegeist.Monocle:Preview.Prototype用于使用风格指南属性渲染单个原型。如果您想将结果作为prop提供给另一个原型的预览，这很有用。

原型允许指定以下选项

• prototypeName：字符串，原型的名称
• propSet：字符串，应用于默认属性的propSet的名称
• props：数组，key => value对的键值对，除defaultProps和propSet外还应用

以下示例显示了如何使用Sitegeist.Monocle:Preview.Prototype在风格指南prop中渲染预览

prototype(Vendor.Site:ContainerExample) {
    @styleguide{
        props.content = Sitegeist.Monocle:Preview.Prototype {
            prototypeName = 'Vendor.Site:Item'
            propSet = 'large'
        }
    }
    ...
}

模拟API端点

Monocle有融合原型来模拟组件的json API响应。

Sitegeist.Monocle:DataUri

通用的数据URI实现，期望type和content作为字符串

    endpointUrl = Sitegeist.Monocle:DataUri {
        content = '{"hello":"world"}'
        type = 'application/json'
    }

DataUri-原型将内容编码为base64。注意：数据URI不接受url参数。如果您的客户端代码向模拟添加参数，您必须注意这一点。

为方便起见，存在特殊的json和text原型

• Sitegeist.Monocle:DataUri.Json：具有媒体类型application/json的端点模拟，将通过Json.stringify传递content
• Sitegeist.Monocle:DataUri.Text：具有媒体类型text/plain的端点模拟

Sitegeist.Monocle:MirrorUri

创建一个uri，该uri指向一个monocle端点，该端点返回带有给定类型传递的内容

    endpointUrl = Sitegeist.Monocle:MirrorUri {
        content = '{"hello":"world"}'
        type = 'application/json'
    }

注意：浏览器通常会截断url到最大长度，如果您模拟大的json结构，请注意这一点。

为方便起见，存在特殊的json和text原型

• Sitegeist.Monocle:MirrorUri.Json：具有媒体类型application/json的端点模拟，接受原始数组数据
• Sitegeist.Monocle:MirrorUri.Text：具有媒体类型text/plain的端点模拟

Sitegeist.Monocle:StaticUri

创建一个URI，该URI将返回给定键的文件内容和contentType。

    endpointUrl = Sitegeist.Monocle:StaticUri {
        key = 'example'
    }

每个键的路径和内容类型通过设置进行配置

Sitegeist:
  Monocle:
    uriMock:
      static:
        example:
          path: 'resource://Vendor.Package/Private/Json/example.json'
          contentType: 'application/json'

在风格指南中模拟URI

prototype(Vendor.Package:Component.SearchExample) < prototype(Neos.Fusion:Component) {
	@styleguide {
		props {
			endpointUrl = Sitegeist.Monocle:DataUri.Json {
				content = Neos.Fusion:RawArray {
					term = 'hamburch'
					suggestedTerm = 'hamburg'
				}
			}
		}
	}

	endpointUrl = null

	renderer = afx`
		<div data-endpoint-url={props.endpointUrl} />
	`
}

属性 & 属性编辑器

在预览Fusion原型时，Monocle UI提供了一种机制，可以以临时方式覆盖该原型的某些属性。这允许您快速检查您的原型是否在某些不可预见配置（例如较长的文本或较短的文本）中工作。

Monocle将尝试从多个来源重现您的原型的API，并将所有可合理与特定编辑器配置相关联的属性作为可编辑属性提供。默认情况下，Monocle将扫描您的融合代码中的@styleguide.props路径以查找属性值。如果您的原型恰好是Neos.Fusion:Component（在大多数情况下很可能如此），Monocle还会扫描您的Component属性的默认值。

给定一个属性值，Monocle将检查其类型并提供相应的编辑器配置。以下是所有标准情况的表格。

此外，如果您需要更多控制所使用的编辑器，可以在融合代码中的@styleguide.options.propEditors路径下包含自定义配置。

prototype(Vendor.Package:MyAlertComponent) < prototype(Neos.Fusion:Component) {
    @styleguide {
        options {
            propEditors {
                severity {
                    editor = 'Sitegeist.Monocle/Props/Editors/SelectBox'
                    editorOptions {
                        options {
                            info {
                                label = 'Info'
                                value = 'info'
                            }
                            success {
                                label = 'Success'
                                value = 'success'
                            }
                            warning {
                                label = 'Warning'
                                value = 'warning'
                            }
                            error {
                                label = 'Error'
                                value = 'error'
                            }
                        }
                    }
                }
            }
        }
    }
}

可用编辑器的概述可以在[PropEditors]找到。

如果您正在使用PackageFactory.AtomicFusion.PropTypes，则请查看Sitegeist.Monocle.PropTypes。此包会自动生成适合您的PropTypes的编辑器配置。

在检查器中隐藏属性

有时，完全移除属性的编辑器可能很有用（例如，对于包含HTML的属性）。可以使用hidePropsInInspector选项完成此操作。

prototype(Vendor.Package:SomeComponent) < prototype(Neos.Fusion:Component) {
    @styleguide {
        options {
            hidePropsInInspector = ${['header', 'content']}
        }
    }
}

Fusion对象树缓存

Monocle将为每个站点包缓存融合代码。为了使此缓存无效，将监视所有包的Fusion目录，并且更改将触发flushing of the fusion-cache。

设置Sitegeist.Monocle.fusion.enableObjectTreeCache默认启用Monocle中的缓存。

路由

monocle路由将通过设置自动包含。

策略

Monocle附带四个权限目标以控制访问。

• Sitegeist.Monocle:Backend.Styleguide：调用打开风格指南的后端模块
• Sitegeist.Monocle:Styleguide.Api：通过API请求有关原型等信息（由模块使用）
• Sitegeist.Monocle:Styleguide.Preview：显示原型的预览
• Sitegeist.Monocle:Styleguide.Module：显示风格指南

不同上下文中的策略

• 在Production上下文中，默认情况下将所有monocle权限授予组Neos.Neos:AbstractEditor。这样，只有后端用户可以看到风格指南。
• 在Development上下文中，将Sitegeist.Monocle:Styleguide权限授予组Neos.Flow:Everybody。这样，可以通过URLhttp://127.0.0.1:8081/monocle/preview/module访问Styleguide，而无需任何数据库。
• 为了集成到ci-process中，您将权限Sitegeist.Monocle:Styleguide.Preview和Sitegeist.Monocle:Styleguide.Api授予ci系统。

贡献

我们乐意接受贡献。请发送给我们pull requests。