Add ability to define custom modes/views.
Swap view handler to Statamic's View class, some cascade data will now be available.

Author: Michael Rook

README.md

@@ -25,14 +25,16 @@ php artisan vendor:publish --tag="config" --provider="HandmadeWeb\Frosty\Service
 #### 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();`
 
-#### Alpine Js Method
+This method uses the `native.blade.php` view, you are free to override it in `resources/vendor/frosty/`, you will have access to the `content`, `endpoint` and `mode` variables.
 
-If you are using Alpine Js in your application then you may update your Frosty configuration to use Alpine.
+#### Alpine.Js Method
+
+If you are using Alpine.Js in your application then you may update your Frosty configuration to use Alpine.
 ```php
 /*
-* Javascript Mode
+* Mode
 *
-* Which Javascript mode to use?
+* 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.
@@ -44,6 +46,35 @@ If you are using Alpine Js in your application then you may update your Frosty c
 'mode' => 'alpine',
 ```
 
+This method uses the `alpine.blade.php` view, you are free to override it in `resources/vendor/frosty/`, you will have access to the `content`, `endpoint` and `mode` variables.
+
+#### Custom Method
+
+You are free to use a custom method, you may do so by defining a new view template for Frosty to use under `resources/vendor/frosty`, the filenames `alpine`, `native` and `not-found` are considered to be reserved, although you may override them if you wish.
+
+Once you have created a new view for your mode, you will have access to the `content`, `endpoint` and `mode` variables, you may then use this to provide the content or endpoint to your custom method.
+
+Then it is just a matter of updating the mode to use the name of your new method/view.
+
+Lets say we created a file called `myCustomVueMode.blade.php` which might contain something like,
+```blade
+<vue-fetcher endpoint="{{ $endpoint }}" initial-content="{!! $content !!}" />
+```
+
+You would then update your mode to:
+```php
+'mode' => 'myCustomVueMode',
+```
+
+In the event that your custom method/mode doesn't have a corresponding view file, then Frosty will insert some HTML comments in the location of where it would have rendered your method.
+
+```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 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)
@@ -81,6 +112,15 @@ This works with both the route and url options.
 {{ /frosty:fetch }}
 ```
 
+### Using a different mode/view.
+You are free to use any other mode/view that might be available for Frosty to use, separately to whatever you might have set as the config default.
+You can do this by passing the mode parameter, which will relate to the name of a view file located in `resources/vendor/frosty/`
+```antlers
+{{ frosty:fetch route="ajax.news" mode="myCustomVueMode" }}
+    <p>Finding something juicy!</p>
+{{ /frosty:fetch }}
+```
+
 ## 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.
@@ -105,6 +145,13 @@ You can also use named arguments in PHP 8+ to specify particular parameters.
 @frosty(route('ajax.sponsors', 'featured'))
 ```
 
+### Using a different mode/view.
+You are free to use any other mode/view that might be available for Frosty to use, separately to whatever you might have set as the config default.
+You can do this by passing the mode parameter, which will relate to the name of a view file located in `resources/vendor/frosty/`
+```blade
+@frosty(route('ajax.sponsors', 'featured'), 'myCustomVueMode')
+```
+
 ## Class Usage
 New up the class.
 ```php
@@ -119,6 +166,13 @@ You can also use named arguments in PHP 8+ to specify particular parameters.
 $frosty = Frosty::make(endpoint: '/ajax/random-quote');
 ```
 
+You are free to use any other mode/view that might be available for Frosty to use, separately to whatever you might have set as the config default.
+You can do this by passing the mode (or second) parameter, which will relate to the name of a view file located in `resources/vendor/frosty/`
+```php
+$frosty = Frosty::make('/ajax/random-quote', 'myCustomVueMode');
+// You are free to use the named argument style of mode: 'myCustomVueMode'
+```
+
 Aditional methods can be chained to add content and context, or to set the endpoint.
 ```php
 $frosty = Frosty::make();

config/frosty.php

@@ -2,16 +2,19 @@
 
 return [
     /*
-    * Javascript Mode
+    * Mode
     *
-    * Which Javascript mode to use?
+    * 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.
+    *
+    * You are also free to define your own modes or override existing ones by creating a corresponding view file at `resources/vendor/frosty/`
+    * And updating the mode below to match the name of the view.
     */
     'mode' => 'native',
 ];

resources/views/not-found.blade.php

@@ -0,0 +1,5 @@
+<!-- Frosty could not be rendered, Mode not found -->
+@if(optional(Auth::user())->isSuper())
+<!-- Mode: {{ $mode }} -->
+<!-- Endpoint: {{ $endpoint }} -->
+@endif

src/Frosty.php

@@ -5,6 +5,7 @@
 use Illuminate\Support\Collection;
 use Statamic\Facades\Antlers;
 use Statamic\Tags\Context;
+use Statamic\View\View;
 
 class Frosty
 {
@@ -13,22 +14,16 @@ class Frosty
     protected $endpoint;
     protected $mode;
 
-    public static function make(string $endpoint = null): static
+    public static function make(string $endpoint = null, ?string $mode = null): static
     {
-        return new static($endpoint);
+        $mode = $mode ? $mode : static::mode();
+
+        return new static($endpoint, static::mode($mode));
     }
 
-    public static function mode(): string
+    public static function mode(?string $mode = null): string
     {
-        $defaultMode = 'native';
-
-        if ($mode = config('frosty.mode')) {
-            if (! in_array($mode, ['native', 'alpine'])) {
-                $mode = $defaultMode;
-            }
-        }
-
-        return $mode ?? $defaultMode;
+        return $mode ? $mode : config('frosty.mode', 'native');
     }
 
     public static function scripts(): string
@@ -43,10 +38,10 @@ public static function scripts(): string
         return '';
     }
 
-    public function __construct(string $endpoint = null)
+    public function __construct(string $endpoint = null, ?string $mode = null)
     {
         $this->endpoint = $endpoint;
-        $this->mode = static::mode();
+        $this->mode = static::mode($mode);
     }
 
     public function content(): string
@@ -75,9 +70,10 @@ public function endpoint(): ?string
     public function render(): string
     {
         if ($this->endpoint()) {
-            return view("frosty::{$this->mode}", [
+            return View::first(["frosty::{$this->mode}", 'frosty::not-found'], [
                 'content' => $this->content(),
                 'endpoint' => $this->endpoint(),
+                'mode' => $this->mode,
             ])->render();
         }
 

src/Tags/FrostyTag.php

@@ -30,7 +30,7 @@ public function index()
      */
     public function fetch()
     {
-        $frosty = Frosty::make()
+        $frosty = Frosty::make(mode: Arr::get($this->params, 'mode'))
             ->withContent($this->content)
             ->withContext($this->context);