Merge pull request #1542 from hydephp/improved-head-and-scripts-includes

Add configuration options to add HTML to the head and scripts sections
hydephp · Feb 11, 2024 · 23f587f · 23f587f
2 parents 3bb136e + eb959a9
commit 23f587f
Show file tree

Hide file tree

Showing 7 changed files with 99 additions and 2 deletions.
diff --git a/config/hyde.php b/config/hyde.php
@@ -224,6 +224,23 @@
         Meta::property('site_name', env('SITE_NAME', 'HydePHP')),
     ],
 
+    /*
+    |--------------------------------------------------------------------------
+    | Custom head and script HTML hooks
+    |--------------------------------------------------------------------------
+    |
+    | While the best way to add custom `<head>` and `<body>` code is to use the
+    | Blade components, you can also add them here. This is useful for adding
+    | scripts like analytics codes, chat widgets, or even custom styles.
+    |
+    */
+
+    // Add any extra HTML to include in the <head> tag
+    'head' => '',
+
+    // Add any extra HTML to include before the closing <body> tag
+    'scripts' => '',
+
     /*
     |--------------------------------------------------------------------------
     | Features

diff --git a/docs/digging-deeper/customization.md b/docs/digging-deeper/customization.md
@@ -200,6 +200,49 @@ If you don't want to have a footer on your site, you can set the `'footer'` conf
 'footer' => 'false',
 ```
 
+### Head and script HTML hooks
+
+>info Note: The configuration options `head` and `scripts` were added in HydePHP v1.5. If you are running an older version, you need to use the Blade options, or upgrade your project.
+
+While the most robust way to add custom HTML to the head or body of your site is to publish the Blade layouts, or pushing to the `meta` or `scripts` stacks,
+you can also add custom HTML directly in the configuration file. This works especially well to quickly add things like analytics widgets or similar in the `hyde.yml` file, though the possibilities are endless.
+
+To add custom HTML to your layouts, you can use the `head` and `scripts` configuration options in the `config/hyde.php` file (or the `hyde.yml` file).
+The HTML will be added to the `<head>` section, or just before the closing `</body>` tag, respectively.
+Note that the HTML is added to all pages. If you need to add HTML to a specific page, you will need to override the layout for that page.
+
+```php
+// filepath: config/hyde.php
+'head' => '<!-- Custom HTML in the head -->',
+'scripts' => '<!-- Custom HTML in the body -->',
+```
+
+```yaml
+# filepath: hyde.yml
+hyde:
+  head: "<!-- Custom HTML in the head -->"
+  scripts: "<!-- Custom HTML in the body -->"
+```
+
+You can of course also add multiple lines of HTML:
+
+```php
+// filepath: config/hyde.php
+'head' => <<<HTML
+    <!-- Custom HTML in the head -->
+    <link rel="stylesheet" href="https://example.com/styles.css">
+HTML,
+```
+
+```yaml
+# filepath: hyde.yml
+
+hyde:
+  head: |
+    <!-- Custom HTML in the head -->
+    <link rel="stylesheet" href="https://example.com/styles.css">
+```
+
 ### Navigation Menu & Sidebar
 
 A great time-saving feature of HydePHP is the automatic navigation menu and documentation sidebar generation.

diff --git a/packages/framework/config/hyde.php b/packages/framework/config/hyde.php
@@ -224,6 +224,23 @@
         Meta::property('site_name', env('SITE_NAME', 'HydePHP')),
     ],
 
+    /*
+    |--------------------------------------------------------------------------
+    | Custom head and script HTML hooks
+    |--------------------------------------------------------------------------
+    |
+    | While the best way to add custom `<head>` and `<body>` code is to use the
+    | Blade components, you can also add them here. This is useful for adding
+    | scripts like analytics codes, chat widgets, or even custom styles.
+    |
+    */
+
+    // Add any extra HTML to include in the <head> tag
+    'head' => '',
+
+    // Add any extra HTML to include before the closing <body> tag
+    'scripts' => '',
+
     /*
     |--------------------------------------------------------------------------
     | Features

diff --git a/packages/framework/resources/views/layouts/head.blade.php b/packages/framework/resources/views/layouts/head.blade.php
@@ -16,4 +16,7 @@
     {{-- Check the local storage for theme preference to avoid FOUC --}}
     <meta id="meta-color-scheme" name="color-scheme" content="{{ config('hyde.default_color_scheme', 'light') }}">
     <script>if (localStorage.getItem('color-theme') === 'dark' || (!('color-theme' in localStorage) && window.matchMedia('(prefers-color-scheme: dark)').matches)) { document.documentElement.classList.add('dark'); document.getElementById('meta-color-scheme').setAttribute('content', 'dark');} else { document.documentElement.classList.remove('dark') } </script>
-@endif
+@endif
+
+{{-- If the user has defined any custom head tags, render them here --}}
+{!! config('hyde.head') !!}
diff --git a/packages/framework/resources/views/layouts/scripts.blade.php b/packages/framework/resources/views/layouts/scripts.blade.php
@@ -21,4 +21,7 @@ function toggleTheme() {
 </script>
 
 {{-- Add any extra scripts to include before the closing <body> tag --}}
-@stack('scripts')
+@stack('scripts')
+
+{{-- If the user has defined any custom scripts, render them here --}}
+{!! config('hyde.scripts') !!}
diff --git a/packages/framework/tests/Unit/Views/HeadComponentViewTest.php b/packages/framework/tests/Unit/Views/HeadComponentViewTest.php
@@ -72,6 +72,13 @@ public function testComponentIncludesStylesView()
         $this->assertStringContainsString("@include('hyde::layouts.styles')", $this->renderTestView());
     }
 
+    public function testCanAddHeadHtmlFromConfigHook()
+    {
+        config(['hyde.head' => '<meta name="custom-hook" content="foo">']);
+
+        $this->assertStringContainsString('<meta name="custom-hook" content="foo">', $this->renderTestView());
+    }
+
     protected function escapeIncludes(string $contents): string
     {
         return str_replace('@include', '@@include', $contents);

diff --git a/packages/framework/tests/Unit/Views/ScriptsComponentViewTest.php b/packages/framework/tests/Unit/Views/ScriptsComponentViewTest.php
@@ -56,6 +56,13 @@ public function test_component_uses_relative_path_to_app_js_file_for_nested_page
         Filesystem::unlink('_media/app.js');
     }
 
+    public function testCanAddHeadHtmlFromConfigHook()
+    {
+        config(['hyde.scripts' => '<script src="custom-hook.js"></script>']);
+
+        $this->assertStringContainsString('<script src="custom-hook.js"></script>', $this->renderTestView());
+    }
+
     public function test_scripts_can_be_pushed_to_the_component_scripts_stack()
     {
         view()->share('routeKey', '');