README

Frosty 提供了在 Statamic 中获取 Ajax 内容的简单方法。

要求

• PHP 8.0 或更高版本
• Statamic 3.1 或更高版本

安装

您可以通过 composer 安装此包

composer require handmadeweb/frosty

使用 publish 命令将包配置复制到您的本地配置

php artisan vendor:publish --tag="config" --provider="HandmadeWeb\Frosty\ServiceProvider"

准备使用

原生方法

如果您在应用程序中没有使用 Alpine Js，则需要将 handmadeweb/datafetcher.js 加载到您的页脚中，您可以选择手动操作，或者通过提供的 Alpine：{{ frosty:scripts }}、Blade：@frostyScripts 或 PHP：\HandmadeWeb\Frosty\Frosty::scripts(); 辅助器来完成。

此方法使用 native.blade.php 视图，您可以在 resources/vendor/frosty/ 中自由覆盖它，您将能够访问 content、endpoint 和 mode 变量。

Alpine.Js 方法

如果您在应用程序中使用 Alpine.Js，则可以更新 Frosty 配置以使用 Alpine。

/*
* Mode
*
* Which mode to use?
*
* native: uses https://github.com/handmadeweb/datafetcher.js
* - If you aren't using Alpine Js in your application then you'll need to load handmadeweb/datafetcher.js in your footer.
* - You can either do this manually, or via the provided helpers for Alpine: `{{ frosty:scripts }}`
* - Blade: `@frostyScripts` or PHP: `\HandmadeWeb\Frosty\Frosty::scripts();`
*
* alpine: uses Alpine.Js, be sure to load it.
*/
'mode' => 'alpine',

此方法使用 alpine.blade.php 视图，您可以在 resources/vendor/frosty/ 中自由覆盖它，您将能够访问 content、endpoint 和 mode 变量。

自定义方法

您可以使用自定义方法，您可以通过在 resources/vendor/frosty 下为 Frosty 定义新的视图模板来实现，文件名 alpine、native 和 not-found 被视为保留，尽管您可以选择覆盖它们。

一旦您为您的方法创建了一个新的视图，您将能够访问 content、endpoint 和 mode 变量，您可以使用这些变量为您的自定义方法提供内容或端点。

然后只需将模式更新为使用您的新方法/视图的名称即可。

假设我们创建了一个名为 myCustomVueMode.blade.php 的文件，它可能包含以下内容：

<vue-fetcher endpoint="{{ $endpoint }}" initial-content="{!! $content !!}" />

然后您需要将模式更新为：

'mode' => 'myCustomVueMode',

如果您的自定义方法/模式没有相应的视图文件，则 Frosty 将在渲染方法的位置插入一些 HTML 注释。

<!-- Frosty could not be rendered, Mode not found -->

<!-- If the page is being viewed by a Super Administrator, then the below will also be inserted as a comment. -->
<!-- Mode: {{ $mode }} -->
<!-- Endpoint: {{ $endpoint }} -->

Antlers 使用

在 Antlers 中使用 Frosty 可以通过使用 frosty 标签完成，如果您使用的是 .antlers.php 模板文件，则可以通过使用 class（请参阅类说明）完成。

您可以使用标签作为 frosty:fetch 或只是 frosty，尽管我更喜欢 frosty:fetch，因为它描述了它在做什么。

从 URL 中获取内容。

URL 可以是任何地方。

{{ frosty:fetch url="/ajax/signup-form" }}

或者

{{ frosty:fetch endpoint="/ajax/signup-form" }}

从路由中获取内容。

路由必须是 GET 路由，并且目前不能接受参数。

{{ frosty:fetch route="ajax.signup-form" }}

请注意，上述三个示例不能组合成一个标签调用。

{{ frosty:fetch endpoint="/ajax/signup-form" url="/ajax/signup-form" route="ajax.signup-form" }}
{{ frosty:fetch route="ajax.signup-form" endpoint="/ajax/signup-form" url="/ajax/signup-form" }}

将使用第一个找到的参数，参数按以下顺序进行检查：端点、URL、路由。

使用初始内容然后获取新内容。

此方法适用于路由和 URL 选项。

{{ frosty:fetch route="ajax.news" }}
    <p>Finding something juicy!</p>
{{ /frosty:fetch }}

使用不同的模式/视图。

您可以使用任何其他模式/视图，这些模式/视图可能对 Frosty 可用，而无需设置配置默认值。您可以通过传递模式参数来实现，该参数将与位于 resources/vendor/frosty/ 的视图文件名相关联。

{{ frosty:fetch route="ajax.news" mode="myCustomVueMode" }}
    <p>Finding something juicy!</p>
{{ /frosty:fetch }}

Blade 使用

在Blade中使用Frosty可以通过使用frosty Blade指令或通过使用class（参见类说明）来实现。目前，Blade指令不支持提供内容或上下文，如果您需要使用该功能，则需要使用类链式方法。

@frosty(string $endpoint = null)

您还可以在PHP 8+中使用命名参数来指定特定参数。

@frosty(endpoint: '/ajax/sponsors')

从 URL 中获取内容。

@frosty('/ajax/sponsors')

从路由中获取内容。

@frosty(route('ajax.sponsors', 'featured'))

使用不同的模式/视图。

您可以使用任何其他模式/视图，这些模式/视图可能对 Frosty 可用，而无需设置配置默认值。您可以通过传递模式参数来实现，该参数将与位于 resources/vendor/frosty/ 的视图文件名相关联。

@frosty(route('ajax.sponsors', 'featured'), 'myCustomVueMode')

类使用

初始化类。

new Frosty(string $endpoint = null)

或使用make方法。

Frosty::make(string $endpoint = null)

您还可以在PHP 8+中使用命名参数来指定特定参数。

$frosty = Frosty::make(endpoint: '/ajax/random-quote');

您可以使用Frosty支持的其他任何模式/视图，与您设置的默认配置无关。您可以通过传递模式（或第二个）参数来实现这一点，该参数将与位于resources/vendor/frosty/中的视图文件名称相关。

$frosty = Frosty::make('/ajax/random-quote', 'myCustomVueMode');
// You are free to use the named argument style of mode: 'myCustomVueMode'

可以链式调用其他方法来添加内容、上下文或设置端点。

$frosty = Frosty::make();
$frosty->withContent($content); // string
$frosty->withContext($context); // \Statamic\Tags\Context or \Illuminate\Support\Collection (Used to provide Cascaded variables to the content)
$frosty->withEndpoint($endpoint); // string

当使用标签时，您将指定端点是URL还是路由，然而当直接使用类时，端点被假定为URL字符串，如果您想传递一个路由给它，那么您也可以这样做。

与使用Frosty标签不同，Frosty类可以直接接受路由下的参数。

Frosty::make(route('ajax.cart', $user->id())
// or
Frosty::make()->withEndpoint(route('ajax.cart', $user->id())

当您准备好输出内容时，可以调用render方法。

Frosty::make()
    ->withContent($content) // Optional
    ->withContext($context) // Optional
    ->withEndpoint($endpoint) // Optional (could be set on class or make), If no endpoint has been set, then we won't bother trying to render.
    ->render();

变更日志

请参阅CHANGELOG以获取更多关于最近更改的信息。

贡献

请参阅CONTRIBUTING以获取详细信息。

鸣谢

• Handmade Web & Design
• Michael Rook
• 所有贡献者

许可

MIT许可（MIT）。请参阅许可文件以获取更多信息。