包简介

README 文档

README

Antlers Components is a Statamic addon that makes creating isolated, reusable Antlers partials easy and integrating existing Blade and Livewire components a breeze using a familiar syntax.

Installation

You may install Antlers Components using composer:

composer require stillat/antlers-components

Requirements

Antlers Components requires at least PHP 8.1 and:

Statamic version 3.4.* or higher
Laravel 9.36 or higher

This package provides a familiar syntax for Livewire components, and it is compiled into the Antlers tags provided by this package:

https://github.com/marcorieser/statamic-livewire

In order to use the Livewire/Flux syntax, you will also need to install it using the following command:

composer require marcorieser/statamic-livewire

For support/reporting issues related to the Livewire functionality beyond compilation errors, please use the following GitHub link:

https://github.com/marcorieser/statamic-livewire/issues

Using Blade Components

You may use Blade Components within your Antlers template using the syntax you are familiar with.

For example, to include a card Blade component we may use the <x-card /> syntax. This package supports Blade component slots; you may use Antlers within the slot:

{{ collection:articles }}
    <x-card class="shadow-sm">
        <x-slot:heading class="font-bold">
            {{ title }}
        </x-slot>
    
        {{ content | safe_truncate(120) }}
    
        <x-slot:footer class="text-sm">
            ...
        </x-slot>
    </x-card>
{{ /collection:articles }}

Using Antlers inside parameter values is acceptable.

Livewire Components

We can integrate existing Livewire components in our Antlers templates using the <livewire /> syntax like so:

{{ collection:articles }}
    <livewire:counter :start="index" />
{{ /collection:articles }}

Flux Components

If you'd like to use Flux components, ensure you've also installed the Livewire addon.

Flux v1 Styles and Scripts

Once you have Livewire and Flux installed in your site, you can use the flux tag to add the required styles and scripts to your layout:

<!doctype html>
<html>
<head>

    {{ flux:styles /}}
</head>
<body>
    {{ template_content /}}

    {{ flux:scripts /}}
</body>
</html>

You may now use Flux components directly within your Antlers templates (or within your Livewire components if you are using Antlers for those).

Flux v2 Styles and Scripts

Once you have Livewire and Flux installed in your site, you can use the flux tag to add the required styles and scripts to your layout:

<!doctype html>
<html>
<head>

    {{ flux:appearance /}}
</head>
<body>
    {{ template_content /}}

    {{ flux:scripts /}}
</body>
</html>

You may now use Flux components directly within your Antlers templates (or within your Livewire components if you are using Antlers for those).

Supported Parameter Types

This package supports the following parameter types when compiling component tags to Antlers:

Shorthand Variables:

{{ title = 'The title'; }}

<x-alert :$title />

Variable References:

{{ title = 'The title'; }}

<x-alert :title="title" />

Name/Value:

{{ title = 'The title'; }}

<x-alert title="title" />

Attribute:

<x-editor readonly />

Antlers Components

This package also supports the concept of Antlers "components", which are really just syntax sugar on top of partials (with a few special behaviors).

As an example, we could include a partial named partial-name.antlers.html using this library like so:

<a-partial-name :$title />

Very Important: When using this syntax, the partials will not inherit the scope they were included in (except for the general Cascade). This means that if we want current data to be supplied to our partial, we must explicitly pass it in via. parameters.

The behavior of slots is also slightly different when using this syntax, and is closer to anonymous Blade components.

Let us consider an Antlers partial named _card.antlers.html:

<div {{ attributes.class(['border']) }}>
    <h1 {{ title.attributes.class(['border']) }}>
        {{ title }}
    </h1>
    
    {{ slot }}
    
    <footer {{ footer.attributes.class(['text-gray-700']) }}>
        {{ footer }}
    </footer>
</div>

we can render this Antlers partial in our main template like so:

{{ collection:articles }}
    <a-card :$title :$content>
        <a:slot:title>{{ title }}</a:slot:title>
        <a:slot:footer>...</a:slot:footer>

        {{ content | safe_truncate(120) }}
    </a-card>
{{ /collection:articles }}

Note: We have to explicitly allow the current article's title and content values by supplying them via. parameters. Without this, it will default to the current page's values.

When using this syntax, we do not need to prefix named slots with slot: inside our partial. Additionally, we also have access to an attributes bag. Parameters supplied to named slots will be available within the partial, as well:

{{ collection:articles }}
    <a-card :$title :$content>
        <a:slot:title class="custom title classes">{{ title }}</a:slot:title>
        <a:slot:footer>...</a:slot:footer>

        {{ content | safe_truncate(120) }}
    </a-card>
{{ /collection:articles }}

Nesting Antlers Component Partials

We may also nest partial components by including them within other components. Like with regular components, we must specify what values we want to be passed along to our nested components:

<div>
    <a-child-partial :$title />
</div>

We can check if we are inside a nested/child component using the __is_nested variable:

{{ if __is_nested }}
    I am a nested partial.
{{ else }}
    I am not nested.
{{ /if }}

We can also see how deeply nested we are using the __depth variable:

The current nested partial depth is: {{ __depth }}.

And finally, we may access data from the parent partial if we are nested by referencing the __parent variable:

{{ __parent.title }}

If that parent has a parent, we can keep on going:

{{ __parent.__parent.title }}

License

This addon is open-sourced software licensed under the MIT license.

stillat/antlers-components 适用场景与选型建议

stillat/antlers-components 是一款基于 PHP 开发的 Composer 扩展包，目前已累计 62.92k 次下载、GitHub Stars 达 27，最近一次更新时间为 2023 年 03 月 03 日，在 PHP 生态内属于活跃度较高的组件。

我们在过去多个企业项目中使用过 stillat/antlers-components 或与其功能相近的方案，如果你在选型或落地过程中遇到问题，例如 版本兼容、二次改造、私有化封装、与内部系统对接、生产 BUG 排查，欢迎联系我们协助评估。

围绕 stillat/antlers-components 我们能提供哪些服务？

定制开发 / 二次开发

基于 stillat/antlers-components 在你已有业务上做功能扩展、字段裁剪、UI 适配、与内部账号 / 权限 / 日志系统的深度对接。

BUG 修复 & 性能优化

线上偶发问题、内存泄漏、慢查询、并发异常等排查修复；针对高流量场景做缓存、队列、索引层面的调优。

项目外包 & 长期维护

承接完整的项目从需求 → 设计 → 开发 → 上线 → 长期运维；也可按月提供技术保姆服务。

yvsm@zunyunkeji.com QQ：316430983 微信：yvsm316 西安尊云信息科技 · 专注 PHP / Go / 分布式系统研发

stillat/antlers-components

包简介