Improve preloader animation (#1255)

* Add improvements on the preloader animation * Add tests for the new preloader improvements * Add style CI fix * Refactor: split out logic from LayoutHelper to PreloaderHelper * Apply fix related to style CI
jeroennoten · Mar 8, 2024 · 21b94f6 · 21b94f6
1 parent 6f77753
commit 21b94f6
Show file tree

Hide file tree

Showing 8 changed files with 242 additions and 29 deletions.
diff --git a/config/adminlte.php b/config/adminlte.php
@@ -99,7 +99,10 @@
     | Preloader Animation
     |--------------------------------------------------------------------------
     |
-    | Here you can change the preloader animation configuration.
+    | Here you can change the preloader animation configuration. Currently, two
+    | modes are supported: 'fullscreen' for a fullscreen preloader animation
+    | and 'cwrapper' to attach the preloader animation into the content-wrapper
+    | element and avoid overlapping it with the sidebars and the top navbar.
     |
     | For detailed instructions you can look the preloader section here:
     | https://github.com/jeroennoten/Laravel-AdminLTE/wiki/Basic-Configuration
@@ -108,6 +111,7 @@
 
     'preloader' => [
         'enabled' => true,
+        'mode' => 'fullscreen',
         'img' => [
             'path' => 'vendor/adminlte/dist/img/AdminLTELogo.png',
             'alt' => 'AdminLTE Preloader Image',

diff --git a/resources/views/page.blade.php b/resources/views/page.blade.php
@@ -1,6 +1,7 @@
 @extends('adminlte::master')
 
 @inject('layoutHelper', 'JeroenNoten\LaravelAdminLte\Helpers\LayoutHelper')
+@inject('preloaderHelper', 'JeroenNoten\LaravelAdminLte\Helpers\PreloaderHelper')
 
 @section('adminlte_css')
     @stack('css')
@@ -14,8 +15,8 @@
 @section('body')
     <div class="wrapper">
 
-        {{-- Preloader Animation --}}
-        @if($layoutHelper->isPreloaderEnabled())
+        {{-- Preloader Animation (fullscreen mode) --}}
+        @if($preloaderHelper->isPreloaderEnabled())
             @include('adminlte::partials.common.preloader')
         @endif
 

diff --git a/resources/views/partials/common/preloader.blade.php b/resources/views/partials/common/preloader.blade.php
@@ -1,10 +1,22 @@
-<div class="preloader flex-column justify-content-center align-items-center">
-
-    {{-- Preloader logo --}}
-    <img src="{{ asset(config('adminlte.preloader.img.path', 'vendor/adminlte/dist/img/AdminLTELogo.png')) }}"
-         class="{{ config('adminlte.preloader.img.effect', 'animation__shake') }}"
-         alt="{{ config('adminlte.preloader.img.alt', 'AdminLTE Preloader Image') }}"
-         width="{{ config('adminlte.preloader.img.width', 60) }}"
-         height="{{ config('adminlte.preloader.img.height', 60) }}">
+@inject('preloaderHelper', 'JeroenNoten\LaravelAdminLte\Helpers\PreloaderHelper')
+
+<div class="{{ $preloaderHelper->makePreloaderClasses() }}" style="{{ $preloaderHelper->makePreloaderStyle() }}">
+
+    @hasSection('preloader')
+
+        {{-- Use a custom preloader content --}}
+        @yield('preloader')
+
+    @else
+
+        {{-- Use the default preloader content --}}
+        <img src="{{ asset(config('adminlte.preloader.img.path', 'vendor/adminlte/dist/img/AdminLTELogo.png')) }}"
+             class="img-circle {{ config('adminlte.preloader.img.effect', 'animation__shake') }}"
+             alt="{{ config('adminlte.preloader.img.alt', 'AdminLTE Preloader Image') }}"
+             width="{{ config('adminlte.preloader.img.width', 60) }}"
+             height="{{ config('adminlte.preloader.img.height', 60) }}"
+             style="animation-iteration-count:infinite;">
+
+    @endif
 
 </div>
diff --git a/resources/views/partials/cwrapper/cwrapper-default.blade.php b/resources/views/partials/cwrapper/cwrapper-default.blade.php
@@ -1,4 +1,5 @@
 @inject('layoutHelper', 'JeroenNoten\LaravelAdminLte\Helpers\LayoutHelper')
+@inject('preloaderHelper', 'JeroenNoten\LaravelAdminLte\Helpers\preloaderHelper')
 
 @if($layoutHelper->isLayoutTopnavEnabled())
     @php( $def_container_class = 'container' )
@@ -7,7 +8,12 @@
 @endif
 
 {{-- Default Content Wrapper --}}
-<div class="content-wrapper {{ config('adminlte.classes_content_wrapper', '') }}">
+<div class="{{ $layoutHelper->makeContentWrapperClasses() }}">
+
+    {{-- Preloader Animation (cwrapper mode) --}}
+    @if($preloaderHelper->isPreloaderEnabled('cwrapper'))
+        @include('adminlte::partials.common.preloader')
+    @endif
 
     {{-- Content Header --}}
     @hasSection('content_header')

diff --git a/src/Helpers/LayoutHelper.php b/src/Helpers/LayoutHelper.php
@@ -22,16 +22,6 @@ class LayoutHelper
      */
     protected static $sidebarMiniValues = ['xs', 'md', 'lg'];
 
-    /**
-     * Check if the preloader animation is enabled.
-     *
-     * @return bool
-     */
-    public static function isPreloaderEnabled()
-    {
-        return config('adminlte.preloader.enabled', false);
-    }
-
     /**
      * Check if layout topnav is enabled.
      *
@@ -98,6 +88,33 @@ public static function makeBodyData()
         return trim(implode(' ', $data));
     }
 
+    /**
+     * Make and return the set of classes related to the content-wrapper
+     * element.
+     *
+     * @return string
+     */
+    public static function makeContentWrapperClasses()
+    {
+        $classes = ['content-wrapper'];
+
+        // Add classes from the configuration file.
+
+        $cfg = config('adminlte.classes_content_wrapper');
+
+        if (is_string($cfg) && ! empty($cfg)) {
+            $classes[] = $cfg;
+        }
+
+        // Add position-relative when using a content-wrapper preloader.
+
+        if (PreloaderHelper::isPreloaderEnabled('cwrapper')) {
+            $classes[] = 'position-relative';
+        }
+
+        return trim(implode(' ', $classes));
+    }
+
     /**
      * Make and return the set of classes related to the layout configuration.
      *

diff --git a/src/Helpers/PreloaderHelper.php b/src/Helpers/PreloaderHelper.php
@@ -0,0 +1,65 @@
+<?php
+
+namespace JeroenNoten\LaravelAdminLte\Helpers;
+
+class PreloaderHelper
+{
+    /**
+     * Check if the preloader animation is enabled for the specified mode.
+     *
+     * @param  string  $mode  The preloader mode to check.
+     * @return bool
+     */
+    public static function isPreloaderEnabled($mode = 'fullscreen')
+    {
+        return config('adminlte.preloader.enabled', false)
+            && config('adminlte.preloader.mode', 'fullscreen') == $mode;
+    }
+
+    /**
+     * Make and return the set of classes related to the preloader animation.
+     *
+     * @return string
+     */
+    public static function makePreloaderClasses()
+    {
+        // Setup the base set of classes for the preloader.
+
+        $classes = [
+            'preloader',
+            'flex-column',
+            'justify-content-center',
+            'align-items-center',
+        ];
+
+        // When the preloader is attached to the content-wrapper, the CSS
+        // position attribute should be absolute.
+
+        if (self::isPreloaderEnabled('cwrapper')) {
+            $classes[] = 'position-absolute';
+        }
+
+        return trim(implode(' ', $classes));
+    }
+
+    /**
+     * Make and return the set of styles related to the preloader.
+     *
+     * @return string
+     */
+    public static function makePreloaderStyle()
+    {
+        $styles = [];
+
+        // When the preloader is attached to the content-wrapper, the CSS
+        // z-index attribute should be less than the value of z-index for the
+        // sidebars, the top navbar and the footer (they all are between 1030
+        // and 1040). This way, we avoid overlapping with those elements.
+
+        if (self::isPreloaderEnabled('cwrapper')) {
+            $styles[] = 'z-index:1000';
+        }
+
+        return trim(implode(';', $styles));
+    }
+}
diff --git a/tests/Helpers/LayoutHelperTest.php b/tests/Helpers/LayoutHelperTest.php
@@ -4,19 +4,32 @@
 
 class LayoutHelperTest extends TestCase
 {
-    public function testEnableDisablePreloader()
+    public function testMakeContentWrapperClasses()
     {
-        // Test with config enabled.
+        // Test without config.
+
+        $data = LayoutHelper::makeContentWrapperClasses();
+        $this->assertEquals('content-wrapper', $data);
+
+        // Test with custom classes on the configuration.
 
-        config(['adminlte.preloader.enabled' => true]);
+        config(['adminlte.classes_content_wrapper' => 'class1 class2']);
 
-        $this->assertTrue(LayoutHelper::isPreloaderEnabled());
+        $data = LayoutHelper::makeContentWrapperClasses();
+        $this->assertStringContainsString('content-wrapper', $data);
+        $this->assertStringContainsString('class1', $data);
+        $this->assertStringContainsString('class2', $data);
 
-        // Test with config disabled.
+        // Test with cwrapper mode enabled.
 
-        config(['adminlte.preloader.enabled' => false]);
+        config([
+            'adminlte.preloader.enabled' => true,
+            'adminlte.preloader.mode' => 'cwrapper',
+        ]);
 
-        $this->assertFalse(LayoutHelper::isPreloaderEnabled());
+        $data = LayoutHelper::makeContentWrapperClasses();
+        $this->assertStringContainsString('content-wrapper', $data);
+        $this->assertStringContainsString('position-relative', $data);
     }
 
     public function testMakeBodyData()

diff --git a/tests/Helpers/PreloaderHelperTest.php b/tests/Helpers/PreloaderHelperTest.php
@@ -0,0 +1,95 @@
+<?php
+
+use JeroenNoten\LaravelAdminLte\Helpers\PreloaderHelper;
+
+class PreloaderHelperTest extends TestCase
+{
+    public function testEnableDisablePreloaderFullscreenMode()
+    {
+        // Test with config enabled.
+
+        config(['adminlte.preloader.enabled' => true]);
+
+        $this->assertTrue(PreloaderHelper::isPreloaderEnabled());
+        $this->assertTrue(PreloaderHelper::isPreloaderEnabled('fullscreen'));
+        $this->assertFalse(PreloaderHelper::isPreloaderEnabled('cwrapper'));
+
+        // Test with config disabled.
+
+        config(['adminlte.preloader.enabled' => false]);
+
+        $this->assertFalse(PreloaderHelper::isPreloaderEnabled());
+        $this->assertFalse(PreloaderHelper::isPreloaderEnabled('fullscreen'));
+        $this->assertFalse(PreloaderHelper::isPreloaderEnabled('cwrapper'));
+    }
+
+    public function testEnableDisablePreloaderCWrapperMode()
+    {
+        // Test with config enabled.
+
+        config([
+            'adminlte.preloader.enabled' => true,
+            'adminlte.preloader.mode' => 'cwrapper',
+        ]);
+
+        $this->assertFalse(PreloaderHelper::isPreloaderEnabled());
+        $this->assertFalse(PreloaderHelper::isPreloaderEnabled('fullscreen'));
+        $this->assertTrue(PreloaderHelper::isPreloaderEnabled('cwrapper'));
+
+        // Test with config disabled.
+
+        config([
+            'adminlte.preloader.enabled' => false,
+            'adminlte.preloader.mode' => 'cwrapper',
+        ]);
+
+        $this->assertFalse(PreloaderHelper::isPreloaderEnabled());
+        $this->assertFalse(PreloaderHelper::isPreloaderEnabled('fullscreen'));
+        $this->assertFalse(PreloaderHelper::isPreloaderEnabled('cwrapper'));
+    }
+
+    public function testMakePreloaderClasses()
+    {
+        // Test without config.
+
+        $data = PreloaderHelper::makePreloaderClasses();
+        $this->assertEquals(
+            'preloader flex-column justify-content-center align-items-center',
+            $data
+        );
+
+        // Test with cwrapper mode enabled.
+
+        config([
+            'adminlte.preloader.enabled' => true,
+            'adminlte.preloader.mode' => 'cwrapper',
+        ]);
+
+        $data = PreloaderHelper::makePreloaderClasses();
+
+        $this->assertStringContainsString(
+            'preloader flex-column justify-content-center align-items-center',
+            $data
+        );
+
+        $this->assertStringContainsString('position-absolute', $data);
+    }
+
+    public function testMakePreloaderStyle()
+    {
+        // Test without config.
+
+        $data = PreloaderHelper::makePreloaderStyle();
+        $this->assertEquals('', $data);
+
+        // Test with cwrapper mode enabled.
+
+        config([
+            'adminlte.preloader.enabled' => true,
+            'adminlte.preloader.mode' => 'cwrapper',
+        ]);
+
+        $data = PreloaderHelper::makePreloaderStyle();
+        $this->assertStringContainsString('z-index:', $data);
+    }
+}