README

Neos 插件，用于提供第三方使用的数据/渲染内容片段（也称为 'renderlets'）

安装

通过 composer 安装

composer require wwwision/renderlets-provider

用法

Renderlets 可以在 Fusion 路径下定义 /renderlets

renderlets {
    some_renderlet = Wwwision.Renderlets.Provider:Renderlet {
        renderer = afx`<p>This can be any component</p>`
    }
}

设置完成后，renderlet 将通过 HTTP 在端点 /__renderlet/some_renderlet 上公开

参数

Renderlets 可以定义参数，消费者可以通过查询参数指定这些参数

renderlet_with_parameters = Wwwision.Renderlets.Provider:Renderlet {
    parameters {
        foo = true
        bar = false
    }
    renderer = afx`foo: {parameters.foo}, bar: {parameters.bar || 'default'}`
}

在此示例中，"foo" 参数是必需的（true），而 "bar" 是可选的。如果请求 renderlet 端点而没有任何查询参数（/__renderlet/renderlet_with_parameters），则返回包含体的 400 HTTP 响应

Missing/empty parameter "foo"

如果指定了参数（例如，/__renderlet/renderlet_with_parameters?foo=foo%20value&bar=bar%20value），则它们将按预期评估

foo: foo value, bar: bar value

注意

不匹配配置参数的查询参数（例如，/__renderlet/renderlet_with_parameters?fo=typo）也会导致 400 状态码，以防止因输入错误而导致的不正确行为

缓存

每个 renderlet 都分配了一个 cacheId，该 ID 将在响应中转换为 ETag HTTP 标头。这允许消费者发送相应的 If-None-Match 标头，以防止未更改的 renderlets 再次传输。

cacheId 默认是一个随机字符串，在渲染时分配。为了保持一致性，在 renderlet 声明中定义了一个相应的 @cache 元属性（请参阅 https://docs.neos.io/guide/manual/rendering/caching）。如果 renderlet 内容依赖于其他组件或数据，则应相应扩展此属性

示例

some_renderlet = Wwwision.Renderlets.Provider:Renderlet {
    @context {
        someNode = ${q(site).children('[instanceof Some.Package:SomeNodeType]').get(0)}
    }
    renderer = afx`Node label: {someNode.label}`
    @cache {
        entryTags {
            someNode = ${Neos.Caching.nodeTag(someNode)}
        }
    }
}

或者，可以将 cacheId 设置为静态（或动态）值以使其确定

some_renderlet = Wwwision.Renderlets.Provider:Renderlet {
    cacheId = 'some-static-value'
    renderer = afx`Static content`
}

对于 Renderlet Props，可以通过 renderer.@cache 配置缓存行为

注意

参数始终是缓存条目标识符的一部分，因此每个参数组合都将单独缓存

HTTP 标头

Content-Type

默认情况下，renderlets 使用 "text/html" 的 Content-Type 标头进行渲染。这可以通过 httpHeaders 属性进行更改

some_renderlet = Wwwision.Renderlets.Provider:Renderlet {
    httpHeaders {
        'Content-Type' = 'text/plain'
    }
    renderer = 'This is some plain text'
}

CORS

默认情况下，renderlets 使用 Access-Control-Allow-Origin 的 Access-Control-Allow-Origin 标头为 "*"，以允许它们在没有 CORS 限制的情况下被使用。这可以通过 httpHeaders 属性进行更改

some_renderlet = Wwwision.Renderlets.Provider:Renderlet {
    httpHeaders {
        'Access-Control-Allow-Origin' = 'some-domain.tld'
    }
    // ...
}

其他标头

可以通过 httpHeaders 属性添加其他 HTTP 标头

some_renderlet = Wwwision.Renderlets.Provider:Renderlet {
    httpHeaders {
        'Content-Language' = 'de-DE, en-CA'
        'X-Custom-Header' = 'some value'
    }
    // ...
}

本地化

Renderlet 端点独立于 Neos 路由工作。因此，内容存储库中的节点将在其默认维度中加载。但参数是一个很好的选项，允许消费者更改语言

localized_renderlet = Wwwision.Renderlets.Provider:Renderlet {
    parameters {
        lang = true
    }
    @context {
        someNode = ${q(site).children('[instanceof Some.Package:SomeNodeType]').get(0)}
        someNode.@process.translate = ${q(value).context({dimensions: {language: [parameters.lang]}, targetDimensions: {language: parameters.lang}}).get(0)}
    }
    renderer = afx`{q(someNode).property('title')}`
}

在这种情况下，必须指定一个 lang 查询参数，该参数用于在相应上下文中加载节点。

或者，可以将参数设置为可选的

localized_renderlet = Wwwision.Renderlets.Provider:Renderlet {
    parameters {
        lang = false
    }
    @context {
        someNode = ${q(site).children('[instanceof Some.Package:SomeNodeType]').get(0)}
        someNode.@process.translate = ${q(value).context({dimensions: {language: [parameters.lang]}, targetDimensions: {language: parameters.lang}}).get(0)}
        someNode.@process.translate.@if.hasLanguageParameter = ${!String.isBlank(parameters.lang)}
    }
    renderer = afx`{q(someNode).property('title')}`
}

Renderlet Props

可以使用 RenderletProps 原型渲染数据结构，而不是（HTML）内容

some_renderlet_props = Wwwision.Renderlets.Provider:RenderletProps {
    properties {
        foo = 'bar'
        baz {
           foos = true 
        }
    }
}

这将渲染端点 /__renderlet/some_renderlet_props 上的以下 JSON

{
	"foo": "bar",
	"baz": {
		"foos": true
	}
}

RenderletProps 的 Content-Type 标头默认为 application/json，但可以按照上述说明进行更改。

缓存段

当在渲染带有自身 @cache 配置的 Fusion 原型时，这可能导致响应中出现内容缓存标记（详见问题）。因此，从版本 1.3.0 开始，这些标记现在已被从渲染器中移除。

注意，为了使自动缓存刷新正常工作，@cache 配置必须完整。

some_renderlet_props = Wwwision.Renderlets.Provider:RenderletProps {
    @context {
        someNode = ${q(site).find('#517ad799-35df-4324-9429-5c75629a8b34').get(0)}
    }
    properties {
        someRenderedComponent = Some.Package:Foo {
            someNode = ${someNode}
        }
    }
    renderer.@cache {
        entryTags {
            someNode = ${Neos.Caching.nodeTag(someNode)}
        }
    }
}

贡献

以问题或拉取请求形式提供的贡献非常受欢迎。

许可证

请参阅 LICENSE

wwwision / renderlets-provider

维护者

详情