diff --git a/README.md b/README.md index c52a2a8..ce39a16 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ [![MIT Licensed](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](LICENSE.md) -Frosty provides easy access to fetch Ajax content via Alpine.Js in Statamic. +Frosty provides easy access to fetch Ajax content in Statamic. ## Requirements @@ -14,43 +14,36 @@ You can install the package via composer: ```shell composer require handmadeweb/frosty ``` -Then be sure to load Alpine.js on any pages that you wish to use Frosty on. -## PHP Usage -Using Frosty in `PHP` is done by using the `class` (see class instructions) +### Copy the package config to your local config with the publish command: -## Blade Usage -Using Frosty in `Blade` can be done by using the `frosty` blade directive or by using the `class` (see class instructions) - -```blade -@frosty(string $content = null, array | Collection $context = [], string $endpoint = null, bool $antlers = false) +```shell +php artisan vendor:publish --tag="config" --provider="HandmadeWeb\Frosty\ServiceProvider" ``` -You can also use named arguments in PHP 8+ to specify particular parameters. -```blade -@frosty(content: 'Loading', endpoint: '/ajax/sponsors') -``` +### Prepare for Usage +#### Native Method +If you aren't using Alpine Js in your application then you'll need to load [handmadeweb/datafetcher.js](https://github.com/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();` -### Pulling in content from a url. +#### Alpine Js Method -```blade -@frosty(endpoint: '/ajax/sponsors') -``` - -### Pulling in content from a route. -```blade -@frosty(endpoint: route('ajax.sponsors', 'featured')) +If you are using Alpine Js in your application then you may update your Frosty configuration to use Alpine. +```php +/* +* Javascript Mode +* +* Which Javascript 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', ``` -### Using initial content then pulling new content. -```blade -@frosty(content: '

Finding something juicy!

', endpoint: route('ajax.news')) -``` - -### Using antlers in content. -```blade -@frosty(content: '

Finding something @{{ zingword | ucfirst }}

', context: ['zingword' => 'amazing'], endpoint: route('ajax.news')) -``` ## Antlers Usage Using Frosty in `Antlers` can be done by using the `frosty` tag or if you are using an `.antlers.php` template file by using the `class` (see class instructions) @@ -84,61 +77,70 @@ This works with both the route and url options. {{ /frosty:fetch }} ``` -## Class Usage -The `\HandmadeWeb\Frosty\Frosty` class provides a way to easily generate code like the below. +## Blade Usage +Using Frosty in `Blade` can be done by using the `frosty` blade directive or by using the `class` (see class instructions) +The blade directive currently doesn't accept providing content or context, If you need to use that functionality the you'll need to use the class chaining method. + +```blade +@frosty(string $endpoint = null) +``` + +You can also use named arguments in PHP 8+ to specify particular parameters. +```blade +@frosty(endpoint: '/ajax/sponsors') +``` + +### Pulling in content from a url. + +```blade +@frosty('/ajax/sponsors') +``` +### Pulling in content from a route. ```blade -
Initial content example
+@frosty(route('ajax.sponsors', 'featured')) ``` -You can do this by newing up the class. +## Class Usage +New up the class. ```php -new Frosty(string $content = null, array | Collection $context = [], string $endpoint = null, bool $antlers = false) +new Frosty(string $endpoint = null) ``` -Or by using the make method. +Or use the make method. ```php -Frosty::make(string $content = null, array | Collection $context = [], string $endpoint = null, bool $antlers = false) +Frosty::make(string $endpoint = null) ``` You can also use named arguments in PHP 8+ to specify particular parameters. ```php $frosty = Frosty::make(endpoint: '/ajax/random-quote'); ``` -All parameters are optional on init and can be individually defined later on. +Aditional methods can be chained to add content and context, or to set the endpoint. ```php $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 -$frosty->withAntlers(false); // bool ``` When using the tag, you'll specify if the endpoint is a url or a route, however when using the class directly, the endpoint is assumed to be a url string, if you wish to pass a route to it instead, then you are welcome to do that. Unlike when using the Frosty tag, the Frosty class can directly accept parameters on the route below. ```php +Frosty::make(route('ajax.cart', $user->id()) +// or Frosty::make()->withEndpoint(route('ajax.cart', $user->id()) ``` When you are ready to output the content, then you may call the render method. ```php Frosty::make() - ->withContent($content) - ->withContext($context) - ->withEndpoint($endpoint) - ->withAntlers(false) + ->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(); ``` -## View -Should you wish to override the vendor/handmadeweb/frosty/resources/views/fetcher.blade.php view, you are welcome to do that, by placing `fetcher.blade.php`, `fetcher.antlers.php` or `fetcher.antlers.html` in the resources/vendor/frosty directory from the root of your project. -The class will be passed down to the view and will be called `frosty`. -You may then use the `$frosty->content()` and `$frosty->endpoint()` methods in your view override. - ## Changelog Please see [CHANGELOG](https://statamic.com/addons/handmadeweb/frosty/release-notes) for more information what has changed recently. diff --git a/composer.json b/composer.json index 757db85..04ed972 100644 --- a/composer.json +++ b/composer.json @@ -20,7 +20,7 @@ "extra": { "statamic": { "name": "Frosty", - "description": "Frosty addon" + "description": "Frosty provides easy access to fetch Ajax content in Statamic." }, "laravel": { "providers": [ diff --git a/config/frosty.php b/config/frosty.php index b063003..4ecb26e 100644 --- a/config/frosty.php +++ b/config/frosty.php @@ -1,16 +1,17 @@ 'native', ]; diff --git a/src/Frosty.php b/src/Frosty.php index a7fb1e5..19aa991 100644 --- a/src/Frosty.php +++ b/src/Frosty.php @@ -20,12 +20,15 @@ public static function make(string $endpoint = null): static public static function mode(): string { - $mode = config('frosty.mode', 'native'); - if (! is_string($mode) || ! in_array($mode, ['native', 'alpine'])) { - $mode = 'native'; + $defaultMode = 'native'; + + if ($mode = config('frosty.mode')) { + if (! in_array($mode, ['native', 'alpine'])) { + $mode = $defaultMode; + } } - return $mode; + return $mode ?? $defaultMode; } public static function scripts(): string diff --git a/src/ServiceProvider.php b/src/ServiceProvider.php index 28af32f..6d9b460 100644 --- a/src/ServiceProvider.php +++ b/src/ServiceProvider.php @@ -16,6 +16,12 @@ public function boot() { parent::boot(); + if ($this->app->runningInConsole()) { + $this->publishes([ + __DIR__.'/../config/frosty.php' => config_path('frosty.php'), + ], 'config'); + } + $this->bootDirectives(); }