Merge pull request #1568 from hydephp/improved-navigation-internals

[2.x] Rewrite navigation internals

Author: emmadesilva

RELEASE_NOTES.md

@@ -13,9 +13,12 @@ This serves two purposes:
 - Added a new `\Hyde\Framework\Actions\PreBuildTasks\TransferMediaAssets` build task handle media assets transfers for site builds.
 
 ### Changed
+- **Breaking:** The internals of the navigation system has been rewritten into a new Navigation API. This change is breaking for custom navigation implementations. For more information, see below.
+- Minor: Navigation menu items are now no longer filtered by duplicates (meaning two items with the same label can now exist in the same menu) in https://github.com/hydephp/develop/pull/1573
+- Minor: Due to changes in the navigation system, it is possible that existing configuration files will need to be adjusted in order for menus to look the same (in terms of ordering etc.)
+- Minor: The documentation article component now supports disabling the semantic rendering using a falsy value in https://github.com/hydephp/develop/pull/1566
 - Changed how the documentation search is generated, to be an `InMemoryPage` instead of a post-build task.
 - Media asset files are now copied using the new build task instead of the deprecated `BuildService::transferMediaAssets()` method.
-- Minor: The documentation article component now supports disabling the semantic rendering using a falsy value in https://github.com/hydephp/develop/pull/1566
 
 ### Deprecated
 - for soon-to-be removed features.
@@ -41,6 +44,32 @@ Please see the "Breaking changes & upgrade guide" section below for more informa
 
 Please read through this section to ensure your site upgrades smoothly.
 
+## High impact
+
+### Navigation system rewrite
+
+The navigation system has been rewritten into a new Navigation API. This change is breaking for custom navigation implementations, see more down below.
+
+For most users, the only impact will be that configuration files need to be updated to use the new configuration format. Due to the internal changes,
+it's also possible that menu items will be in a slightly different order than before, depending on your setup. Please verify that your site's menus
+look as expected after upgrading, and adjust the configuration files if necessary, before deploying to production.
+
+### Navigation and sidebar configuration changes
+
+The navigation and sidebar configuration files have been updated to use the new Navigation API.
+This means that you will need to update your configuration files to use the new format.
+
+The easiest way to upgrade is to publish updated configuration files (`hyde.php` and `docs.php`) and copy over your customizations.
+
+The following configuration entries have been updated:
+
+-  Changed configuration option `docs.sidebar_order` to `docs.sidebar.order` in https://github.com/hydephp/develop/pull/1583
+-  Upgrade path: Move the `sidebar_order` option's array in the `config/docs.php` file into the `sidebar` array in the same file.
+
+-  Changed configuration option `docs.table_of_contents` to `docs.sidebar.table_of_contents` in https://github.com/hydephp/develop/pull/1584
+-  Upgrade path: Move the `table_of_contents` option's array in the `config/docs.php` file into the `sidebar` array in the same file.
+
+
 ## General impact
 
 ### Documentation search page changes
@@ -49,26 +78,55 @@ The documentation search page and search index have been changed to be generated
 
 The main impact noticeable to most users by this is the implicit changes, like the pages showing up in the dashboard and route list command.
 
-In case you have customized the `GenerateSearch` post-build task you may, depending on what you were trying to do, 
+In case you have customized the `GenerateSearch` post-build task you may, depending on what you were trying to do,
 want to adapt your code to interact with the new `InMemoryPage`, which is generated in the `HydeCoreExtension` class.
 
 For more information, see https://github.com/hydephp/develop/pull/1498.
 
 ## Low impact
 
+### Navigation internal changes
+
+The navigation system has been rewritten into a new Navigation API. This change is breaking for custom navigation implementations.
+
+If you have previously in your custom code done any of the following, or similar, you will need to adapt your code to use the new Navigation API:
+- Created custom navigation menus or Blade components
+- Extended or called the navigation related classes directly
+- Customized the navigation system in any way beyond the standard configuration
+
+
+#### Upgrade guide
+
+Due to the scope of the rewrite, the easiest and fastest way to upgrade your code is to recreate it using the new Navigation API.
+
+- For a full comparison of the changes, you may see the PR that introduced the new API: https://github.com/hydephp/develop/pull/1568/files
+- For information on how to use the new Navigation API, see the documentation: https://hydephp.com/docs/2.x/navigation-api
+
+### HTML ID changes
+
+Some HTML IDs have been renamed to follow a more consistent naming convention.
+
+If you have used any of the following selectors in custom code you wrote yourself, you will need to update to use the new changed IDs.
+
+#### https://github.com/hydephp/develop/pull/1622
+- Rename HTML ID `#searchMenu` to `#search-menu`
+- Rename HTML ID `#searchMenuButton` to `#search-menu-button`
+- Rename HTML ID `#searchMenuButtonMobile` to `#search-menu-button-mobile`
+
+
 ### New documentation search implementation
 
 As the new documentation search implementation brings changes to their code API you may need to adapt your code
 according to the information below in case you wrote custom code that interacted with these parts of the codebase.
 
-- The `GenerateSearch` post-build task has been removed. If you have previously extended or customized this class, 
+- The `GenerateSearch` post-build task has been removed. If you have previously extended or customized this class,
   you will need to adapt your code, as the search index files are now handled implicitly during the standard build process,
   as the search pages are now added to the kernel page and route collection. (https://github.com/hydephp/develop/pull/1498)
 
 - If your site has a custom documentation search page, for example `_docs/search.md` or `_pages/docs/search.blade.php`,
-  that page will no longer be built when using the specific `build:search` command. It will, of course, 
+  that page will no longer be built when using the specific `build:search` command. It will, of course,
   be built using the standard `build` command. https://github.com/hydephp/develop/commit/82dc71f4a0e7b6be7a9f8d822fbebe39d2289ced
- 
+
 - In the highly unlikely event your site customizes any of the search pages by replacing them in the kernel route collection,
   you would now need to do that in the kernel page collection due to the search pages being generated earlier in the lifecycle.
   https://github.com/hydephp/develop/commit/82dc71f4a0e7b6be7a9f8d822fbebe39d2289ced

_ide_helper.php

@@ -22,6 +22,11 @@
 /** @var string $routeKey The route key for the page being compiled/previewed */
 $routeKey = \Hyde\Support\Facades\Render::getRouteKey();
 
+// Variables available only to some page types
+
+/** @var \Hyde\Framework\Features\Navigation\DocumentationSidebar $sidebar */
+$sidebar = app('navigation.sidebar');
+
 // Facades (aliased in app/config.php)
 
 /** @mixin \Hyde\Foundation\HydeKernel */

app/config.php

@@ -73,6 +73,7 @@
         Hyde\Foundation\Providers\ConfigurationServiceProvider::class,
         Hyde\Framework\HydeServiceProvider::class,
         Hyde\Foundation\Providers\ViewServiceProvider::class,
+        Hyde\Foundation\Providers\NavigationServiceProvider::class,
         Hyde\Console\ConsoleServiceProvider::class,
     ],
 

config/docs.php

@@ -30,49 +30,49 @@
         // When using a grouped sidebar, should the groups be collapsible?
         'collapsible' => true,
 
-        // Should the sidebar footer be shown? You can also set this to a string
-        // of Markdown to show in the footer. Set to `false` to disable.
-        'footer' => true,
-    ],
-
-    /*
-    |--------------------------------------------------------------------------
-    | Sidebar Page Order
-    |--------------------------------------------------------------------------
-    |
-    | In the generated Documentation pages the navigation links in the sidebar
-    | default to sort alphabetically. You can reorder the page identifiers
-    | in the list below, and the links will get sorted in that order.
-    |
-    | The items will get a priority of 500 plus the order its found in the list.
-    | Pages without a priority will fall back to the default priority of 999.
-    |
-    | You can also set explicit priorities in front matter or by specifying
-    | a value to the array key in the list to override the inferred value.
-    |
-    */
-
-    'sidebar_order' => [
-        'readme',
-        'installation',
-        'getting-started',
-    ],
-
-    /*
-    |--------------------------------------------------------------------------
-    | Table of Contents Settings
-    |--------------------------------------------------------------------------
-    |
-    | The Hyde Documentation Module comes with a fancy Sidebar that, by default,
-    | has a Table of Contents included. Here, you can configure its behavior,
-    | content, look and feel. You can also disable the feature completely.
-    |
-    */
+        // A string of Markdown to show in the footer. Set to `false` to disable.
+        'footer' => '[Back to home page](../)',
+
+        /*
+        |--------------------------------------------------------------------------
+        | Sidebar Page Order
+        |--------------------------------------------------------------------------
+        |
+        | In the generated Documentation pages the navigation links in the sidebar
+        | default to sort alphabetically. You can reorder the page identifiers
+        | in the list below, and the links will get sorted in that order.
+        |
+        | The items will get a priority of 500 plus the order its found in the list.
+        | Pages without a priority will fall back to the default priority of 999.
+        |
+        | You can also set explicit priorities in front matter or by specifying
+        | a value to the array key in the list to override the inferred value.
+        |
+        */
+
+        'order' => [
+            'readme',
+            'installation',
+            'getting-started',
+        ],
+
+        /*
+        |--------------------------------------------------------------------------
+        | Table of Contents Settings
+        |--------------------------------------------------------------------------
+        |
+        | The Hyde Documentation Module comes with a fancy Sidebar that, by default,
+        | has a Table of Contents included. Here, you can configure its behavior,
+        | content, look and feel. You can also disable the feature completely.
+        |
+        */
+
+        'table_of_contents' => [
+            'enabled' => true,
+            'min_heading_level' => 2,
+            'max_heading_level' => 4,
+        ],
 
-    'table_of_contents' => [
-        'enabled' => true,
-        'min_heading_level' => 2,
-        'max_heading_level' => 4,
     ],
 
     /*

config/hyde.php

@@ -350,7 +350,7 @@
         // To get started quickly, you can uncomment the defaults here.
         // See the documentation link above for more information.
         'custom' => [
-            // NavItem::forLink('https://github.com/hydephp/hyde', 'GitHub', 200),
+            // NavigationItem::create('https://github.com/hydephp/hyde', 'GitHub', 200),
         ],
 
         // How should pages in subdirectories be displayed in the menu?