Merge pull request #103 from hydephp/improve-assetservice

Improve AssetService and style/script handling

Author: caendesilva

CHANGELOG.md

@@ -14,21 +14,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### About
 
-Keep an Unreleased section at the top to track upcoming changes.
+> Keep an Unreleased section at the top to track upcoming changes.
+> 
+> This serves two purposes:
+> 
+> 1. People can see what changes they might expect in upcoming releases
+> 2. At release time, you can move the Unreleased section changes into a new > release version section.
 
-This serves two purposes:
 
-1. People can see what changes they might expect in upcoming releases
-2. At release time, you can move the Unreleased section changes into a new release version section.
+This release refactors and improves the Asset Service, adding auto-configuration features and a new Asset facade.
+
+#### Using the Asset facade in Blade views
+
+Instead of the long syntax `Hyde::assetManager()` you can now use the `Asset` facade directly. See this example, which both do the exact same thing using the same underlying service:
+
+```blade
+Hyde::assetManager()->hasMediaFile('app.css')
+Asset::hasMediaFile('app.css')
+```
+
+If you don't know what any of this means, good news! You don't have to worry about it. Hyde's got your back.
 
 ### Added
-- for new features.
+- Added feature to dynamically load hyde.css and hyde.js if they exist locally
+- Added the Asset facade to be used instead of `Hyde::assetManager()`
+- Added the Asset facade as a class alias to `config/app.css`
 
 ### Changed
-- for changes in existing functionality.
+- Changed `scripts.blade.php` and `styles.blade.php` to use the Asset facade
 
 ### Deprecated
-- for soon-to-be removed features.
+- Deprecated AssetManager.php (`Hyde::assetManager()`). Use the Asset facade instead
 
 ### Removed
 - for now removed features.

config/app.php

@@ -81,8 +81,20 @@
         Hyde\Framework\HydeServiceProvider::class,
     ],
 
+    /*
+    |--------------------------------------------------------------------------
+    | Class Aliases
+    |--------------------------------------------------------------------------
+    |
+    | This array of class aliases will be registered when this application
+    | is started. However, feel free to register as many as you wish as
+    | the aliases are "lazy" loaded so they don't hinder performance.
+    |
+    */
+
     'aliases' => [
         'Hyde' => Hyde\Framework\Hyde::class,
+        'Asset' => Hyde\Framework\Facades\Asset::class,
     ],
 
 ];

docs/managing-assets.md

@@ -14,7 +14,7 @@ But as always with Hyde, you can customize everything if you want to.
 
 Hyde ships with a complete frontend where base styles and scripts are included through [HydeFront](https://github.com/hydephp/hydefront) which adds accessibility and mobile support as well as interactions for dark mode switching and navigation and sidebar interactions.
 
-HydeFront is split into two files, `hyde.css` and `hyde.js`. These are loaded in the default Blade views using the [jsDelivr CDN](https://www.jsdelivr.com/package/npm/hydefront). This is the recommended way to load the base styles as the [Hyde Framework](https://github.com/hydephp/framework) automatically makes sure that the correct HydeFront version for the current version of Hyde is loaded. If you don't want to use HydeFribtm you can customize the `styles.blade.php` file.
+HydeFront is split into two files, `hyde.css` and `hyde.js`. These are loaded in the default Blade views using the [jsDelivr CDN](https://www.jsdelivr.com/package/npm/hydefront). This is the recommended way to load the base styles as the [Hyde Framework](https://github.com/hydephp/framework) automatically makes sure that the correct HydeFront version for the current version of Hyde is loaded. If you don't want to use HydeFront you can of course customize this. See the [Telling Hyde where to find assets](#telling-hyde-where-to-find-assets) section for more information.
 
 The bulk of the frontend is built with [TailwindCSS](https://tailwindcss.com/). To get you started, when installing Hyde, all the Tailwind styles you need come precompiled and minified into `_media/app.css`.
 
@@ -80,6 +80,41 @@ npx tailwindcss -i resources/assets/app.css -o _media/app.css
 php hyde build OR php hyde rebuild _media
 ```
 
+## Telling Hyde where to find assets
+
+### Customizing the Blade templates
+
+To make it really easy to customize asset loading, the styles and scripts are loaded in dedicated Blade components.
+
+- Styles are loaded in `hyde::layouts.styles`
+- Scripts are loaded in `hyde::layouts.scripts`
+
+To customize them, run the following command:
+
+```bash
+php hyde publish:views layouts
+```
+
+Then edit the files found in `resources/views/vendor/hyde/layouts` of your project.
+
+### You might not even need to do anything!
+
+For the absolute majority of the cases, you don't need to mess with these files. The idea behind using a CDN is that your styles will be automatically updated when needed.
+
+Furthermore, Hyde does some automatic configuration which is roughly as follows:
+
+- If there is no `_media/app.css` file, Hyde won't attempt to load it.
+- If there is no `_media/app.js` file, Hyde won't attempt to load it.
+
+- If there is no `_media/hyde.css` file, the correct version will be loaded through the CDN.
+- If there is no `_media/hyde.js` file, the correct version will be loaded through the CDN.
+
+- If there is a `_media/hyde.css` file, it will be loaded instead of the CDN.
+- If there is a `_media/hyde.js` file, it will be loaded instead of the CDN.
+{.list-compact}
+
+Note that this automatic configuration behaviour was implemented in v0.41.x. Prior to that, only the first two bullets were implemented and you would need to change the layouts to load local HydeFront files manually.
+
 
 ## Managing images
 As mentioned above, assets stored in the _media folder are automatically copied to the _site/media folder,
@@ -90,8 +125,7 @@ making it the recommended place to store images. You can then easily reference t
 The recommended way to reference images are with relative paths as this offers the most compatibility,
 allowing you to browse the site both locally on your filesystem and on the web when serving from a subdirectory.
 
-> Note: The path is relative to the **compiled** file
-{.warning}
+>warning Note: The path is relative to the <b>compiled</b> file in the site output
 
 The path to use depends on the location of the page. Note the subtle difference in the path prefix.
 

packages/framework/resources/views/layouts/scripts.blade.php

@@ -1,10 +1,12 @@
 {{-- The core HydeFront scripts --}}
-@if(Hyde::scripts())
-<script defer src="{{ Hyde::scripts() }}"></script>
-@endif
+@unless(Asset::hasMediaFile('hyde.js'))
+<script defer src="{{ Asset::cdnLink('hyde.js') }}"></script>
+@else
+<script defer src="{{ Hyde::relativeLink('media/hyde.js', $currentPage) }}"></script>
+@endunless
 
 {{-- The compiled Laravel Mix scripts --}}
-@if(Hyde::assetManager()->hasMediaFile('app.js'))
+@if(Asset::hasMediaFile('app.js'))
 <script defer src="{{ Hyde::relativeLink('media/app.js', $currentPage) }}"></script>
 @endif
 

packages/framework/resources/views/layouts/styles.blade.php

@@ -1,10 +1,12 @@
 {{-- The core HydeFront stylesheet --}}
-@if(Hyde::styles())
-<link rel="stylesheet" href="{{ Hyde::styles() }}">
-@endif
+@unless(Asset::hasMediaFile('hyde.css'))
+<link rel="stylesheet" href="{{ Asset::cdnLink('hyde.css') }}">
+@else
+<link rel="stylesheet" href="{{ Hyde::relativeLink('media/hyde.css', $currentPage) }}">
+@endunless
 
 {{-- The compiled Tailwind/App styles --}}
-@if(Hyde::assetManager()->hasMediaFile('app.css'))
+@if(Asset::hasMediaFile('app.css'))
 <link rel="stylesheet" href="{{ Hyde::relativeLink('media/app.css', $currentPage) }}">
 @endif
 

packages/framework/src/Concerns/Internal/AssetManager.php

@@ -7,13 +7,16 @@
 /**
  * Offloads asset related methods for the Hyde Facade.
  *
+ * @deprecated version 0.41.x - Use the Asset facade instead.
  * @see \Hyde\Framework\Hyde
  */
 trait AssetManager
 {
     /**
      * Get the asset service instance.
      *
+     * @deprecated version 0.41.x - Use the Asset facade instead.
+     *
      * @return \Hyde\Framework\Contracts\AssetServiceContract
      */
     public static function assetManager(): AssetServiceContract
@@ -23,6 +26,8 @@ public static function assetManager(): AssetServiceContract
 
     /**
      * Return the Hyde stylesheet.
+     *
+     * @deprecated version 0.41.x - Use the Asset facade instead.
      */
     public static function styles(): string
     {
@@ -31,6 +36,8 @@ public static function styles(): string
 
     /**
      * Return the Hyde scripts.
+     *
+     * @deprecated version 0.41.x - Use the Asset facade instead.
      */
     public static function scripts(): string
     {

packages/framework/src/Facades/Asset.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace Hyde\Framework\Facades;
+
+use Hyde\Framework\Contracts\AssetServiceContract;
+use Illuminate\Support\Facades\Facade;
+
+/**
+ * @see \Hyde\Framework\Services\AssetService
+ *
+ * @method static string version()
+ * @method static string stylePath()
+ * @method static string scriptPath()
+ * @method static string constructCdnPath(string $file)
+ * @method static string cdnLink(string $file)
+ * @method static bool hasMediaFile(string $file)
+ */
+class Asset extends Facade
+{
+    protected static function getFacadeAccessor(): string
+    {
+        return AssetServiceContract::class;
+    }
+}

packages/framework/src/Services/AssetService.php

@@ -5,6 +5,9 @@
 use Hyde\Framework\Contracts\AssetServiceContract;
 use Hyde\Framework\Hyde;
 
+/**
+ * @see \Hyde\Framework\Facades\Asset
+ */
 class AssetService implements AssetServiceContract
 {
     /**
@@ -34,6 +37,16 @@ public function constructCdnPath(string $file): string
         return 'https://cdn.jsdelivr.net/npm/hydefront@'.$this->version().'/dist/'.$file;
     }
 
+    /**
+     * Alias for constructCdnPath.
+     *
+     * @since v0.41.x
+     */
+    public function cdnLink(string $file): string
+    {
+        return $this->constructCdnPath($file);
+    }
+
     public function hasMediaFile(string $file): bool
     {
         return file_exists(Hyde::path('_media').'/'.$file);

packages/framework/tests/Unit/AssetFacadeTest.php

@@ -0,0 +1,28 @@
+<?php
+
+use Hyde\Framework\Contracts\AssetServiceContract;
+use Hyde\Framework\Facades\Asset;
+use Hyde\Framework\Services\AssetService;
+use Hyde\Testing\TestCase;
+
+/**
+ * @covers \Hyde\Framework\Facades\Asset
+ */
+class AssetFacadeTest extends TestCase
+{
+    public function test_asset_facade_returns_the_asset_service()
+    {
+        $this->assertInstanceOf(AssetServiceContract::class, Asset::getFacadeRoot());
+    }
+
+    public function test_facade_returns_same_instance_as_bound_by_the_container()
+    {
+        $this->assertSame(Asset::getFacadeRoot(), app(AssetServiceContract::class));
+    }
+
+    public function test_asset_facade_can_call_methods_on_the_asset_service()
+    {
+        $service = new AssetService();
+        $this->assertEquals($service->version(), Asset::version());
+    }
+}

packages/framework/tests/Unit/Views/ScriptsComponentViewTest.php

@@ -0,0 +1,103 @@
+<?php
+
+namespace Hyde\Framework\Testing\Unit\Views;
+
+use Hyde\Framework\Hyde;
+use Hyde\Framework\Services\AssetService;
+use Hyde\Testing\TestCase;
+use Illuminate\Support\Facades\Blade;
+
+/**
+ * @see resources/views/layouts/scripts.blade.php
+ */
+class ScriptsComponentViewTest extends TestCase
+{
+    protected ?string $mockCurrentPage = null;
+
+    protected function renderTestView(): string
+    {
+        view()->share('currentPage', $this->mockCurrentPage ?? '');
+
+        return Blade::render(file_get_contents(
+            Hyde::vendorPath('resources/views/layouts/scripts.blade.php')
+        ));
+    }
+
+    public function test_component_can_be_rendered()
+    {
+        $this->assertStringContainsString('<script defer', $this->renderTestView());
+    }
+
+    public function test_component_has_link_to_app_js_file_when_it_exists()
+    {
+        touch(Hyde::path('_media/app.js'));
+        $this->assertStringContainsString('<script defer src="media/app.js"', $this->renderTestView());
+        unlink(Hyde::path('_media/app.js'));
+    }
+
+    public function test_component_does_not_render_link_to_app_js_when_it_does_not_exist()
+    {
+        $this->assertStringNotContainsString('<script defer src="media/app.js"', $this->renderTestView());
+    }
+
+    public function test_component_uses_relative_path_to_app_js_file_for_nested_pages()
+    {
+        touch(Hyde::path('_media/app.js'));
+        $this->mockCurrentPage = 'foo';
+        $this->assertStringContainsString('<script defer src="media/app.js"', $this->renderTestView());
+        $this->mockCurrentPage = 'foo/bar';
+        $this->assertStringContainsString('<script defer src="../media/app.js"', $this->renderTestView());
+        $this->mockCurrentPage = 'foo/bar/cat.html';
+        $this->assertStringContainsString('<script defer src="../../media/app.js"', $this->renderTestView());
+        $this->mockCurrentPage = null;
+        unlink(Hyde::path('_media/app.js'));
+    }
+
+    public function test_scripts_can_be_pushed_to_the_component_scripts_stack()
+    {
+        view()->share('currentPage', '');
+
+        $this->assertStringContainsString('foo bar',
+             Blade::render('
+                @push("scripts")
+                foo bar
+                @endpush
+                
+                @include("hyde::layouts.scripts")'
+             )
+        );
+    }
+
+    public function test_component_renders_link_to_hyde_js_when_it_exists()
+    {
+        touch(Hyde::path('_media/hyde.js'));
+        $this->assertStringContainsString('<script defer src="media/hyde.js"', $this->renderTestView());
+        unlink(Hyde::path('_media/hyde.js'));
+    }
+
+    public function test_component_does_not_render_link_to_hyde_js_when_it_does_not_exist()
+    {
+        $this->assertStringNotContainsString('<script defer src="media/hyde.js"', $this->renderTestView());
+    }
+
+    public function test_component_renders_cdn_link_when_no_local_file_exists()
+    {
+        $this->assertStringContainsString('https://cdn.jsdelivr.net/npm/hydefront', $this->renderTestView());
+    }
+
+    public function test_component_does_not_render_cdn_link_when_a_local_file_exists()
+    {
+        touch(Hyde::path('_media/hyde.js'));
+        $this->assertStringNotContainsString('https://cdn.jsdelivr.net/npm/hydefront', $this->renderTestView());
+        unlink(Hyde::path('_media/hyde.js'));
+    }
+
+    public function test_cdn_link_uses_the_correct_version_defined_in_the_asset_manager()
+    {
+        $expectedVersion = (new AssetService)->version();
+        $this->assertStringContainsString(
+            'https://cdn.jsdelivr.net/npm/hydefront@'.$expectedVersion.'/dist/hyde.js',
+            $this->renderTestView()
+        );
+    }
+}