From 9046c882eac9d6f8ea28e6d222bc7476189c843d Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 12:43:07 +0200 Subject: [PATCH 001/232] Create NavigationFacadeTest.php --- .../tests/Unit/Facades/NavigationFacadeTest.php | 15 +++++++++++++++ 1 file changed, 15 insertions(+) create mode 100644 packages/framework/tests/Unit/Facades/NavigationFacadeTest.php diff --git a/packages/framework/tests/Unit/Facades/NavigationFacadeTest.php b/packages/framework/tests/Unit/Facades/NavigationFacadeTest.php new file mode 100644 index 00000000000..f9474f285bc --- /dev/null +++ b/packages/framework/tests/Unit/Facades/NavigationFacadeTest.php @@ -0,0 +1,15 @@ + Date: Wed, 10 Jul 2024 12:39:10 +0200 Subject: [PATCH 002/232] Create Navigation.php --- packages/framework/src/Facades/Navigation.php | 10 ++++++++++ 1 file changed, 10 insertions(+) create mode 100644 packages/framework/src/Facades/Navigation.php diff --git a/packages/framework/src/Facades/Navigation.php b/packages/framework/src/Facades/Navigation.php new file mode 100644 index 00000000000..a1e2286b01f --- /dev/null +++ b/packages/framework/src/Facades/Navigation.php @@ -0,0 +1,10 @@ + Date: Wed, 10 Jul 2024 12:44:04 +0200 Subject: [PATCH 003/232] Alias the Navigation facade --- app/config.php | 1 + 1 file changed, 1 insertion(+) diff --git a/app/config.php b/app/config.php index ab5db6907b0..143a4a6dda4 100644 --- a/app/config.php +++ b/app/config.php @@ -97,6 +97,7 @@ 'Features' => \Hyde\Facades\Features::class, 'Config' => \Hyde\Facades\Config::class, 'Filesystem' => \Hyde\Facades\Filesystem::class, + 'Navigation' => \Hyde\Facades\Navigation::class, 'Routes' => \Hyde\Foundation\Facades\Routes::class, 'HtmlPage' => \Hyde\Pages\HtmlPage::class, 'BladePage' => \Hyde\Pages\BladePage::class, From c35db97b1c8b8235243182a13589c19a2d02d1c3 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 12:46:51 +0200 Subject: [PATCH 004/232] Add facade class documentation --- packages/framework/src/Facades/Navigation.php | 3 +++ 1 file changed, 3 insertions(+) diff --git a/packages/framework/src/Facades/Navigation.php b/packages/framework/src/Facades/Navigation.php index a1e2286b01f..60d4ac8360a 100644 --- a/packages/framework/src/Facades/Navigation.php +++ b/packages/framework/src/Facades/Navigation.php @@ -4,6 +4,9 @@ namespace Hyde\Facades; +/** + * General facade for navigation features. + */ class Navigation { // From 5e276288d2008d2d82361f07a544e505086468fb Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 15:55:39 +0200 Subject: [PATCH 005/232] Add configuration helper to the Navigation facade to create item array --- packages/framework/src/Facades/Navigation.php | 18 ++++++++++++++- .../Unit/Facades/NavigationFacadeTest.php | 23 ++++++++++++++++++- 2 files changed, 39 insertions(+), 2 deletions(-) diff --git a/packages/framework/src/Facades/Navigation.php b/packages/framework/src/Facades/Navigation.php index 60d4ac8360a..a91b41fef5a 100644 --- a/packages/framework/src/Facades/Navigation.php +++ b/packages/framework/src/Facades/Navigation.php @@ -4,10 +4,26 @@ namespace Hyde\Facades; +use function compact; + /** * General facade for navigation features. */ class Navigation { - // + /** + * Configuration helper method to define a new navigation item, with better IDE support. + * + * The returned array will then be used by the framework to create a new NavigationItem instance. + * + * @see https://hydephp.com/docs/2.x/navigation-api + * + * @param string<\Hyde\Support\Models\RouteKey>|string $destination Route key, or an external URI. + * @param string|null $label If not provided, Hyde will try to get it from the route's connected page, or from the URL. + * @param int|null $priority If not provided, Hyde will try to get it from the route or the default priority of 500. + */ + public static function item(string $destination, ?string $label = null, ?int $priority = null): array + { + return compact('destination', 'label', 'priority'); + } } diff --git a/packages/framework/tests/Unit/Facades/NavigationFacadeTest.php b/packages/framework/tests/Unit/Facades/NavigationFacadeTest.php index f9474f285bc..2c7e27e61ac 100644 --- a/packages/framework/tests/Unit/Facades/NavigationFacadeTest.php +++ b/packages/framework/tests/Unit/Facades/NavigationFacadeTest.php @@ -4,6 +4,7 @@ namespace Hyde\Framework\Testing\Unit\Facades; +use Hyde\Facades\Navigation; use Hyde\Testing\UnitTestCase; /** @@ -11,5 +12,25 @@ */ class NavigationFacadeTest extends UnitTestCase { - // + public function testItem(): void + { + $item = Navigation::item('home', 'Home', 100); + + $this->assertSame([ + 'destination' => 'home', + 'label' => 'Home', + 'priority' => 100, + ], $item); + } + + public function testItemWithOnlyDestination(): void + { + $item = Navigation::item('home'); + + $this->assertSame([ + 'destination' => 'home', + 'label' => null, + 'priority' => null, + ], $item); + } } From 7733c698ceda2d14b60708f2a4674cf9ca5badad Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 15:58:32 +0200 Subject: [PATCH 006/232] Remove test method type annotations --- .../framework/tests/Unit/Facades/NavigationFacadeTest.php | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/framework/tests/Unit/Facades/NavigationFacadeTest.php b/packages/framework/tests/Unit/Facades/NavigationFacadeTest.php index 2c7e27e61ac..b9365eefb0d 100644 --- a/packages/framework/tests/Unit/Facades/NavigationFacadeTest.php +++ b/packages/framework/tests/Unit/Facades/NavigationFacadeTest.php @@ -12,7 +12,7 @@ */ class NavigationFacadeTest extends UnitTestCase { - public function testItem(): void + public function testItem() { $item = Navigation::item('home', 'Home', 100); @@ -23,7 +23,7 @@ public function testItem(): void ], $item); } - public function testItemWithOnlyDestination(): void + public function testItemWithOnlyDestination() { $item = Navigation::item('home'); From 4c99f022e6a38703bedf837625850fdee735b395 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 15:58:18 +0200 Subject: [PATCH 007/232] Test item method with URL --- .../tests/Unit/Facades/NavigationFacadeTest.php | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/packages/framework/tests/Unit/Facades/NavigationFacadeTest.php b/packages/framework/tests/Unit/Facades/NavigationFacadeTest.php index b9365eefb0d..bbc7e2d84f0 100644 --- a/packages/framework/tests/Unit/Facades/NavigationFacadeTest.php +++ b/packages/framework/tests/Unit/Facades/NavigationFacadeTest.php @@ -33,4 +33,15 @@ public function testItemWithOnlyDestination() 'priority' => null, ], $item); } + + public function testItemWithUrl() + { + $item = Navigation::item('https://example.com', 'External', 200); + + $this->assertSame([ + 'destination' => 'https://example.com', + 'label' => 'External', + 'priority' => 200, + ], $item); + } } From 598df29b13fac48d3a27ada08c45d18365dc224a Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 16:01:38 +0200 Subject: [PATCH 008/232] Prepare generator for configuration type change --- .../Features/Navigation/NavigationMenuGenerator.php | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php b/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php index d2bd01921f8..d2dbab7d0d2 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php @@ -17,6 +17,7 @@ use function collect; use function in_array; use function strtolower; +use function trigger_deprecation; /** * @experimental This class may change significantly before its release. @@ -81,7 +82,16 @@ protected function generate(): void $this->items->push(NavigationItem::create(DocumentationPage::home())); } } else { - collect(Config::getArray('hyde.navigation.custom', []))->each(function (NavigationItem $item): void { + collect(Config::getArray('hyde.navigation.custom', []))->each(function (NavigationItem|array $item): void { + // In preparation of refactor: + // @codeCoverageIgnoreStart + if (is_array($item)) { + $item = NavigationItem::create($item['destination'], $item['label'] ?? null, $item['priority'] ?? null); + } else { + trigger_deprecation('hydephp/hyde', '2.0', 'Passing a NavigationItem instance directly to the navigation menu is deprecated. Use the array format instead. (Replace with \Navigation::item(...))'); + } + // @codeCoverageIgnoreEnd + // Since these were added explicitly by the user, we can assume they should always be shown $this->items->push($item); }); From ebb703828bc34064d100862e982916ee7384cd39 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 16:03:32 +0200 Subject: [PATCH 009/232] Test covers the navigation facade --- .../tests/Feature/AutomaticNavigationConfigurationsTest.php | 1 + 1 file changed, 1 insertion(+) diff --git a/packages/framework/tests/Feature/AutomaticNavigationConfigurationsTest.php b/packages/framework/tests/Feature/AutomaticNavigationConfigurationsTest.php index 8d3ee0e380d..c5763cf2e89 100644 --- a/packages/framework/tests/Feature/AutomaticNavigationConfigurationsTest.php +++ b/packages/framework/tests/Feature/AutomaticNavigationConfigurationsTest.php @@ -28,6 +28,7 @@ * * @see \Hyde\Framework\Testing\Unit\Views\NavigationHtmlLayoutsTest * + * @covers \Hyde\Facades\Navigation * @covers \Hyde\Framework\Factories\NavigationDataFactory * @covers \Hyde\Framework\Features\Navigation\NavigationMenuGenerator * @covers \Hyde\Framework\Features\Navigation\DocumentationSidebar From 7fcd967f0784b248016288e255205fe37eaeb8e9 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 16:06:50 +0200 Subject: [PATCH 010/232] Remove temporary refactor code Want to see where this fails so we can update it in the right places --- .../Features/Navigation/NavigationMenuGenerator.php | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php b/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php index d2dbab7d0d2..e510dcdae28 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php @@ -17,7 +17,6 @@ use function collect; use function in_array; use function strtolower; -use function trigger_deprecation; /** * @experimental This class may change significantly before its release. @@ -82,15 +81,8 @@ protected function generate(): void $this->items->push(NavigationItem::create(DocumentationPage::home())); } } else { - collect(Config::getArray('hyde.navigation.custom', []))->each(function (NavigationItem|array $item): void { - // In preparation of refactor: - // @codeCoverageIgnoreStart - if (is_array($item)) { - $item = NavigationItem::create($item['destination'], $item['label'] ?? null, $item['priority'] ?? null); - } else { - trigger_deprecation('hydephp/hyde', '2.0', 'Passing a NavigationItem instance directly to the navigation menu is deprecated. Use the array format instead. (Replace with \Navigation::item(...))'); - } - // @codeCoverageIgnoreEnd + collect(Config::getArray('hyde.navigation.custom', []))->each(function (array $item): void { + $item = NavigationItem::create($item['destination'], $item['label'] ?? null, $item['priority'] ?? null); // Since these were added explicitly by the user, we can assume they should always be shown $this->items->push($item); From ab6e659a97f4f667f1183072168f121b1aa732af Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 16:12:33 +0200 Subject: [PATCH 011/232] Revert "Remove temporary refactor code" This reverts commit 7fcd967f0784b248016288e255205fe37eaeb8e9. --- .../Features/Navigation/NavigationMenuGenerator.php | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php b/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php index e510dcdae28..d2dbab7d0d2 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php @@ -17,6 +17,7 @@ use function collect; use function in_array; use function strtolower; +use function trigger_deprecation; /** * @experimental This class may change significantly before its release. @@ -81,8 +82,15 @@ protected function generate(): void $this->items->push(NavigationItem::create(DocumentationPage::home())); } } else { - collect(Config::getArray('hyde.navigation.custom', []))->each(function (array $item): void { - $item = NavigationItem::create($item['destination'], $item['label'] ?? null, $item['priority'] ?? null); + collect(Config::getArray('hyde.navigation.custom', []))->each(function (NavigationItem|array $item): void { + // In preparation of refactor: + // @codeCoverageIgnoreStart + if (is_array($item)) { + $item = NavigationItem::create($item['destination'], $item['label'] ?? null, $item['priority'] ?? null); + } else { + trigger_deprecation('hydephp/hyde', '2.0', 'Passing a NavigationItem instance directly to the navigation menu is deprecated. Use the array format instead. (Replace with \Navigation::item(...))'); + } + // @codeCoverageIgnoreEnd // Since these were added explicitly by the user, we can assume they should always be shown $this->items->push($item); From b22c3118d502bb1b4b1bc121cd633f9908ec40fb Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 16:12:39 +0200 Subject: [PATCH 012/232] Revert "Prepare generator for configuration type change" This reverts commit 598df29b13fac48d3a27ada08c45d18365dc224a. --- .../Features/Navigation/NavigationMenuGenerator.php | 12 +----------- 1 file changed, 1 insertion(+), 11 deletions(-) diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php b/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php index d2dbab7d0d2..d2bd01921f8 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php @@ -17,7 +17,6 @@ use function collect; use function in_array; use function strtolower; -use function trigger_deprecation; /** * @experimental This class may change significantly before its release. @@ -82,16 +81,7 @@ protected function generate(): void $this->items->push(NavigationItem::create(DocumentationPage::home())); } } else { - collect(Config::getArray('hyde.navigation.custom', []))->each(function (NavigationItem|array $item): void { - // In preparation of refactor: - // @codeCoverageIgnoreStart - if (is_array($item)) { - $item = NavigationItem::create($item['destination'], $item['label'] ?? null, $item['priority'] ?? null); - } else { - trigger_deprecation('hydephp/hyde', '2.0', 'Passing a NavigationItem instance directly to the navigation menu is deprecated. Use the array format instead. (Replace with \Navigation::item(...))'); - } - // @codeCoverageIgnoreEnd - + collect(Config::getArray('hyde.navigation.custom', []))->each(function (NavigationItem $item): void { // Since these were added explicitly by the user, we can assume they should always be shown $this->items->push($item); }); From 7188b38d998eeaa949e0e1dda367a6e1f2b0eb7b Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 16:13:37 +0200 Subject: [PATCH 013/232] Breaking: The custom navigation item config now uses array inputs --- .../Navigation/NavigationMenuGenerator.php | 4 +- .../tests/Feature/NavigationMenuTest.php | 45 ++++++++++++++++--- 2 files changed, 40 insertions(+), 9 deletions(-) diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php b/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php index d2bd01921f8..c9a0ad405d6 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php @@ -81,9 +81,9 @@ protected function generate(): void $this->items->push(NavigationItem::create(DocumentationPage::home())); } } else { - collect(Config::getArray('hyde.navigation.custom', []))->each(function (NavigationItem $item): void { + collect(Config::getArray('hyde.navigation.custom', []))->each(function (array $item): void { // Since these were added explicitly by the user, we can assume they should always be shown - $this->items->push($item); + $this->items->push(NavigationItem::create($item['destination'], $item['label'] ?? null, $item['priority'] ?? null)); }); } } diff --git a/packages/framework/tests/Feature/NavigationMenuTest.php b/packages/framework/tests/Feature/NavigationMenuTest.php index 7f6cb8b3ac7..3c6876935c3 100644 --- a/packages/framework/tests/Feature/NavigationMenuTest.php +++ b/packages/framework/tests/Feature/NavigationMenuTest.php @@ -5,6 +5,7 @@ namespace Hyde\Framework\Testing\Feature; use Hyde\Hyde; +use Hyde\Facades\Navigation; use Hyde\Support\Models\Route; use Hyde\Foundation\Facades\Routes; use Hyde\Framework\Features\Navigation\NavigationGroup; @@ -91,9 +92,39 @@ public function testIsSortedAutomaticallyWhenUsingNavigationMenuCreate() $this->assertEquals($expected, $menu->getItems()); } + public function testCanAddCustomLinksInConfig() + { + config(['hyde.navigation.custom' => [Navigation::item('foo', 'Foo')]]); + + $menu = $this->createNavigationMenu(); + + $expected = collect([ + NavigationItem::create(Routes::get('index')), + NavigationItem::create('foo', 'Foo'), + ]); + + $this->assertCount(count($expected), $menu->getItems()); + $this->assertEquals($expected, $menu->getItems()); + } + + public function testCanAddCustomLinksInConfigAsArray() + { + config(['hyde.navigation.custom' => [['destination' => 'foo', 'label' => 'Foo']]]); + + $menu = $this->createNavigationMenu(); + + $expected = collect([ + NavigationItem::create(Routes::get('index')), + NavigationItem::create('foo', 'Foo'), + ]); + + $this->assertCount(count($expected), $menu->getItems()); + $this->assertEquals($expected, $menu->getItems()); + } + public function testExternalLinkCanBeAddedInConfig() { - config(['hyde.navigation.custom' => [NavigationItem::create('https://example.com', 'foo')]]); + config(['hyde.navigation.custom' => [Navigation::item('https://example.com', 'foo')]]); $menu = $this->createNavigationMenu(); @@ -108,7 +139,7 @@ public function testExternalLinkCanBeAddedInConfig() public function testPathLinkCanBeAddedInConfig() { - config(['hyde.navigation.custom' => [NavigationItem::create('foo', 'foo')]]); + config(['hyde.navigation.custom' => [Navigation::item('foo', 'foo')]]); $menu = $this->createNavigationMenu(); @@ -124,8 +155,8 @@ public function testPathLinkCanBeAddedInConfig() public function testDuplicatesAreNotRemovedWhenAddingInConfig() { config(['hyde.navigation.custom' => [ - NavigationItem::create('foo', 'foo'), - NavigationItem::create('foo', 'foo'), + Navigation::item('foo', 'foo'), + Navigation::item('foo', 'foo'), ]]); $menu = $this->createNavigationMenu(); @@ -143,8 +174,8 @@ public function testDuplicatesAreNotRemovedWhenAddingInConfig() public function testDuplicatesAreNotRemovedWhenAddingInConfigRegardlessOfDestination() { config(['hyde.navigation.custom' => [ - NavigationItem::create('foo', 'foo'), - NavigationItem::create('bar', 'foo'), + Navigation::item('foo', 'foo'), + Navigation::item('bar', 'foo'), ]]); $menu = $this->createNavigationMenu(); @@ -163,7 +194,7 @@ public function testConfigItemsTakePrecedenceOverGeneratedItems() { $this->file('_pages/foo.md'); - config(['hyde.navigation.custom' => [NavigationItem::create('bar', 'Foo')]]); + config(['hyde.navigation.custom' => [Navigation::item('bar', 'Foo')]]); $menu = $this->createNavigationMenu(); From 8142e7f8e28d0b1d2d3478c9282708d2a20a90f7 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 16:37:37 +0200 Subject: [PATCH 014/232] Update Yaml configuration loader to parse navigation items --- .../Internal/LoadYamlConfiguration.php | 16 ++++++++ .../Feature/YamlConfigurationFeatureTest.php | 38 +++++++++++++++++++ 2 files changed, 54 insertions(+) diff --git a/packages/framework/src/Foundation/Internal/LoadYamlConfiguration.php b/packages/framework/src/Foundation/Internal/LoadYamlConfiguration.php index 6a1cda350e7..8ff06c9998d 100644 --- a/packages/framework/src/Foundation/Internal/LoadYamlConfiguration.php +++ b/packages/framework/src/Foundation/Internal/LoadYamlConfiguration.php @@ -8,6 +8,7 @@ use Illuminate\Support\Arr; use Hyde\Foundation\Application; use Illuminate\Config\Repository; +use Hyde\Framework\Features\Navigation\NavigationItem; use Hyde\Framework\Features\Blogging\Models\PostAuthor; use Hyde\Framework\Exceptions\InvalidConfigurationException; @@ -50,6 +51,10 @@ protected function mergeParsedConfiguration(): void $data['authors'] = $this->parseAuthors($data['authors']); } + if ($namespace === 'hyde' && isset($data['navigation']['custom'])) { + $data['navigation']['custom'] = $this->parseNavigationItems($data['navigation']['custom']); + } + $this->mergeConfiguration($namespace, Arr::undot($data ?: [])); } } @@ -76,4 +81,15 @@ protected function parseAuthors(array $authors): array } }); } + + /** + * @param array $items Where destination is a route key or an external URI. + * @return array<\Hyde\Framework\Features\Navigation\NavigationItem> + */ + protected function parseNavigationItems(array $items): array + { + return Arr::map($items, function (array $item): NavigationItem { + return NavigationItem::create($item['destination'], $item['label'], $item['priority']); + }); + } } diff --git a/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php b/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php index efb6baeb5c6..cf9c17bf423 100644 --- a/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php +++ b/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php @@ -6,6 +6,7 @@ use Hyde\Testing\TestCase; use Illuminate\Support\Env; +use Hyde\Framework\Features\Navigation\NavigationItem; use Hyde\Framework\Features\Blogging\Models\PostAuthor; use Hyde\Framework\Exceptions\InvalidConfigurationException; @@ -456,6 +457,43 @@ public function testTypeErrorsInAuthorsYamlConfigAreRethrownMoreHelpfully() unlink('hyde.yml'); } + public function testCanSetCustomNavigationItemsInTheYamlConfig() + { + $this->file('hyde.yml', <<<'YAML' + hyde: + navigation: + custom: + - destination: 'https://example.com' + label: 'Example' + priority: 100 + - destination: 'about' + label: 'About Us' + priority: 200 + - destination: 'contact' + label: 'Contact' + priority: 300 + YAML); + + $this->runBootstrappers(); + + $navigationItems = config('hyde.navigation.custom'); + + $this->assertCount(3, $navigationItems); + $this->assertContainsOnlyInstancesOf(NavigationItem::class, $navigationItems); + + $this->assertSame('https://example.com', $navigationItems[0]->destination); + $this->assertSame('Example', $navigationItems[0]->label); + $this->assertSame(100, $navigationItems[0]->priority); + + $this->assertSame('about', $navigationItems[1]->destination); + $this->assertSame('About Us', $navigationItems[1]->label); + $this->assertSame(200, $navigationItems[1]->priority); + + $this->assertSame('contact', $navigationItems[2]->destination); + $this->assertSame('Contact', $navigationItems[2]->label); + $this->assertSame(300, $navigationItems[2]->priority); + } + protected function runBootstrappers(?array $withMergedConfig = null): void { $this->refreshApplication(); From af201607e83f3b98872462670a3df7f024b33e31 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 16:43:40 +0200 Subject: [PATCH 015/232] Loader must create array structures as routes are not available yet This is essentially no-op now so we may not need it --- .../Internal/LoadYamlConfiguration.php | 5 +- .../Feature/YamlConfigurationFeatureTest.php | 47 ++++++++++++++----- 2 files changed, 39 insertions(+), 13 deletions(-) diff --git a/packages/framework/src/Foundation/Internal/LoadYamlConfiguration.php b/packages/framework/src/Foundation/Internal/LoadYamlConfiguration.php index 8ff06c9998d..8b1fa0b5dc9 100644 --- a/packages/framework/src/Foundation/Internal/LoadYamlConfiguration.php +++ b/packages/framework/src/Foundation/Internal/LoadYamlConfiguration.php @@ -6,6 +6,7 @@ use Throwable; use Illuminate\Support\Arr; +use Hyde\Facades\Navigation; use Hyde\Foundation\Application; use Illuminate\Config\Repository; use Hyde\Framework\Features\Navigation\NavigationItem; @@ -88,8 +89,8 @@ protected function parseAuthors(array $authors): array */ protected function parseNavigationItems(array $items): array { - return Arr::map($items, function (array $item): NavigationItem { - return NavigationItem::create($item['destination'], $item['label'], $item['priority']); + return Arr::map($items, function (array $item): array { + return Navigation::item($item['destination'], $item['label'], $item['priority']); }); } } diff --git a/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php b/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php index cf9c17bf423..b9de9681679 100644 --- a/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php +++ b/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php @@ -8,7 +8,9 @@ use Illuminate\Support\Env; use Hyde\Framework\Features\Navigation\NavigationItem; use Hyde\Framework\Features\Blogging\Models\PostAuthor; +use Hyde\Framework\Features\Navigation\MainNavigationMenu; use Hyde\Framework\Exceptions\InvalidConfigurationException; +use Hyde\Framework\Features\Navigation\NavigationMenuGenerator; /** * Test the Yaml configuration feature. @@ -476,22 +478,45 @@ public function testCanSetCustomNavigationItemsInTheYamlConfig() $this->runBootstrappers(); - $navigationItems = config('hyde.navigation.custom'); + $configItems = config('hyde.navigation.custom'); - $this->assertCount(3, $navigationItems); + $this->assertSame([ + [ + 'destination' => 'https://example.com', + 'label' => 'Example', + 'priority' => 100, + ], [ + 'destination' => 'about', + 'label' => 'About Us', + 'priority' => 200, + ], [ + 'destination' => 'contact', + 'label' => 'Contact', + 'priority' => 300, + ], + ], $configItems); + + /** @var NavigationItem[] $navigationItems */ + $navigationItems = NavigationMenuGenerator::handle(MainNavigationMenu::class)->getItems()->all(); + + $this->assertCount(4, $navigationItems); $this->assertContainsOnlyInstancesOf(NavigationItem::class, $navigationItems); - $this->assertSame('https://example.com', $navigationItems[0]->destination); - $this->assertSame('Example', $navigationItems[0]->label); - $this->assertSame(100, $navigationItems[0]->priority); + $this->assertSame('index.html', $navigationItems[0]->getLink()); + $this->assertSame('Home', $navigationItems[0]->getLabel()); + $this->assertSame(0, $navigationItems[0]->getPriority()); + + $this->assertSame('https://example.com', $navigationItems[1]->getLink()); + $this->assertSame('Example', $navigationItems[1]->getLabel()); + $this->assertSame(100, $navigationItems[1]->getPriority()); - $this->assertSame('about', $navigationItems[1]->destination); - $this->assertSame('About Us', $navigationItems[1]->label); - $this->assertSame(200, $navigationItems[1]->priority); + $this->assertSame('about', $navigationItems[2]->getLink()); + $this->assertSame('About Us', $navigationItems[2]->getLabel()); + $this->assertSame(200, $navigationItems[2]->getPriority()); - $this->assertSame('contact', $navigationItems[2]->destination); - $this->assertSame('Contact', $navigationItems[2]->label); - $this->assertSame(300, $navigationItems[2]->priority); + $this->assertSame('contact', $navigationItems[3]->getLink()); + $this->assertSame('Contact', $navigationItems[3]->getLabel()); + $this->assertSame(300, $navigationItems[3]->getPriority()); } protected function runBootstrappers(?array $withMergedConfig = null): void From 01f36306263c2661a90de67142cf7b6a7800c4f0 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 16:44:05 +0200 Subject: [PATCH 016/232] Clean up code --- .../src/Foundation/Internal/LoadYamlConfiguration.php | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/framework/src/Foundation/Internal/LoadYamlConfiguration.php b/packages/framework/src/Foundation/Internal/LoadYamlConfiguration.php index 8b1fa0b5dc9..18413688ebe 100644 --- a/packages/framework/src/Foundation/Internal/LoadYamlConfiguration.php +++ b/packages/framework/src/Foundation/Internal/LoadYamlConfiguration.php @@ -9,10 +9,10 @@ use Hyde\Facades\Navigation; use Hyde\Foundation\Application; use Illuminate\Config\Repository; -use Hyde\Framework\Features\Navigation\NavigationItem; use Hyde\Framework\Features\Blogging\Models\PostAuthor; use Hyde\Framework\Exceptions\InvalidConfigurationException; +use function tap; use function array_merge; /** @@ -84,7 +84,7 @@ protected function parseAuthors(array $authors): array } /** - * @param array $items Where destination is a route key or an external URI. + * @param array $items Where destination is a route key or an external URI. * @return array<\Hyde\Framework\Features\Navigation\NavigationItem> */ protected function parseNavigationItems(array $items): array From 0724ac00e49919d139026f00291e92cc16ff65d9 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 17:04:04 +0200 Subject: [PATCH 017/232] Test navigation items in the YAML config can be resolved to routes --- .../Feature/YamlConfigurationFeatureTest.php | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php b/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php index b9de9681679..8457f163fb7 100644 --- a/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php +++ b/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php @@ -4,8 +4,10 @@ namespace Hyde\Framework\Testing\Feature; +use Hyde\Hyde; use Hyde\Testing\TestCase; use Illuminate\Support\Env; +use Hyde\Pages\MarkdownPage; use Hyde\Framework\Features\Navigation\NavigationItem; use Hyde\Framework\Features\Blogging\Models\PostAuthor; use Hyde\Framework\Features\Navigation\MainNavigationMenu; @@ -519,6 +521,32 @@ public function testCanSetCustomNavigationItemsInTheYamlConfig() $this->assertSame(300, $navigationItems[3]->getPriority()); } + public function testNavigationItemsInTheYamlConfigCanBeResolvedToRoutes() + { + $this->file('hyde.yml', <<<'YAML' + hyde: + navigation: + custom: + - destination: 'about' + YAML); + + $this->runBootstrappers(); + + Hyde::routes()->addRoute((new MarkdownPage('about', ['title' => 'About Us', 'navigation' => ['priority' => 250]]))->getRoute()); + + $navigationItems = NavigationMenuGenerator::handle(MainNavigationMenu::class)->getItems()->all(); + + // The route is already automatically added to the navigation menu, so we'll have two of it. + $this->assertCount(3, $navigationItems); + $this->assertContainsOnlyInstancesOf(NavigationItem::class, $navigationItems); + + $this->assertEquals($navigationItems[1], $navigationItems[2]); + + $this->assertSame('about.html', $navigationItems[1]->getLink()); + $this->assertSame('About Us', $navigationItems[1]->getLabel()); + $this->assertSame(250, $navigationItems[1]->getPriority()); + } + protected function runBootstrappers(?array $withMergedConfig = null): void { $this->refreshApplication(); From 600dfd5e325d73c0d8ebb17158561ce4eda17603 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 17:09:01 +0200 Subject: [PATCH 018/232] Add null fallbacks --- .../Internal/LoadYamlConfiguration.php | 2 +- .../Feature/YamlConfigurationFeatureTest.php | 36 +++++++++++++++++++ 2 files changed, 37 insertions(+), 1 deletion(-) diff --git a/packages/framework/src/Foundation/Internal/LoadYamlConfiguration.php b/packages/framework/src/Foundation/Internal/LoadYamlConfiguration.php index 18413688ebe..d8aa49f44d8 100644 --- a/packages/framework/src/Foundation/Internal/LoadYamlConfiguration.php +++ b/packages/framework/src/Foundation/Internal/LoadYamlConfiguration.php @@ -90,7 +90,7 @@ protected function parseAuthors(array $authors): array protected function parseNavigationItems(array $items): array { return Arr::map($items, function (array $item): array { - return Navigation::item($item['destination'], $item['label'], $item['priority']); + return Navigation::item($item['destination'], $item['label'] ?? null, $item['priority'] ?? null); }); } } diff --git a/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php b/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php index 8457f163fb7..c7cf48962f2 100644 --- a/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php +++ b/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php @@ -521,6 +521,42 @@ public function testCanSetCustomNavigationItemsInTheYamlConfig() $this->assertSame(300, $navigationItems[3]->getPriority()); } + public function testOnlyNeedToAddDestinationToYamlConfiguredNavigationItems() + { + $this->file('hyde.yml', <<<'YAML' + hyde: + navigation: + custom: + - destination: 'about.html' + YAML); + + $this->runBootstrappers(); + + $configItems = config('hyde.navigation.custom'); + + $this->assertSame([ + [ + 'destination' => 'about.html', + 'label' => null, + 'priority' => null, + ], + ], $configItems); + + /** @var NavigationItem[] $navigationItems */ + $navigationItems = NavigationMenuGenerator::handle(MainNavigationMenu::class)->getItems()->all(); + + $this->assertCount(2, $navigationItems); + $this->assertContainsOnlyInstancesOf(NavigationItem::class, $navigationItems); + + $this->assertSame('index.html', $navigationItems[0]->getLink()); + $this->assertSame('Home', $navigationItems[0]->getLabel()); + $this->assertSame(0, $navigationItems[0]->getPriority()); + + $this->assertSame('about.html', $navigationItems[1]->getLink()); + $this->assertSame('about.html', $navigationItems[1]->getLabel()); // The label is automatically set to the destination. + $this->assertSame(500, $navigationItems[1]->getPriority()); + } + public function testNavigationItemsInTheYamlConfigCanBeResolvedToRoutes() { $this->file('hyde.yml', <<<'YAML' From 9af37e1aceee37d834ee8d88dc9efdafd9f53645 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 17:14:32 +0200 Subject: [PATCH 019/232] Rethrow exceptions more helpfully --- .../Internal/LoadYamlConfiguration.php | 9 ++++- .../Feature/YamlConfigurationFeatureTest.php | 36 +++++++++++++++++++ 2 files changed, 44 insertions(+), 1 deletion(-) diff --git a/packages/framework/src/Foundation/Internal/LoadYamlConfiguration.php b/packages/framework/src/Foundation/Internal/LoadYamlConfiguration.php index d8aa49f44d8..d3872cc5e55 100644 --- a/packages/framework/src/Foundation/Internal/LoadYamlConfiguration.php +++ b/packages/framework/src/Foundation/Internal/LoadYamlConfiguration.php @@ -90,7 +90,14 @@ protected function parseAuthors(array $authors): array protected function parseNavigationItems(array $items): array { return Arr::map($items, function (array $item): array { - return Navigation::item($item['destination'], $item['label'] ?? null, $item['priority'] ?? null); + try { + return Navigation::item($item['destination'], $item['label'] ?? null, $item['priority'] ?? null); + } catch (Throwable $exception) { + throw new InvalidConfigurationException( + 'Invalid navigation item configuration detected in the YAML config file. Please double check the syntax.', + previous: $exception + ); + } }); } } diff --git a/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php b/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php index c7cf48962f2..a3ee6809eec 100644 --- a/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php +++ b/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php @@ -557,6 +557,42 @@ public function testOnlyNeedToAddDestinationToYamlConfiguredNavigationItems() $this->assertSame(500, $navigationItems[1]->getPriority()); } + public function testTypeErrorsInNavigationYamlConfigAreRethrownMoreHelpfully() + { + file_put_contents('hyde.yml', <<<'YAML' + hyde: + navigation: + custom: + - destination: false + YAML); + + try { + $this->runBootstrappers(); + } catch (InvalidConfigurationException $exception) { + $this->assertSame('Invalid navigation item configuration detected in the YAML config file. Please double check the syntax.', $exception->getMessage()); + } + + unlink('hyde.yml'); + } + + public function testMustAddDestinationToYamlConfiguredNavigationItems() + { + file_put_contents('hyde.yml', <<<'YAML' + hyde: + navigation: + custom: + - label: 'About Us' + YAML); + + try { + $this->runBootstrappers(); + } catch (InvalidConfigurationException $exception) { + $this->assertSame('Invalid navigation item configuration detected in the YAML config file. Please double check the syntax.', $exception->getMessage()); + } + + unlink('hyde.yml'); + } + public function testNavigationItemsInTheYamlConfigCanBeResolvedToRoutes() { $this->file('hyde.yml', <<<'YAML' From 4e1fbf933b85029bd6c4d63fb62f66a426aaacd2 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 17:14:47 +0200 Subject: [PATCH 020/232] Reorder tests --- .../Feature/YamlConfigurationFeatureTest.php | 52 +++++++++---------- 1 file changed, 26 insertions(+), 26 deletions(-) diff --git a/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php b/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php index a3ee6809eec..bf99165f5d7 100644 --- a/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php +++ b/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php @@ -557,6 +557,32 @@ public function testOnlyNeedToAddDestinationToYamlConfiguredNavigationItems() $this->assertSame(500, $navigationItems[1]->getPriority()); } + public function testNavigationItemsInTheYamlConfigCanBeResolvedToRoutes() + { + $this->file('hyde.yml', <<<'YAML' + hyde: + navigation: + custom: + - destination: 'about' + YAML); + + $this->runBootstrappers(); + + Hyde::routes()->addRoute((new MarkdownPage('about', ['title' => 'About Us', 'navigation' => ['priority' => 250]]))->getRoute()); + + $navigationItems = NavigationMenuGenerator::handle(MainNavigationMenu::class)->getItems()->all(); + + // The route is already automatically added to the navigation menu, so we'll have two of it. + $this->assertCount(3, $navigationItems); + $this->assertContainsOnlyInstancesOf(NavigationItem::class, $navigationItems); + + $this->assertEquals($navigationItems[1], $navigationItems[2]); + + $this->assertSame('about.html', $navigationItems[1]->getLink()); + $this->assertSame('About Us', $navigationItems[1]->getLabel()); + $this->assertSame(250, $navigationItems[1]->getPriority()); + } + public function testTypeErrorsInNavigationYamlConfigAreRethrownMoreHelpfully() { file_put_contents('hyde.yml', <<<'YAML' @@ -593,32 +619,6 @@ public function testMustAddDestinationToYamlConfiguredNavigationItems() unlink('hyde.yml'); } - public function testNavigationItemsInTheYamlConfigCanBeResolvedToRoutes() - { - $this->file('hyde.yml', <<<'YAML' - hyde: - navigation: - custom: - - destination: 'about' - YAML); - - $this->runBootstrappers(); - - Hyde::routes()->addRoute((new MarkdownPage('about', ['title' => 'About Us', 'navigation' => ['priority' => 250]]))->getRoute()); - - $navigationItems = NavigationMenuGenerator::handle(MainNavigationMenu::class)->getItems()->all(); - - // The route is already automatically added to the navigation menu, so we'll have two of it. - $this->assertCount(3, $navigationItems); - $this->assertContainsOnlyInstancesOf(NavigationItem::class, $navigationItems); - - $this->assertEquals($navigationItems[1], $navigationItems[2]); - - $this->assertSame('about.html', $navigationItems[1]->getLink()); - $this->assertSame('About Us', $navigationItems[1]->getLabel()); - $this->assertSame(250, $navigationItems[1]->getPriority()); - } - protected function runBootstrappers(?array $withMergedConfig = null): void { $this->refreshApplication(); From 44573ddb8a9ad48e2f2a2c652365b91a60e9bab7 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 17:19:46 +0200 Subject: [PATCH 021/232] Mark method as experimental --- .../framework/src/Foundation/Internal/LoadYamlConfiguration.php | 2 ++ 1 file changed, 2 insertions(+) diff --git a/packages/framework/src/Foundation/Internal/LoadYamlConfiguration.php b/packages/framework/src/Foundation/Internal/LoadYamlConfiguration.php index d3872cc5e55..ed5cf8adef8 100644 --- a/packages/framework/src/Foundation/Internal/LoadYamlConfiguration.php +++ b/packages/framework/src/Foundation/Internal/LoadYamlConfiguration.php @@ -84,6 +84,8 @@ protected function parseAuthors(array $authors): array } /** + * @experimental Since the main configuration also uses arrays, the only thing this method really does is to rethrow any exceptions. + * * @param array $items Where destination is a route key or an external URI. * @return array<\Hyde\Framework\Features\Navigation\NavigationItem> */ From 74240c061285a4893feafd2b76461644cb933813 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 17:20:10 +0200 Subject: [PATCH 022/232] Update type annotation to match actual values --- .../framework/src/Foundation/Internal/LoadYamlConfiguration.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/framework/src/Foundation/Internal/LoadYamlConfiguration.php b/packages/framework/src/Foundation/Internal/LoadYamlConfiguration.php index ed5cf8adef8..52a80feb8a4 100644 --- a/packages/framework/src/Foundation/Internal/LoadYamlConfiguration.php +++ b/packages/framework/src/Foundation/Internal/LoadYamlConfiguration.php @@ -87,7 +87,7 @@ protected function parseAuthors(array $authors): array * @experimental Since the main configuration also uses arrays, the only thing this method really does is to rethrow any exceptions. * * @param array $items Where destination is a route key or an external URI. - * @return array<\Hyde\Framework\Features\Navigation\NavigationItem> + * @return array */ protected function parseNavigationItems(array $items): array { From a6c5ba09893f110f3a3d2886d661a36eb8466cde Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 17:28:31 +0200 Subject: [PATCH 023/232] Test extra YAML navigation item fields are ignored --- .../Feature/YamlConfigurationFeatureTest.php | 31 +++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php b/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php index bf99165f5d7..c9cf81ffadf 100644 --- a/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php +++ b/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php @@ -583,6 +583,37 @@ public function testNavigationItemsInTheYamlConfigCanBeResolvedToRoutes() $this->assertSame(250, $navigationItems[1]->getPriority()); } + public function testExtraYamlNavigationItemFieldsAreIgnored() + { + $this->file('hyde.yml', <<<'YAML' + hyde: + navigation: + custom: + - destination: 'about' + extra: 'field' + YAML); + + $this->runBootstrappers(); + + $configItems = config('hyde.navigation.custom'); + + $this->assertSame([ + [ + 'destination' => 'about', + 'label' => null, + 'priority' => null, + ], + ], $configItems); + + $navigationItems = NavigationMenuGenerator::handle(MainNavigationMenu::class)->getItems()->all(); + + $this->assertCount(2, $navigationItems); + + $this->assertSame('about', $navigationItems[1]->getLink()); + $this->assertSame('about', $navigationItems[1]->getLabel()); + $this->assertSame(500, $navigationItems[1]->getPriority()); + } + public function testTypeErrorsInNavigationYamlConfigAreRethrownMoreHelpfully() { file_put_contents('hyde.yml', <<<'YAML' From c773393387e2515469cf60f726b2bfe54ed9f3db Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 17:29:32 +0200 Subject: [PATCH 024/232] Revert "Test extra YAML navigation item fields are ignored" This reverts commit a6c5ba09893f110f3a3d2886d661a36eb8466cde. --- .../Feature/YamlConfigurationFeatureTest.php | 31 ------------------- 1 file changed, 31 deletions(-) diff --git a/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php b/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php index c9cf81ffadf..bf99165f5d7 100644 --- a/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php +++ b/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php @@ -583,37 +583,6 @@ public function testNavigationItemsInTheYamlConfigCanBeResolvedToRoutes() $this->assertSame(250, $navigationItems[1]->getPriority()); } - public function testExtraYamlNavigationItemFieldsAreIgnored() - { - $this->file('hyde.yml', <<<'YAML' - hyde: - navigation: - custom: - - destination: 'about' - extra: 'field' - YAML); - - $this->runBootstrappers(); - - $configItems = config('hyde.navigation.custom'); - - $this->assertSame([ - [ - 'destination' => 'about', - 'label' => null, - 'priority' => null, - ], - ], $configItems); - - $navigationItems = NavigationMenuGenerator::handle(MainNavigationMenu::class)->getItems()->all(); - - $this->assertCount(2, $navigationItems); - - $this->assertSame('about', $navigationItems[1]->getLink()); - $this->assertSame('about', $navigationItems[1]->getLabel()); - $this->assertSame(500, $navigationItems[1]->getPriority()); - } - public function testTypeErrorsInNavigationYamlConfigAreRethrownMoreHelpfully() { file_put_contents('hyde.yml', <<<'YAML' From efea4a447d966e64289169fdff75acf040bf91ea Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 17:31:10 +0200 Subject: [PATCH 025/232] Test adding extra YAML navigation item fields throws an exception --- .../Feature/YamlConfigurationFeatureTest.php | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php b/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php index bf99165f5d7..4d8ea7376a2 100644 --- a/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php +++ b/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php @@ -619,6 +619,25 @@ public function testMustAddDestinationToYamlConfiguredNavigationItems() unlink('hyde.yml'); } + public function testAddingExtraYamlNavigationItemFieldsThrowsAnException() + { + file_put_contents('hyde.yml', <<<'YAML' + hyde: + navigation: + custom: + - destination: 'about' + extra: 'field' + YAML); + + try { + $this->runBootstrappers(); + } catch (InvalidConfigurationException $exception) { + $this->assertSame('Invalid navigation item configuration detected in the YAML config file. Please double check the syntax.', $exception->getMessage()); + } + + unlink('hyde.yml'); + } + protected function runBootstrappers(?array $withMergedConfig = null): void { $this->refreshApplication(); From acb740da8ce20b6b1731a70006071ec12753e1dc Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 17:31:43 +0200 Subject: [PATCH 026/232] Unpack the array directly Reduces extra code, and adds type safety as it will throw when supplied an extra parameter --- .../framework/src/Foundation/Internal/LoadYamlConfiguration.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/framework/src/Foundation/Internal/LoadYamlConfiguration.php b/packages/framework/src/Foundation/Internal/LoadYamlConfiguration.php index 52a80feb8a4..0ac92ab01d0 100644 --- a/packages/framework/src/Foundation/Internal/LoadYamlConfiguration.php +++ b/packages/framework/src/Foundation/Internal/LoadYamlConfiguration.php @@ -93,7 +93,7 @@ protected function parseNavigationItems(array $items): array { return Arr::map($items, function (array $item): array { try { - return Navigation::item($item['destination'], $item['label'] ?? null, $item['priority'] ?? null); + return Navigation::item(...$item); } catch (Throwable $exception) { throw new InvalidConfigurationException( 'Invalid navigation item configuration detected in the YAML config file. Please double check the syntax.', From cc0f567e1ab83f6bab06a009ad7feda6e0ef0c71 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 17:37:30 +0200 Subject: [PATCH 027/232] Clean up if a test failed to clean up after itself --- .../tests/Feature/YamlConfigurationFeatureTest.php | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php b/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php index 4d8ea7376a2..71c1d5c8d24 100644 --- a/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php +++ b/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php @@ -25,6 +25,16 @@ */ class YamlConfigurationFeatureTest extends TestCase { + public static function setUpBeforeClass(): void + { + parent::setUpBeforeClass(); + + if (file_exists('hyde.yml')) { + // Clean up if a test failed to clean up after itself. + unlink('hyde.yml'); + } + } + protected function tearDown(): void { $this->clearEnvVars(); From 709bc3541086a671eb62c20f8fa8adac2c9a7348 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 17:41:29 +0200 Subject: [PATCH 028/232] Update navigation item configuration to use the new facade --- config/hyde.php | 3 ++- packages/framework/config/hyde.php | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/config/hyde.php b/config/hyde.php index 0898d2a80f4..2cbe97e8047 100644 --- a/config/hyde.php +++ b/config/hyde.php @@ -25,6 +25,7 @@ use Hyde\Facades\Author; use Hyde\Facades\Meta; use Hyde\Enums\Feature; +use Hyde\Facades\Navigation; return [ @@ -358,7 +359,7 @@ // To get started quickly, you can uncomment the defaults here. // See the documentation link above for more information. 'custom' => [ - // NavigationItem::create('https://github.com/hydephp/hyde', 'GitHub', 200), + // Navigation::item('https://github.com/hydephp/hyde', 'GitHub', 200), ], // How should pages in subdirectories be displayed in the menu? diff --git a/packages/framework/config/hyde.php b/packages/framework/config/hyde.php index 0898d2a80f4..2cbe97e8047 100644 --- a/packages/framework/config/hyde.php +++ b/packages/framework/config/hyde.php @@ -25,6 +25,7 @@ use Hyde\Facades\Author; use Hyde\Facades\Meta; use Hyde\Enums\Feature; +use Hyde\Facades\Navigation; return [ @@ -358,7 +359,7 @@ // To get started quickly, you can uncomment the defaults here. // See the documentation link above for more information. 'custom' => [ - // NavigationItem::create('https://github.com/hydephp/hyde', 'GitHub', 200), + // Navigation::item('https://github.com/hydephp/hyde', 'GitHub', 200), ], // How should pages in subdirectories be displayed in the menu? From c06a475dfde5f8bd0ba40f781b21f3a5dc8c902b Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 17:50:05 +0200 Subject: [PATCH 029/232] Breaking: Rename `subdirectories` option to `subdirectory_display` Breaking: Renames the `hyde.navigation.subdirectories` option to `hyde.navigation.subdirectory_display` to make its usage much clearer. --- config/hyde.php | 2 +- docs/digging-deeper/navigation.md | 4 ++-- packages/framework/config/hyde.php | 2 +- .../Factories/NavigationDataFactory.php | 2 +- .../Navigation/NavigationMenuGenerator.php | 2 +- .../AutomaticNavigationConfigurationsTest.php | 22 +++++++++---------- .../framework/tests/Feature/HydePageTest.php | 6 ++--- .../tests/Feature/NavigationMenuTest.php | 6 ++--- .../NumericalPageOrderingHelperTest.php | 2 +- .../Unit/NavigationDataFactoryUnitTest.php | 4 ++-- ...veLinksAcrossPagesRetainsIntegrityTest.php | 2 +- .../Unit/Views/NavigationHtmlLayoutsTest.php | 2 +- .../Unit/Views/NavigationMenuViewTest.php | 4 ++-- 13 files changed, 30 insertions(+), 30 deletions(-) diff --git a/config/hyde.php b/config/hyde.php index 2cbe97e8047..8d9c62357c5 100644 --- a/config/hyde.php +++ b/config/hyde.php @@ -364,7 +364,7 @@ // How should pages in subdirectories be displayed in the menu? // You can choose between 'dropdown', 'flat', and 'hidden'. - 'subdirectories' => 'hidden', + 'subdirectory_display' => 'hidden', ], /* diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index efbd049babd..3ff1d9d16b9 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -259,7 +259,7 @@ Within the Hyde config you can configure how subdirectories should be displayed ```php // filepath config/hyde.php 'navigation' => [ - 'subdirectories' => 'dropdown' + 'subdirectory_display' => 'dropdown' ] ``` @@ -279,7 +279,7 @@ For pages that can be in the main site menu, this feature needs to be enabled in // filepath config/hyde.php 'navigation' => [ - 'subdirectories' => 'dropdown', + 'subdirectory_display' => 'dropdown', ], ``` diff --git a/packages/framework/config/hyde.php b/packages/framework/config/hyde.php index 2cbe97e8047..8d9c62357c5 100644 --- a/packages/framework/config/hyde.php +++ b/packages/framework/config/hyde.php @@ -364,7 +364,7 @@ // How should pages in subdirectories be displayed in the menu? // You can choose between 'dropdown', 'flat', and 'hidden'. - 'subdirectories' => 'hidden', + 'subdirectory_display' => 'hidden', ], /* diff --git a/packages/framework/src/Framework/Factories/NavigationDataFactory.php b/packages/framework/src/Framework/Factories/NavigationDataFactory.php index b7b331e6db6..61526679f33 100644 --- a/packages/framework/src/Framework/Factories/NavigationDataFactory.php +++ b/packages/framework/src/Framework/Factories/NavigationDataFactory.php @@ -274,7 +274,7 @@ private function getSubdirectoryName(): string protected function getSubdirectoryConfiguration(): string { - return Config::getString('hyde.navigation.subdirectories', 'hidden'); + return Config::getString('hyde.navigation.subdirectory_display', 'hidden'); } /** @param class-string<\Hyde\Pages\Concerns\HydePage> $class */ diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php b/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php index c9a0ad405d6..eae219d2f53 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php @@ -96,7 +96,7 @@ protected function usesGroups(): bool return $this->routes->first(fn (Route $route): bool => filled($route->getPage()->navigationMenuGroup())) !== null; } else { - return Config::getString('hyde.navigation.subdirectories', 'hidden') === 'dropdown'; + return Config::getString('hyde.navigation.subdirectory_display', 'hidden') === 'dropdown'; } } diff --git a/packages/framework/tests/Feature/AutomaticNavigationConfigurationsTest.php b/packages/framework/tests/Feature/AutomaticNavigationConfigurationsTest.php index c5763cf2e89..ab6939903ba 100644 --- a/packages/framework/tests/Feature/AutomaticNavigationConfigurationsTest.php +++ b/packages/framework/tests/Feature/AutomaticNavigationConfigurationsTest.php @@ -412,7 +412,7 @@ public function testMainNavigationDropdownLabelsCanBeSetInConfig() public function testMainNavigationAutomaticSubdirectoryDropdownLabelsCanBeSetInConfig() { - config(['hyde.navigation.subdirectories' => 'dropdown']); + config(['hyde.navigation.subdirectory_display' => 'dropdown']); config(['hyde.navigation.labels' => ['hello' => 'World']]); $this->assertMenuEquals(['World'], [ @@ -444,7 +444,7 @@ public function testPagesInSubdirectoriesAreNotAddedToNavigation() public function testPagesInSubdirectoriesAreAddedToNavigationWhenNavigationSubdirectoriesIsSetToFlat() { - config(['hyde.navigation.subdirectories' => 'flat']); + config(['hyde.navigation.subdirectory_display' => 'flat']); $this->assertMenuEquals(['Foo', 'Bar', 'Baz'], [ new MarkdownPage('about/foo'), @@ -455,7 +455,7 @@ public function testPagesInSubdirectoriesAreAddedToNavigationWhenNavigationSubdi public function testPagesInSubdirectoriesAreAddedAsDropdownsWhenNavigationSubdirectoriesIsSetToDropdown() { - config(['hyde.navigation.subdirectories' => 'dropdown']); + config(['hyde.navigation.subdirectory_display' => 'dropdown']); $this->assertMenuEquals([ ['label' => 'About', 'children' => ['Foo', 'Bar', 'Baz']], @@ -502,7 +502,7 @@ public function testMainNavigationMenuItemsWithSameLabelButDifferentGroupsAreNot public function testMainNavigationMenuDropdownItemsWithSameLabelButDifferentGroupsAreNotFiltered() { - config(['hyde.navigation.subdirectories' => 'dropdown']); + config(['hyde.navigation.subdirectory_display' => 'dropdown']); $this->assertMenuEquals([ ['label' => 'One', 'children' => ['Foo']], @@ -515,7 +515,7 @@ public function testMainNavigationMenuDropdownItemsWithSameLabelButDifferentGrou public function testMainNavigationMenuAutomaticDropdownItemsWithSameLabelButDifferentGroupsAreNotFiltered() { - config(['hyde.navigation.subdirectories' => 'dropdown']); + config(['hyde.navigation.subdirectory_display' => 'dropdown']); $this->assertMenuEquals([ ['label' => 'One', 'children' => ['Foo']], @@ -532,7 +532,7 @@ public function testConflictingSubdirectoryAndFrontMatterDropdownConfigurationGi // we run into a conflicting state where we don't know what the user intended. We solve this by giving // precedence to the subdirectory configuration. This is opinionated, but allows for good grouping. - config(['hyde.navigation.subdirectories' => 'dropdown']); + config(['hyde.navigation.subdirectory_display' => 'dropdown']); $this->assertMenuEquals([ ['label' => 'Foo', 'children' => ['Child']], @@ -543,7 +543,7 @@ public function testConflictingSubdirectoryAndFrontMatterDropdownConfigurationGi public function testCanMixSubdirectoryDropdownsWithFrontMatterDropdowns() { - config(['hyde.navigation.subdirectories' => 'dropdown']); + config(['hyde.navigation.subdirectory_display' => 'dropdown']); $this->assertMenuEquals([ ['label' => 'Foo', 'children' => ['Bar', 'Baz']], @@ -555,7 +555,7 @@ public function testCanMixSubdirectoryDropdownsWithFrontMatterDropdowns() public function testMainMenuAutomaticDropdownLabelsCanBeSetInConfig() { - config(['hyde.navigation.subdirectories' => 'dropdown']); + config(['hyde.navigation.subdirectory_display' => 'dropdown']); config(['hyde.navigation.labels' => ['foo' => 'Bar']]); $this->assertMenuEquals([ @@ -1110,7 +1110,7 @@ public function testSidebarCanMixSubdirectoryGroupsWithFrontMatterGroups() public function testMainNavigationDropdownPriorityCanBeSetInConfig() { - config(['hyde.navigation.subdirectories' => 'dropdown']); + config(['hyde.navigation.subdirectory_display' => 'dropdown']); config(['hyde.navigation.order' => ['foo' => 500]]); $this->assertMenuEquals( @@ -1121,7 +1121,7 @@ public function testMainNavigationDropdownPriorityCanBeSetInConfig() public function testMainNavigationDropdownPriorityCanBeSetInConfigUsingDifferingCases() { - config(['hyde.navigation.subdirectories' => 'dropdown']); + config(['hyde.navigation.subdirectory_display' => 'dropdown']); config(['hyde.navigation.order' => ['hello-world' => 500]]); $expected = [['label' => 'Hello World', 'priority' => 500]]; @@ -1176,7 +1176,7 @@ public function testMainMenuNavigationItemCasingUsingFrontMatter() public function testMainMenuNavigationGroupCasing() { - config(['hyde.navigation.subdirectories' => 'dropdown']); + config(['hyde.navigation.subdirectory_display' => 'dropdown']); // When using subdirectory groupings, we try to format them the same way as the page titles diff --git a/packages/framework/tests/Feature/HydePageTest.php b/packages/framework/tests/Feature/HydePageTest.php index c6adb02918f..d9ca0150311 100644 --- a/packages/framework/tests/Feature/HydePageTest.php +++ b/packages/framework/tests/Feature/HydePageTest.php @@ -1176,7 +1176,7 @@ public function testNavigationDataFactoryHidesPageFromNavigationWhenInASubdirect public function testNavigationDataFactoryHidesPageFromNavigationWhenInAAndConfigIsSetToHidden() { - config(['hyde.navigation.subdirectories' => 'hidden']); + config(['hyde.navigation.subdirectory_display' => 'hidden']); $page = MarkdownPage::make('foo/bar'); @@ -1186,7 +1186,7 @@ public function testNavigationDataFactoryHidesPageFromNavigationWhenInAAndConfig public function testNavigationDataFactoryDoesNotHidePageFromNavigationWhenInASubdirectoryAndAllowedInConfiguration() { - config(['hyde.navigation.subdirectories' => 'flat']); + config(['hyde.navigation.subdirectory_display' => 'flat']); $page = MarkdownPage::make('foo/bar'); @@ -1196,7 +1196,7 @@ public function testNavigationDataFactoryDoesNotHidePageFromNavigationWhenInASub public function testNavigationDataFactoryAllowsShowInNavigationAndSetsGroupWhenDropdownIsSelectedInConfig() { - config(['hyde.navigation.subdirectories' => 'dropdown']); + config(['hyde.navigation.subdirectory_display' => 'dropdown']); $page = MarkdownPage::make('foo/bar'); diff --git a/packages/framework/tests/Feature/NavigationMenuTest.php b/packages/framework/tests/Feature/NavigationMenuTest.php index 3c6876935c3..cd9d6f72986 100644 --- a/packages/framework/tests/Feature/NavigationMenuTest.php +++ b/packages/framework/tests/Feature/NavigationMenuTest.php @@ -239,7 +239,7 @@ public function testPagesInSubdirectoriesAreNotAddedToTheNavigationMenu() public function testPagesInSubdirectoriesCanBeAddedToTheNavigationMenuWithConfigFlatSetting() { - config(['hyde.navigation.subdirectories' => 'flat']); + config(['hyde.navigation.subdirectory_display' => 'flat']); $this->directory('_pages/foo'); $this->file('_pages/foo/bar.md'); @@ -256,7 +256,7 @@ public function testPagesInSubdirectoriesCanBeAddedToTheNavigationMenuWithConfig public function testPagesInSubdirectoriesAreNotAddedToTheNavigationMenuWithConfigDropdownSetting() { - config(['hyde.navigation.subdirectories' => 'dropdown']); + config(['hyde.navigation.subdirectory_display' => 'dropdown']); $this->directory('_pages/foo'); $this->file('_pages/foo/bar.md'); @@ -275,7 +275,7 @@ public function testPagesInSubdirectoriesAreNotAddedToTheNavigationMenuWithConfi public function testPagesInDropdownsDoNotGetAddedToTheMainNavigation() { - config(['hyde.navigation.subdirectories' => 'dropdown']); + config(['hyde.navigation.subdirectory_display' => 'dropdown']); Routes::push((new MarkdownPage('foo'))->getRoute()); Routes::push((new MarkdownPage('bar/baz'))->getRoute()); diff --git a/packages/framework/tests/Feature/NumericalPageOrderingHelperTest.php b/packages/framework/tests/Feature/NumericalPageOrderingHelperTest.php index b5b54025ac0..82137389905 100644 --- a/packages/framework/tests/Feature/NumericalPageOrderingHelperTest.php +++ b/packages/framework/tests/Feature/NumericalPageOrderingHelperTest.php @@ -38,7 +38,7 @@ protected function setUp(): void $this->helper = new FilenamePrefixNavigationPriorityTestingHelper($this); - Config::set('hyde.navigation.subdirectories', 'dropdown'); + Config::set('hyde.navigation.subdirectory_display', 'dropdown'); // Todo: Replace kernel with mock class $this->withoutDefaultPages(); diff --git a/packages/framework/tests/Unit/NavigationDataFactoryUnitTest.php b/packages/framework/tests/Unit/NavigationDataFactoryUnitTest.php index eccd5604465..bdbca3f172e 100644 --- a/packages/framework/tests/Unit/NavigationDataFactoryUnitTest.php +++ b/packages/framework/tests/Unit/NavigationDataFactoryUnitTest.php @@ -248,7 +248,7 @@ public function testMakeGroupUsesFrontMatterGroupIfSet() public function testMakeGroupUsesFrontMatterGroupIfSetRegardlessOfSubdirectoryConfiguration() { - self::mockConfig(['hyde.navigation.subdirectories' => 'hidden']); + self::mockConfig(['hyde.navigation.subdirectory_display' => 'hidden']); $frontMatter = new FrontMatter(['navigation.group' => 'Test Group']); $coreDataObject = new CoreDataObject($frontMatter, new Markdown(), MarkdownPage::class, 'test.md', '', '', ''); @@ -259,7 +259,7 @@ public function testMakeGroupUsesFrontMatterGroupIfSetRegardlessOfSubdirectoryCo public function testMakeGroupDefaultsToNullIfFrontMatterGroupNotSetAndSubdirectoriesNotUsed() { - self::mockConfig(['hyde.navigation.subdirectories' => 'hidden']); + self::mockConfig(['hyde.navigation.subdirectory_display' => 'hidden']); $coreDataObject = new CoreDataObject(new FrontMatter(), new Markdown(), MarkdownPage::class, 'test.md', '', '', ''); $factory = new NavigationConfigTestClass($coreDataObject); diff --git a/packages/framework/tests/Unit/RelativeLinksAcrossPagesRetainsIntegrityTest.php b/packages/framework/tests/Unit/RelativeLinksAcrossPagesRetainsIntegrityTest.php index facec7a3cc6..e8f9f8c1f66 100644 --- a/packages/framework/tests/Unit/RelativeLinksAcrossPagesRetainsIntegrityTest.php +++ b/packages/framework/tests/Unit/RelativeLinksAcrossPagesRetainsIntegrityTest.php @@ -23,7 +23,7 @@ protected function setUp(): void parent::setUp(); config(['hyde.enable_cache_busting' => false]); - config(['hyde.navigation.subdirectories' => 'flat']); + config(['hyde.navigation.subdirectory_display' => 'flat']); $this->needsDirectory('_pages/nested'); $this->file('_pages/root.md'); diff --git a/packages/framework/tests/Unit/Views/NavigationHtmlLayoutsTest.php b/packages/framework/tests/Unit/Views/NavigationHtmlLayoutsTest.php index b34f0d78af2..9935ef20e84 100644 --- a/packages/framework/tests/Unit/Views/NavigationHtmlLayoutsTest.php +++ b/packages/framework/tests/Unit/Views/NavigationHtmlLayoutsTest.php @@ -515,7 +515,7 @@ protected function sidebar(array $withPages = []): RenderedDocumentationSidebarM protected function useSubdirectoryConfig(string $option): static { - config(['hyde.navigation.subdirectories' => $option]); + config(['hyde.navigation.subdirectory_display' => $option]); return $this; } diff --git a/packages/framework/tests/Unit/Views/NavigationMenuViewTest.php b/packages/framework/tests/Unit/Views/NavigationMenuViewTest.php index 18d9bfd7cbf..e1aa632ac05 100644 --- a/packages/framework/tests/Unit/Views/NavigationMenuViewTest.php +++ b/packages/framework/tests/Unit/Views/NavigationMenuViewTest.php @@ -78,7 +78,7 @@ public function testNavigationMenuWithRootPages() public function testNavigationMenuWithDropdownPages() { - config(['hyde.navigation.subdirectories' => 'dropdown']); + config(['hyde.navigation.subdirectory_display' => 'dropdown']); $page = new MarkdownPage('page'); $bar = new MarkdownPage('foo/bar'); @@ -104,7 +104,7 @@ public function testNavigationMenuWithDropdownPages() public function testNavigationMenuWithDropdownPagesWithRootGroupPage() { - config(['hyde.navigation.subdirectories' => 'dropdown']); + config(['hyde.navigation.subdirectory_display' => 'dropdown']); $foo = new MarkdownPage('foo'); $bar = new MarkdownPage('foo/bar'); From ba547bdd23fe4d5bff18d5e7a68ff85668c2bef3 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 18:34:17 +0200 Subject: [PATCH 030/232] Test the entire component state --- .../tests/Unit/Views/NavigationLinkViewTest.php | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/packages/framework/tests/Unit/Views/NavigationLinkViewTest.php b/packages/framework/tests/Unit/Views/NavigationLinkViewTest.php index de571ed18df..877eac0b14c 100644 --- a/packages/framework/tests/Unit/Views/NavigationLinkViewTest.php +++ b/packages/framework/tests/Unit/Views/NavigationLinkViewTest.php @@ -88,4 +88,17 @@ public function testComponentHasActiveClassWhenActive() ->assertHasClass('navigation-link') ->assertHasClass('navigation-link-active'); } + + public function testComponentState() + { + $this->mockCurrentPage('foo'); + + $view = $this->testView(); + + $expected = <<<'HTML' + Foo + HTML; + + $this->assertSame($expected, $view->getRendered()); + } } From 5d7fb5e12f88fb3cd036196246e29dee040da681 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 18:22:15 +0200 Subject: [PATCH 031/232] Add attributes array to the navigation item class --- .../src/Framework/Features/Navigation/NavigationItem.php | 2 ++ 1 file changed, 2 insertions(+) diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationItem.php b/packages/framework/src/Framework/Features/Navigation/NavigationItem.php index 43d2cf5312b..b8cbf5b81b5 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationItem.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationItem.php @@ -23,6 +23,8 @@ class NavigationItem implements Stringable protected string $label; protected int $priority; + protected array $attributes = []; + /** * Create a new navigation menu item, automatically filling in the properties from a Route instance if provided. * From b07ecf56cd0bbc5b17c6fba68fb5a17454177afa Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 18:22:29 +0200 Subject: [PATCH 032/232] Annotate scalar array generics --- .../src/Framework/Features/Navigation/NavigationItem.php | 1 + 1 file changed, 1 insertion(+) diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationItem.php b/packages/framework/src/Framework/Features/Navigation/NavigationItem.php index b8cbf5b81b5..6e5d610e010 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationItem.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationItem.php @@ -23,6 +23,7 @@ class NavigationItem implements Stringable protected string $label; protected int $priority; + /** @var array */ protected array $attributes = []; /** From 9762449f1deb9ce95192181f25453d9a97a7c91f Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 18:22:49 +0200 Subject: [PATCH 033/232] Add attributes accessor --- .../src/Framework/Features/Navigation/NavigationItem.php | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationItem.php b/packages/framework/src/Framework/Features/Navigation/NavigationItem.php index 6e5d610e010..bdec0a01a5f 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationItem.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationItem.php @@ -119,4 +119,9 @@ protected static function make(Route|string $destination, ?string $label = null, return [$destination, $label ?? $destination, $priority ?? NavigationMenu::DEFAULT]; } + + public function getAttributes(): array + { + return $this->attributes; + } } From 6c5961bd5c9f8468f6bd9c75e21dc78bb5540fad Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 18:23:27 +0200 Subject: [PATCH 034/232] Return attributes as component attribute bag --- .../src/Framework/Features/Navigation/NavigationItem.php | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationItem.php b/packages/framework/src/Framework/Features/Navigation/NavigationItem.php index bdec0a01a5f..e70f75fb1a3 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationItem.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationItem.php @@ -9,6 +9,7 @@ use Hyde\Hyde; use Hyde\Support\Models\Route; use Stringable; +use Illuminate\View\ComponentAttributeBag; use function is_string; @@ -120,8 +121,8 @@ protected static function make(Route|string $destination, ?string $label = null, return [$destination, $label ?? $destination, $priority ?? NavigationMenu::DEFAULT]; } - public function getAttributes(): array + public function getAttributes(): ComponentAttributeBag { - return $this->attributes; + return new ComponentAttributeBag($this->attributes); } } From 15b97f9db5e48a9917e72080ada9bce928ae09e4 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 18:23:30 +0200 Subject: [PATCH 035/232] Revert "Return attributes as component attribute bag" This reverts commit 3a0c2798132f9ae7a581e38ea89369cd9c68f4fe. --- .../src/Framework/Features/Navigation/NavigationItem.php | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationItem.php b/packages/framework/src/Framework/Features/Navigation/NavigationItem.php index e70f75fb1a3..bdec0a01a5f 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationItem.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationItem.php @@ -9,7 +9,6 @@ use Hyde\Hyde; use Hyde\Support\Models\Route; use Stringable; -use Illuminate\View\ComponentAttributeBag; use function is_string; @@ -121,8 +120,8 @@ protected static function make(Route|string $destination, ?string $label = null, return [$destination, $label ?? $destination, $priority ?? NavigationMenu::DEFAULT]; } - public function getAttributes(): ComponentAttributeBag + public function getAttributes(): array { - return new ComponentAttributeBag($this->attributes); + return $this->attributes; } } From 66dc9b29dc789e1d227386412162e6ababb49620 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 18:23:58 +0200 Subject: [PATCH 036/232] Rename accessor to signify it's for extra attributes Inspired by Filament --- .../src/Framework/Features/Navigation/NavigationItem.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationItem.php b/packages/framework/src/Framework/Features/Navigation/NavigationItem.php index bdec0a01a5f..1254ce72a53 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationItem.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationItem.php @@ -120,7 +120,7 @@ protected static function make(Route|string $destination, ?string $label = null, return [$destination, $label ?? $destination, $priority ?? NavigationMenu::DEFAULT]; } - public function getAttributes(): array + public function getExtraAttributes(): array { return $this->attributes; } From caae63617e14ad6ef875d16ecb9851b7cd503dda Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 18:24:47 +0200 Subject: [PATCH 037/232] Annotate the scalar return array --- .../src/Framework/Features/Navigation/NavigationItem.php | 1 + 1 file changed, 1 insertion(+) diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationItem.php b/packages/framework/src/Framework/Features/Navigation/NavigationItem.php index 1254ce72a53..418f029f7c6 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationItem.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationItem.php @@ -120,6 +120,7 @@ protected static function make(Route|string $destination, ?string $label = null, return [$destination, $label ?? $destination, $priority ?? NavigationMenu::DEFAULT]; } + /** @return array */ public function getExtraAttributes(): array { return $this->attributes; From 283016f0b68a39c270eaaa68bf776ffc252f0523 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 18:25:38 +0200 Subject: [PATCH 038/232] Merge in the extra attributes --- .../views/components/navigation/navigation-link.blade.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/framework/resources/views/components/navigation/navigation-link.blade.php b/packages/framework/resources/views/components/navigation/navigation-link.blade.php index 60ce617081d..f5fc6d7de60 100644 --- a/packages/framework/resources/views/components/navigation/navigation-link.blade.php +++ b/packages/framework/resources/views/components/navigation/navigation-link.blade.php @@ -3,4 +3,4 @@ 'navigation-link-active border-l-4 border-indigo-500 md:border-none font-medium -ml-6 pl-5 md:ml-0 md:pl-0 bg-gray-100 dark:bg-gray-800 md:bg-transparent dark:md:bg-transparent' => $item->isActive() ])->merge([ 'aria-current' => $item->isActive() ? 'page' : false, -]) }}>{{ $item->getLabel() }} \ No newline at end of file +])->merge($item->getExtraAttributes()) }}>{{ $item->getLabel() }} \ No newline at end of file From 93cef20ee21ea8447cf1731c140b78a707b1fff6 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 18:37:22 +0200 Subject: [PATCH 039/232] Change merge order to preserve output format May want to revert this later as it makes sense for user added data to be last, but this preserves the current attribute order for now --- .../views/components/navigation/navigation-link.blade.php | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/framework/resources/views/components/navigation/navigation-link.blade.php b/packages/framework/resources/views/components/navigation/navigation-link.blade.php index f5fc6d7de60..5d2725b22e2 100644 --- a/packages/framework/resources/views/components/navigation/navigation-link.blade.php +++ b/packages/framework/resources/views/components/navigation/navigation-link.blade.php @@ -1,6 +1,6 @@ except('item')->class([ 'navigation-link block my-2 md:my-0 md:inline-block py-1 text-gray-700 hover:text-gray-900 dark:text-gray-100', 'navigation-link-active border-l-4 border-indigo-500 md:border-none font-medium -ml-6 pl-5 md:ml-0 md:pl-0 bg-gray-100 dark:bg-gray-800 md:bg-transparent dark:md:bg-transparent' => $item->isActive() -])->merge([ +])->merge($item->getExtraAttributes())->merge([ 'aria-current' => $item->isActive() ? 'page' : false, -])->merge($item->getExtraAttributes()) }}>{{ $item->getLabel() }} \ No newline at end of file +]) }}>{{ $item->getLabel() }} \ No newline at end of file From 395dbfb849cc00ac29466300ad8f8ced9f0c5cd2 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 18:39:44 +0200 Subject: [PATCH 040/232] Merge in extra attributes last in component This reverts commit 93cef20ee21ea8447cf1731c140b78a707b1fff6. --- .../views/components/navigation/navigation-link.blade.php | 4 ++-- .../framework/tests/Unit/Views/NavigationLinkViewTest.php | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/packages/framework/resources/views/components/navigation/navigation-link.blade.php b/packages/framework/resources/views/components/navigation/navigation-link.blade.php index 5d2725b22e2..f5fc6d7de60 100644 --- a/packages/framework/resources/views/components/navigation/navigation-link.blade.php +++ b/packages/framework/resources/views/components/navigation/navigation-link.blade.php @@ -1,6 +1,6 @@ except('item')->class([ 'navigation-link block my-2 md:my-0 md:inline-block py-1 text-gray-700 hover:text-gray-900 dark:text-gray-100', 'navigation-link-active border-l-4 border-indigo-500 md:border-none font-medium -ml-6 pl-5 md:ml-0 md:pl-0 bg-gray-100 dark:bg-gray-800 md:bg-transparent dark:md:bg-transparent' => $item->isActive() -])->merge($item->getExtraAttributes())->merge([ +])->merge([ 'aria-current' => $item->isActive() ? 'page' : false, -]) }}>{{ $item->getLabel() }} \ No newline at end of file +])->merge($item->getExtraAttributes()) }}>{{ $item->getLabel() }} \ No newline at end of file diff --git a/packages/framework/tests/Unit/Views/NavigationLinkViewTest.php b/packages/framework/tests/Unit/Views/NavigationLinkViewTest.php index 877eac0b14c..7f512e5c769 100644 --- a/packages/framework/tests/Unit/Views/NavigationLinkViewTest.php +++ b/packages/framework/tests/Unit/Views/NavigationLinkViewTest.php @@ -96,7 +96,7 @@ public function testComponentState() $view = $this->testView(); $expected = <<<'HTML' - Foo + Foo HTML; $this->assertSame($expected, $view->getRendered()); From b558720c6c37e424c8f8cd8ba03f19182abd2992 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 18:45:24 +0200 Subject: [PATCH 041/232] Update RelativeLinksAcrossPagesRetainsIntegrityTest.php --- .../Unit/RelativeLinksAcrossPagesRetainsIntegrityTest.php | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/packages/framework/tests/Unit/RelativeLinksAcrossPagesRetainsIntegrityTest.php b/packages/framework/tests/Unit/RelativeLinksAcrossPagesRetainsIntegrityTest.php index e8f9f8c1f66..30267866c34 100644 --- a/packages/framework/tests/Unit/RelativeLinksAcrossPagesRetainsIntegrityTest.php +++ b/packages/framework/tests/Unit/RelativeLinksAcrossPagesRetainsIntegrityTest.php @@ -73,10 +73,11 @@ public function testRelativeLinksAcrossPagesRetainsIntegrity() '', 'assertSee('nested/level1', [ @@ -85,8 +86,9 @@ public function testRelativeLinksAcrossPagesRetainsIntegrity() 'assertSee('docs/index', [ From 9c60087503f8811d80afc4f9305de8685c53d890 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 18:47:28 +0200 Subject: [PATCH 042/232] Revert "Update RelativeLinksAcrossPagesRetainsIntegrityTest.php" This reverts commit b558720c6c37e424c8f8cd8ba03f19182abd2992. --- .../Unit/RelativeLinksAcrossPagesRetainsIntegrityTest.php | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/packages/framework/tests/Unit/RelativeLinksAcrossPagesRetainsIntegrityTest.php b/packages/framework/tests/Unit/RelativeLinksAcrossPagesRetainsIntegrityTest.php index 30267866c34..e8f9f8c1f66 100644 --- a/packages/framework/tests/Unit/RelativeLinksAcrossPagesRetainsIntegrityTest.php +++ b/packages/framework/tests/Unit/RelativeLinksAcrossPagesRetainsIntegrityTest.php @@ -73,11 +73,10 @@ public function testRelativeLinksAcrossPagesRetainsIntegrity() '', 'assertSee('nested/level1', [ @@ -86,9 +85,8 @@ public function testRelativeLinksAcrossPagesRetainsIntegrity() 'assertSee('docs/index', [ From c087bbf46548ae8b83da6739f83480ba1ed6820e Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 18:47:31 +0200 Subject: [PATCH 043/232] Revert "Merge in extra attributes last in component" This reverts commit 395dbfb849cc00ac29466300ad8f8ced9f0c5cd2. --- .../views/components/navigation/navigation-link.blade.php | 4 ++-- .../framework/tests/Unit/Views/NavigationLinkViewTest.php | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/packages/framework/resources/views/components/navigation/navigation-link.blade.php b/packages/framework/resources/views/components/navigation/navigation-link.blade.php index f5fc6d7de60..5d2725b22e2 100644 --- a/packages/framework/resources/views/components/navigation/navigation-link.blade.php +++ b/packages/framework/resources/views/components/navigation/navigation-link.blade.php @@ -1,6 +1,6 @@ except('item')->class([ 'navigation-link block my-2 md:my-0 md:inline-block py-1 text-gray-700 hover:text-gray-900 dark:text-gray-100', 'navigation-link-active border-l-4 border-indigo-500 md:border-none font-medium -ml-6 pl-5 md:ml-0 md:pl-0 bg-gray-100 dark:bg-gray-800 md:bg-transparent dark:md:bg-transparent' => $item->isActive() -])->merge([ +])->merge($item->getExtraAttributes())->merge([ 'aria-current' => $item->isActive() ? 'page' : false, -])->merge($item->getExtraAttributes()) }}>{{ $item->getLabel() }} \ No newline at end of file +]) }}>{{ $item->getLabel() }} \ No newline at end of file diff --git a/packages/framework/tests/Unit/Views/NavigationLinkViewTest.php b/packages/framework/tests/Unit/Views/NavigationLinkViewTest.php index 7f512e5c769..877eac0b14c 100644 --- a/packages/framework/tests/Unit/Views/NavigationLinkViewTest.php +++ b/packages/framework/tests/Unit/Views/NavigationLinkViewTest.php @@ -96,7 +96,7 @@ public function testComponentState() $view = $this->testView(); $expected = <<<'HTML' - Foo + Foo HTML; $this->assertSame($expected, $view->getRendered()); From 33e40d82bf8a34f5b9e33ebfcce1825fd510b853 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 20:17:33 +0200 Subject: [PATCH 044/232] Update navigation item facade to support the attribute parameter --- packages/framework/src/Facades/Navigation.php | 5 +++-- .../framework/tests/Feature/YamlConfigurationFeatureTest.php | 4 ++++ .../framework/tests/Unit/Facades/NavigationFacadeTest.php | 3 +++ 3 files changed, 10 insertions(+), 2 deletions(-) diff --git a/packages/framework/src/Facades/Navigation.php b/packages/framework/src/Facades/Navigation.php index a91b41fef5a..e7d12646e06 100644 --- a/packages/framework/src/Facades/Navigation.php +++ b/packages/framework/src/Facades/Navigation.php @@ -21,9 +21,10 @@ class Navigation * @param string<\Hyde\Support\Models\RouteKey>|string $destination Route key, or an external URI. * @param string|null $label If not provided, Hyde will try to get it from the route's connected page, or from the URL. * @param int|null $priority If not provided, Hyde will try to get it from the route or the default priority of 500. + * @param array $attributes Additional attributes for the navigation item. */ - public static function item(string $destination, ?string $label = null, ?int $priority = null): array + public static function item(string $destination, ?string $label = null, ?int $priority = null, array $attributes = []): array { - return compact('destination', 'label', 'priority'); + return compact('destination', 'label', 'priority', 'attributes'); } } diff --git a/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php b/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php index 71c1d5c8d24..6f3f32db097 100644 --- a/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php +++ b/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php @@ -497,14 +497,17 @@ public function testCanSetCustomNavigationItemsInTheYamlConfig() 'destination' => 'https://example.com', 'label' => 'Example', 'priority' => 100, + 'attributes' => [], ], [ 'destination' => 'about', 'label' => 'About Us', 'priority' => 200, + 'attributes' => [], ], [ 'destination' => 'contact', 'label' => 'Contact', 'priority' => 300, + 'attributes' => [], ], ], $configItems); @@ -549,6 +552,7 @@ public function testOnlyNeedToAddDestinationToYamlConfiguredNavigationItems() 'destination' => 'about.html', 'label' => null, 'priority' => null, + 'attributes' => [], ], ], $configItems); diff --git a/packages/framework/tests/Unit/Facades/NavigationFacadeTest.php b/packages/framework/tests/Unit/Facades/NavigationFacadeTest.php index bbc7e2d84f0..a4b68d9f7c4 100644 --- a/packages/framework/tests/Unit/Facades/NavigationFacadeTest.php +++ b/packages/framework/tests/Unit/Facades/NavigationFacadeTest.php @@ -20,6 +20,7 @@ public function testItem() 'destination' => 'home', 'label' => 'Home', 'priority' => 100, + 'attributes' => [], ], $item); } @@ -31,6 +32,7 @@ public function testItemWithOnlyDestination() 'destination' => 'home', 'label' => null, 'priority' => null, + 'attributes' => [], ], $item); } @@ -42,6 +44,7 @@ public function testItemWithUrl() 'destination' => 'https://example.com', 'label' => 'External', 'priority' => 200, + 'attributes' => [], ], $item); } } From 1beec7e8f343d5cb43785c40fb8df1693a3ad65b Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 20:28:17 +0200 Subject: [PATCH 045/232] Update the make method to support extra attributes --- .../src/Framework/Features/Navigation/NavigationItem.php | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationItem.php b/packages/framework/src/Framework/Features/Navigation/NavigationItem.php index 418f029f7c6..d0f1c7c8868 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationItem.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationItem.php @@ -103,8 +103,8 @@ public function isActive(): bool return Hyde::currentRoute()?->getLink() === $this->getLink(); } - /** @return array{\Hyde\Support\Models\Route|string, string, int} */ - protected static function make(Route|string $destination, ?string $label = null, ?int $priority = null): array + /** @return array{\Hyde\Support\Models\Route|string, string, int, array} */ + protected static function make(Route|string $destination, ?string $label = null, ?int $priority = null, array $attributes = []): array { // Automatically resolve the destination if it's a route key. if (is_string($destination) && Routes::has($destination)) { @@ -117,7 +117,7 @@ protected static function make(Route|string $destination, ?string $label = null, $priority ??= $destination->getPage()->navigationMenuPriority(); } - return [$destination, $label ?? $destination, $priority ?? NavigationMenu::DEFAULT]; + return [$destination, $label ?? $destination, $priority ?? NavigationMenu::DEFAULT, $attributes]; } /** @return array */ From 8080709c578dce1ad7bd4df14500e934fb6b1908 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 20:30:01 +0200 Subject: [PATCH 046/232] Update the constructors to support extra attributes --- .../Framework/Features/Navigation/NavigationItem.php | 10 ++++++---- packages/framework/tests/Unit/NavigationItemTest.php | 12 ++++++++++++ 2 files changed, 18 insertions(+), 4 deletions(-) diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationItem.php b/packages/framework/src/Framework/Features/Navigation/NavigationItem.php index d0f1c7c8868..a7fa7bb252c 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationItem.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationItem.php @@ -32,10 +32,11 @@ class NavigationItem implements Stringable * @param \Hyde\Support\Models\Route|string<\Hyde\Support\Models\RouteKey>|string $destination Route instance or route key, or an external URI. * @param string|null $label If not provided, Hyde will try to get it from the route's connected page, or from the URL. * @param int|null $priority If not provided, Hyde will try to get it from the route or the default priority of 500. + * @param array $attributes Additional attributes for the navigation item. */ - public function __construct(Route|string $destination, ?string $label = null, ?int $priority = null) + public function __construct(Route|string $destination, ?string $label = null, ?int $priority = null, array $attributes = []) { - [$this->destination, $this->label, $this->priority] = self::make($destination, $label, $priority); + [$this->destination, $this->label, $this->priority, $this->attributes] = self::make($destination, $label, $priority, $attributes); } /** @@ -44,10 +45,11 @@ public function __construct(Route|string $destination, ?string $label = null, ?i * @param \Hyde\Support\Models\Route|string<\Hyde\Support\Models\RouteKey>|string $destination Route instance or route key, or an external URI. * @param string|null $label If not provided, Hyde will try to get it from the route's connected page, or from the URL. * @param int|null $priority If not provided, Hyde will try to get it from the route or the default priority of 500. + * @param array $attributes Additional attributes for the navigation item. */ - public static function create(Route|string $destination, ?string $label = null, ?int $priority = null): static + public static function create(Route|string $destination, ?string $label = null, ?int $priority = null, array $attributes = []): static { - return new static(...self::make($destination, $label, $priority)); + return new static(...self::make($destination, $label, $priority, $attributes)); } /** diff --git a/packages/framework/tests/Unit/NavigationItemTest.php b/packages/framework/tests/Unit/NavigationItemTest.php index e0a669adf9a..22742802644 100644 --- a/packages/framework/tests/Unit/NavigationItemTest.php +++ b/packages/framework/tests/Unit/NavigationItemTest.php @@ -325,4 +325,16 @@ public function testIsCurrentIsNullSafe() { $this->assertFalse(NavigationItem::create('foo', 'bar')->isActive()); } + + public function testConstructWithAttributes() + { + $item = new NavigationItem('foo', 'Test', 500, ['class' => 'active']); + $this->assertSame(['class' => 'active'], $item->getExtraAttributes()); + } + + public function testCreateWithAttributes() + { + $item = NavigationItem::create('foo', 'Test', 500, ['class' => 'active']); + $this->assertSame(['class' => 'active'], $item->getExtraAttributes()); + } } From 8b6d678ef44ea969855a1c87680d37bae5ddf30f Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 20:31:39 +0200 Subject: [PATCH 047/232] Generate attribute accessors --- .../Features/Navigation/NavigationItem.php | 47 +++++++++++++++++++ .../tests/Unit/NavigationItemTest.php | 29 ++++++++++++ 2 files changed, 76 insertions(+) diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationItem.php b/packages/framework/src/Framework/Features/Navigation/NavigationItem.php index a7fa7bb252c..9b6a498ab59 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationItem.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationItem.php @@ -127,4 +127,51 @@ public function getExtraAttributes(): array { return $this->attributes; } + + /** + * Set an extra attribute for the navigation item. + * + * @param string $key + * @param scalar $value + * @return $this + */ + public function setAttribute(string $key, $value): self + { + $this->attributes[$key] = $value; + return $this; + } + + /** + * Set multiple extra attributes for the navigation item. + * + * @param array $attributes + * @return $this + */ + public function setAttributes(array $attributes): self + { + $this->attributes = array_merge($this->attributes, $attributes); + return $this; + } + + /** + * Get an extra attribute of the navigation item. + * + * @param string $key + * @param scalar|null $default + * @return scalar|null + */ + public function getAttribute(string $key, $default = null) + { + return $this->attributes[$key] ?? $default; + } + + /** + * Get all extra attributes of the navigation item. + * + * @return array + */ + public function getAttributes(): array + { + return $this->attributes; + } } diff --git a/packages/framework/tests/Unit/NavigationItemTest.php b/packages/framework/tests/Unit/NavigationItemTest.php index 22742802644..f27269745d2 100644 --- a/packages/framework/tests/Unit/NavigationItemTest.php +++ b/packages/framework/tests/Unit/NavigationItemTest.php @@ -337,4 +337,33 @@ public function testCreateWithAttributes() $item = NavigationItem::create('foo', 'Test', 500, ['class' => 'active']); $this->assertSame(['class' => 'active'], $item->getExtraAttributes()); } + + public function testSetAttribute() + { + $item = new NavigationItem('foo', 'Test'); + $item->setAttribute('class', 'active'); + $this->assertSame('active', $item->getAttribute('class')); + } + + public function testSetAttributes() + { + $item = new NavigationItem('foo', 'Test'); + $item->setAttributes(['class' => 'active', 'id' => 'nav-item']); + $this->assertSame(['class' => 'active', 'id' => 'nav-item'], $item->getAttributes()); + } + + public function testGetAttribute() + { + $item = new NavigationItem('foo', 'Test', 500, ['class' => 'active']); + $this->assertSame('active', $item->getAttribute('class')); + $this->assertNull($item->getAttribute('id')); + $this->assertSame('default', $item->getAttribute('id', 'default')); + } + + public function testGetAttributes() + { + $attributes = ['class' => 'active', 'id' => 'nav-item']; + $item = new NavigationItem('foo', 'Test', 500, $attributes); + $this->assertSame($attributes, $item->getAttributes()); + } } From 17a33e0c56801879e30194d71b9db5e814c9c1ed Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 20:31:42 +0200 Subject: [PATCH 048/232] Revert "Generate attribute accessors" This reverts commit 8b6d678ef44ea969855a1c87680d37bae5ddf30f. --- .../Features/Navigation/NavigationItem.php | 47 ------------------- .../tests/Unit/NavigationItemTest.php | 29 ------------ 2 files changed, 76 deletions(-) diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationItem.php b/packages/framework/src/Framework/Features/Navigation/NavigationItem.php index 9b6a498ab59..a7fa7bb252c 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationItem.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationItem.php @@ -127,51 +127,4 @@ public function getExtraAttributes(): array { return $this->attributes; } - - /** - * Set an extra attribute for the navigation item. - * - * @param string $key - * @param scalar $value - * @return $this - */ - public function setAttribute(string $key, $value): self - { - $this->attributes[$key] = $value; - return $this; - } - - /** - * Set multiple extra attributes for the navigation item. - * - * @param array $attributes - * @return $this - */ - public function setAttributes(array $attributes): self - { - $this->attributes = array_merge($this->attributes, $attributes); - return $this; - } - - /** - * Get an extra attribute of the navigation item. - * - * @param string $key - * @param scalar|null $default - * @return scalar|null - */ - public function getAttribute(string $key, $default = null) - { - return $this->attributes[$key] ?? $default; - } - - /** - * Get all extra attributes of the navigation item. - * - * @return array - */ - public function getAttributes(): array - { - return $this->attributes; - } } diff --git a/packages/framework/tests/Unit/NavigationItemTest.php b/packages/framework/tests/Unit/NavigationItemTest.php index f27269745d2..22742802644 100644 --- a/packages/framework/tests/Unit/NavigationItemTest.php +++ b/packages/framework/tests/Unit/NavigationItemTest.php @@ -337,33 +337,4 @@ public function testCreateWithAttributes() $item = NavigationItem::create('foo', 'Test', 500, ['class' => 'active']); $this->assertSame(['class' => 'active'], $item->getExtraAttributes()); } - - public function testSetAttribute() - { - $item = new NavigationItem('foo', 'Test'); - $item->setAttribute('class', 'active'); - $this->assertSame('active', $item->getAttribute('class')); - } - - public function testSetAttributes() - { - $item = new NavigationItem('foo', 'Test'); - $item->setAttributes(['class' => 'active', 'id' => 'nav-item']); - $this->assertSame(['class' => 'active', 'id' => 'nav-item'], $item->getAttributes()); - } - - public function testGetAttribute() - { - $item = new NavigationItem('foo', 'Test', 500, ['class' => 'active']); - $this->assertSame('active', $item->getAttribute('class')); - $this->assertNull($item->getAttribute('id')); - $this->assertSame('default', $item->getAttribute('id', 'default')); - } - - public function testGetAttributes() - { - $attributes = ['class' => 'active', 'id' => 'nav-item']; - $item = new NavigationItem('foo', 'Test', 500, $attributes); - $this->assertSame($attributes, $item->getAttributes()); - } } From 3f7c34b178a7535106d32db65468052522289ddd Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 20:38:00 +0200 Subject: [PATCH 049/232] Test the view with extra attributes Claude is just insanely good --- .../Unit/Views/NavigationLinkViewTest.php | 53 ++++++++++++++++++- 1 file changed, 51 insertions(+), 2 deletions(-) diff --git a/packages/framework/tests/Unit/Views/NavigationLinkViewTest.php b/packages/framework/tests/Unit/Views/NavigationLinkViewTest.php index 877eac0b14c..274a71420e0 100644 --- a/packages/framework/tests/Unit/Views/NavigationLinkViewTest.php +++ b/packages/framework/tests/Unit/Views/NavigationLinkViewTest.php @@ -26,10 +26,10 @@ protected function setUp(): void $this->mockPage(); } - protected function testView(): TestView + protected function testView(array $extraAttributes = []): TestView { return $this->view(view('hyde::components.navigation.navigation-link', [ - 'item' => NavigationItem::create(new Route(new InMemoryPage('foo')), 'Foo'), + 'item' => NavigationItem::create(new Route(new InMemoryPage('foo')), 'Foo', null, $extraAttributes), 'attributes' => new ComponentAttributeBag(), ])); } @@ -89,6 +89,55 @@ public function testComponentHasActiveClassWhenActive() ->assertHasClass('navigation-link-active'); } + public function testComponentRendersExtraAttributes() + { + $this->testView(['data-test' => 'value']) + ->assertHasAttribute('data-test') + ->assertAttributeIs('data-test="value"'); + } + + public function testComponentRendersMultipleExtraAttributes() + { + $this->testView(['data-test' => 'value', 'data-foo' => 'bar']) + ->assertHasAttribute('data-test') + ->assertAttributeIs('data-test="value"') + ->assertHasAttribute('data-foo') + ->assertAttributeIs('data-foo="bar"'); + } + + public function testComponentRendersExtraAttributesWithExistingAttributes() + { + $this->mockCurrentPage('foo'); + + $view = $this->testView(['data-test' => 'value']); + + $expected = <<<'HTML' + Foo + HTML; + + $this->assertSame($expected, $view->getRendered()); + } + + public function testComponentMergesClassAttributeCorrectly() + { + $this->testView(['class' => 'custom-class']) + ->assertHasClass('navigation-link') + ->assertHasClass('custom-class'); + } + + public function testComponentOverridesDefaultAttributesWithExtraAttributes() + { + $this->testView(['href' => 'https://example.com']) + ->assertAttributeIs('href="https://example.com"'); + } + + public function testComponentHandlesEmptyExtraAttributes() + { + $this->testView([]) + ->assertHasElement('') + ->assertTextIs('Foo'); + } + public function testComponentState() { $this->mockCurrentPage('foo'); From 798d363f2b50409012da280af280a1da036054aa Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 20:40:26 +0200 Subject: [PATCH 050/232] Annotate the return array shape --- packages/framework/src/Facades/Navigation.php | 1 + 1 file changed, 1 insertion(+) diff --git a/packages/framework/src/Facades/Navigation.php b/packages/framework/src/Facades/Navigation.php index e7d12646e06..b2dda93d6c7 100644 --- a/packages/framework/src/Facades/Navigation.php +++ b/packages/framework/src/Facades/Navigation.php @@ -22,6 +22,7 @@ class Navigation * @param string|null $label If not provided, Hyde will try to get it from the route's connected page, or from the URL. * @param int|null $priority If not provided, Hyde will try to get it from the route or the default priority of 500. * @param array $attributes Additional attributes for the navigation item. + * @return array{destination: string, label: ?string, priority: ?int, attributes: array} */ public static function item(string $destination, ?string $label = null, ?int $priority = null, array $attributes = []): array { From ed615a7c9bef361973d8e42c6e4b99bfa6adba8b Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 20:41:07 +0200 Subject: [PATCH 051/232] Update YAML parser array shapes --- .../src/Foundation/Internal/LoadYamlConfiguration.php | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/framework/src/Foundation/Internal/LoadYamlConfiguration.php b/packages/framework/src/Foundation/Internal/LoadYamlConfiguration.php index 0ac92ab01d0..8a8f2afe540 100644 --- a/packages/framework/src/Foundation/Internal/LoadYamlConfiguration.php +++ b/packages/framework/src/Foundation/Internal/LoadYamlConfiguration.php @@ -86,8 +86,8 @@ protected function parseAuthors(array $authors): array /** * @experimental Since the main configuration also uses arrays, the only thing this method really does is to rethrow any exceptions. * - * @param array $items Where destination is a route key or an external URI. - * @return array + * @param array}> $items Where destination is a route key or an external URI. + * @return array}> */ protected function parseNavigationItems(array $items): array { From 57317389474b6d5115c3d9726886bd4bedf96aa4 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 20:44:21 +0200 Subject: [PATCH 052/232] Support setting navigation items with extra attributes in the config --- .../Navigation/NavigationMenuGenerator.php | 2 +- .../tests/Feature/NavigationMenuTest.php | 15 +++++ .../Feature/YamlConfigurationFeatureTest.php | 61 +++++++++++++++++++ 3 files changed, 77 insertions(+), 1 deletion(-) diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php b/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php index eae219d2f53..54ed54cbf26 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php @@ -83,7 +83,7 @@ protected function generate(): void } else { collect(Config::getArray('hyde.navigation.custom', []))->each(function (array $item): void { // Since these were added explicitly by the user, we can assume they should always be shown - $this->items->push(NavigationItem::create($item['destination'], $item['label'] ?? null, $item['priority'] ?? null)); + $this->items->push(NavigationItem::create($item['destination'], $item['label'] ?? null, $item['priority'] ?? null, $item['attributes'] ?? [])); }); } } diff --git a/packages/framework/tests/Feature/NavigationMenuTest.php b/packages/framework/tests/Feature/NavigationMenuTest.php index cd9d6f72986..b07e62e13de 100644 --- a/packages/framework/tests/Feature/NavigationMenuTest.php +++ b/packages/framework/tests/Feature/NavigationMenuTest.php @@ -152,6 +152,21 @@ public function testPathLinkCanBeAddedInConfig() $this->assertEquals($expected, $menu->getItems()); } + public function testCanAddCustomLinksInConfigWithExtraAttributes() + { + config(['hyde.navigation.custom' => [Navigation::item('foo', 'Foo', 100, ['class' => 'foo'])]]); + + $menu = $this->createNavigationMenu(); + + $expected = collect([ + NavigationItem::create(Routes::get('index')), + NavigationItem::create('foo', 'Foo', 100, ['class' => 'foo']), + ]); + + $this->assertCount(count($expected), $menu->getItems()); + $this->assertEquals($expected, $menu->getItems()); + } + public function testDuplicatesAreNotRemovedWhenAddingInConfig() { config(['hyde.navigation.custom' => [ diff --git a/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php b/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php index 6f3f32db097..7531bf44f94 100644 --- a/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php +++ b/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php @@ -534,6 +534,67 @@ public function testCanSetCustomNavigationItemsInTheYamlConfig() $this->assertSame(300, $navigationItems[3]->getPriority()); } + public function testCanSetAttributesInNavigationItemsInTheYamlConfig() + { + $this->file('hyde.yml', <<<'YAML' + hyde: + navigation: + custom: + - destination: 'https://example.com' + label: 'Example' + priority: 100 + attributes: + class: 'example' + - destination: 'about' + label: 'About Us' + priority: 200 + attributes: + class: 'about' + id: 'about' + - destination: 'contact' + label: 'Contact' + priority: 300 + attributes: + target: '_blank' + rel: 'noopener noreferrer' + foo: 'bar' + YAML); + + $this->runBootstrappers(); + + $configItems = config('hyde.navigation.custom'); + + $this->assertSame([ + [ + 'destination' => 'https://example.com', + 'label' => 'Example', + 'priority' => 100, + 'attributes' => ['class' => 'example'], + ], [ + 'destination' => 'about', + 'label' => 'About Us', + 'priority' => 200, + 'attributes' => ['class' => 'about', 'id' => 'about'], + ], [ + 'destination' => 'contact', + 'label' => 'Contact', + 'priority' => 300, + 'attributes' => ['target' => '_blank', 'rel' => 'noopener noreferrer', 'foo' => 'bar'], + ], + ], $configItems); + + /** @var NavigationItem[] $navigationItems */ + $navigationItems = NavigationMenuGenerator::handle(MainNavigationMenu::class)->getItems()->all(); + + $this->assertCount(4, $navigationItems); + $this->assertContainsOnlyInstancesOf(NavigationItem::class, $navigationItems); + + $this->assertSame([], $navigationItems[0]->getExtraAttributes()); + $this->assertSame(['class' => 'example'], $navigationItems[1]->getExtraAttributes()); + $this->assertSame(['class' => 'about', 'id' => 'about'], $navigationItems[2]->getExtraAttributes()); + $this->assertSame(['target' => '_blank', 'rel' => 'noopener noreferrer', 'foo' => 'bar'], $navigationItems[3]->getExtraAttributes()); + } + public function testOnlyNeedToAddDestinationToYamlConfiguredNavigationItems() { $this->file('hyde.yml', <<<'YAML' From 09db9f10e91834ddf8789d2483dd789d1b47682c Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 20:48:24 +0200 Subject: [PATCH 053/232] Annotate the parameter array shape --- .../Framework/Features/Navigation/NavigationMenuGenerator.php | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php b/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php index 54ed54cbf26..ddbe9679dd5 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php @@ -81,7 +81,8 @@ protected function generate(): void $this->items->push(NavigationItem::create(DocumentationPage::home())); } } else { - collect(Config::getArray('hyde.navigation.custom', []))->each(function (array $item): void { + collect(Config::getArray('hyde.navigation.custom', []))->each( + /** @param array{destination: string, label: ?string, priority: ?int, attributes: array} $item */ function (array $item): void { // Since these were added explicitly by the user, we can assume they should always be shown $this->items->push(NavigationItem::create($item['destination'], $item['label'] ?? null, $item['priority'] ?? null, $item['attributes'] ?? [])); }); From c8a72a87c30ba7795cddca6f347142a901e7dff2 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 20:49:24 +0200 Subject: [PATCH 054/232] Use variable annotation for cleaner looking code --- .../Framework/Features/Navigation/NavigationMenuGenerator.php | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php b/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php index ddbe9679dd5..b4e55a60706 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php @@ -81,8 +81,8 @@ protected function generate(): void $this->items->push(NavigationItem::create(DocumentationPage::home())); } } else { - collect(Config::getArray('hyde.navigation.custom', []))->each( - /** @param array{destination: string, label: ?string, priority: ?int, attributes: array} $item */ function (array $item): void { + collect(Config::getArray('hyde.navigation.custom', []))->each(function (array $item): void { + /** @var array{destination: string, label: ?string, priority: ?int, attributes: array} $item */ // Since these were added explicitly by the user, we can assume they should always be shown $this->items->push(NavigationItem::create($item['destination'], $item['label'] ?? null, $item['priority'] ?? null, $item['attributes'] ?? [])); }); From c6cdbab07e533afd23220133554fe281da96fc18 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 20:53:32 +0200 Subject: [PATCH 055/232] Test invalid custom navigation configuration throws exception --- .../framework/tests/Feature/NavigationMenuTest.php | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/packages/framework/tests/Feature/NavigationMenuTest.php b/packages/framework/tests/Feature/NavigationMenuTest.php index b07e62e13de..7696bb6eb10 100644 --- a/packages/framework/tests/Feature/NavigationMenuTest.php +++ b/packages/framework/tests/Feature/NavigationMenuTest.php @@ -223,6 +223,18 @@ public function testConfigItemsTakePrecedenceOverGeneratedItems() $this->assertEquals($expected, $menu->getItems()); } + public function testInvalidCustomNavigationConfigurationThrowsException() + { + $this->expectException(\Error::class); + // $this->expectExceptionMessage('Invalid configuration for custom navigation item'); + + config(['hyde.navigation.custom' => [ + ['invalid_key' => 'value'], + ]]); + + $this->createNavigationMenu(); + } + public function testDocumentationPagesThatAreNotIndexAreNotAddedToTheMenu() { $this->file('_docs/foo.md'); From b0bbfa7a8c4aee68bbbf615b00ad1cfa07936f30 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 20:53:38 +0200 Subject: [PATCH 056/232] Unpack the array directly --- .../Framework/Features/Navigation/NavigationMenuGenerator.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php b/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php index b4e55a60706..2a9d54c701e 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php @@ -84,7 +84,7 @@ protected function generate(): void collect(Config::getArray('hyde.navigation.custom', []))->each(function (array $item): void { /** @var array{destination: string, label: ?string, priority: ?int, attributes: array} $item */ // Since these were added explicitly by the user, we can assume they should always be shown - $this->items->push(NavigationItem::create($item['destination'], $item['label'] ?? null, $item['priority'] ?? null, $item['attributes'] ?? [])); + $this->items->push(NavigationItem::create(...$item)); }); } } From 87bb7efc8d7f36cf22b57a8231fa41f78939007b Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 20:58:27 +0200 Subject: [PATCH 057/232] Introduce local variable --- .../Framework/Features/Navigation/NavigationMenuGenerator.php | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php b/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php index 2a9d54c701e..b7d2781d908 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php @@ -83,8 +83,10 @@ protected function generate(): void } else { collect(Config::getArray('hyde.navigation.custom', []))->each(function (array $item): void { /** @var array{destination: string, label: ?string, priority: ?int, attributes: array} $item */ + $item = NavigationItem::create(...$item); + // Since these were added explicitly by the user, we can assume they should always be shown - $this->items->push(NavigationItem::create(...$item)); + $this->items->push($item); }); } } From ca28299a2d595ac72b442f92a74fe7dc662990f4 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 20:59:17 +0200 Subject: [PATCH 058/232] Catch and rethrow error caused by bad configuration --- .../Features/Navigation/NavigationMenuGenerator.php | 13 +++++++++++-- .../framework/tests/Feature/NavigationMenuTest.php | 5 +++-- 2 files changed, 14 insertions(+), 4 deletions(-) diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php b/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php index b7d2781d908..8bcbb2c2f14 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php @@ -5,12 +5,14 @@ namespace Hyde\Framework\Features\Navigation; use Hyde\Hyde; +use Throwable; use Hyde\Facades\Config; use Hyde\Support\Models\Route; use Hyde\Pages\DocumentationPage; use Illuminate\Support\Collection; use Hyde\Foundation\Facades\Routes; use Hyde\Foundation\Kernel\RouteCollection; +use Hyde\Framework\Exceptions\InvalidConfigurationException; use function filled; use function assert; @@ -83,8 +85,15 @@ protected function generate(): void } else { collect(Config::getArray('hyde.navigation.custom', []))->each(function (array $item): void { /** @var array{destination: string, label: ?string, priority: ?int, attributes: array} $item */ - $item = NavigationItem::create(...$item); - + try { + $item = NavigationItem::create(...$item); + } catch (Throwable $exception) { + throw new InvalidConfigurationException( + 'Invalid navigation item configuration detected the configuration file. Please double check the syntax.', + previous: $exception + ); + } + // Since these were added explicitly by the user, we can assume they should always be shown $this->items->push($item); }); diff --git a/packages/framework/tests/Feature/NavigationMenuTest.php b/packages/framework/tests/Feature/NavigationMenuTest.php index 7696bb6eb10..0b48b00c05d 100644 --- a/packages/framework/tests/Feature/NavigationMenuTest.php +++ b/packages/framework/tests/Feature/NavigationMenuTest.php @@ -14,6 +14,7 @@ use Hyde\Pages\MarkdownPage; use Hyde\Testing\TestCase; use Illuminate\Support\Collection; +use Hyde\Framework\Exceptions\InvalidConfigurationException; use Hyde\Framework\Features\Navigation\NavigationMenuGenerator; /** @@ -225,8 +226,8 @@ public function testConfigItemsTakePrecedenceOverGeneratedItems() public function testInvalidCustomNavigationConfigurationThrowsException() { - $this->expectException(\Error::class); - // $this->expectExceptionMessage('Invalid configuration for custom navigation item'); + $this->expectException(InvalidConfigurationException::class); + $this->expectExceptionMessage('Invalid navigation item configuration detected the configuration file. Please double check the syntax.'); config(['hyde.navigation.custom' => [ ['invalid_key' => 'value'], From 3f2878ae4480b619f5563fd8a0d80b8e43ecc285 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 21:00:18 +0200 Subject: [PATCH 059/232] Normalize to more generic error message --- .../src/Foundation/Internal/LoadYamlConfiguration.php | 2 +- .../tests/Feature/YamlConfigurationFeatureTest.php | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/packages/framework/src/Foundation/Internal/LoadYamlConfiguration.php b/packages/framework/src/Foundation/Internal/LoadYamlConfiguration.php index 8a8f2afe540..126e8296b12 100644 --- a/packages/framework/src/Foundation/Internal/LoadYamlConfiguration.php +++ b/packages/framework/src/Foundation/Internal/LoadYamlConfiguration.php @@ -96,7 +96,7 @@ protected function parseNavigationItems(array $items): array return Navigation::item(...$item); } catch (Throwable $exception) { throw new InvalidConfigurationException( - 'Invalid navigation item configuration detected in the YAML config file. Please double check the syntax.', + 'Invalid navigation item configuration detected the configuration file. Please double check the syntax.', previous: $exception ); } diff --git a/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php b/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php index 7531bf44f94..266e0804866 100644 --- a/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php +++ b/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php @@ -670,7 +670,7 @@ public function testTypeErrorsInNavigationYamlConfigAreRethrownMoreHelpfully() try { $this->runBootstrappers(); } catch (InvalidConfigurationException $exception) { - $this->assertSame('Invalid navigation item configuration detected in the YAML config file. Please double check the syntax.', $exception->getMessage()); + $this->assertSame('Invalid navigation item configuration detected the configuration file. Please double check the syntax.', $exception->getMessage()); } unlink('hyde.yml'); @@ -688,7 +688,7 @@ public function testMustAddDestinationToYamlConfiguredNavigationItems() try { $this->runBootstrappers(); } catch (InvalidConfigurationException $exception) { - $this->assertSame('Invalid navigation item configuration detected in the YAML config file. Please double check the syntax.', $exception->getMessage()); + $this->assertSame('Invalid navigation item configuration detected the configuration file. Please double check the syntax.', $exception->getMessage()); } unlink('hyde.yml'); @@ -707,7 +707,7 @@ public function testAddingExtraYamlNavigationItemFieldsThrowsAnException() try { $this->runBootstrappers(); } catch (InvalidConfigurationException $exception) { - $this->assertSame('Invalid navigation item configuration detected in the YAML config file. Please double check the syntax.', $exception->getMessage()); + $this->assertSame('Invalid navigation item configuration detected the configuration file. Please double check the syntax.', $exception->getMessage()); } unlink('hyde.yml'); From 5ed108226e1149d85d2987e0c00235b453cddf2b Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 21:03:32 +0200 Subject: [PATCH 060/232] Add helpers to assert exception was thrown --- .../Feature/YamlConfigurationFeatureTest.php | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php b/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php index 266e0804866..1e6245f2170 100644 --- a/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php +++ b/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php @@ -456,6 +456,8 @@ public function testCanSetAuthorsInTheYamlConfig() public function testTypeErrorsInAuthorsYamlConfigAreRethrownMoreHelpfully() { + $exceptionThrown = false; + file_put_contents('hyde.yml', <<<'YAML' authors: wrong: @@ -465,9 +467,11 @@ public function testTypeErrorsInAuthorsYamlConfigAreRethrownMoreHelpfully() try { $this->runBootstrappers(); } catch (InvalidConfigurationException $exception) { + $exceptionThrown = true; $this->assertSame('Invalid author configuration detected in the YAML config file. Please double check the syntax.', $exception->getMessage()); } + $this->assertTrue($exceptionThrown); unlink('hyde.yml'); } @@ -660,6 +664,8 @@ public function testNavigationItemsInTheYamlConfigCanBeResolvedToRoutes() public function testTypeErrorsInNavigationYamlConfigAreRethrownMoreHelpfully() { + $exceptionThrown = false; + file_put_contents('hyde.yml', <<<'YAML' hyde: navigation: @@ -670,14 +676,18 @@ public function testTypeErrorsInNavigationYamlConfigAreRethrownMoreHelpfully() try { $this->runBootstrappers(); } catch (InvalidConfigurationException $exception) { + $exceptionThrown = true; $this->assertSame('Invalid navigation item configuration detected the configuration file. Please double check the syntax.', $exception->getMessage()); } + $this->assertTrue($exceptionThrown); unlink('hyde.yml'); } public function testMustAddDestinationToYamlConfiguredNavigationItems() { + $exceptionThrown = false; + file_put_contents('hyde.yml', <<<'YAML' hyde: navigation: @@ -688,14 +698,18 @@ public function testMustAddDestinationToYamlConfiguredNavigationItems() try { $this->runBootstrappers(); } catch (InvalidConfigurationException $exception) { + $exceptionThrown = true; $this->assertSame('Invalid navigation item configuration detected the configuration file. Please double check the syntax.', $exception->getMessage()); } + $this->assertTrue($exceptionThrown); unlink('hyde.yml'); } public function testAddingExtraYamlNavigationItemFieldsThrowsAnException() { + $exceptionThrown = false; + file_put_contents('hyde.yml', <<<'YAML' hyde: navigation: @@ -707,9 +721,11 @@ public function testAddingExtraYamlNavigationItemFieldsThrowsAnException() try { $this->runBootstrappers(); } catch (InvalidConfigurationException $exception) { + $exceptionThrown = true; $this->assertSame('Invalid navigation item configuration detected the configuration file. Please double check the syntax.', $exception->getMessage()); } + $this->assertTrue($exceptionThrown); unlink('hyde.yml'); } From 138e4b9c92453c3405327359e88f8ad7a8906d82 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 21:03:45 +0200 Subject: [PATCH 061/232] Add message to custom assertion --- .../tests/Feature/YamlConfigurationFeatureTest.php | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php b/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php index 1e6245f2170..b9f6a3fc8fe 100644 --- a/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php +++ b/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php @@ -471,7 +471,7 @@ public function testTypeErrorsInAuthorsYamlConfigAreRethrownMoreHelpfully() $this->assertSame('Invalid author configuration detected in the YAML config file. Please double check the syntax.', $exception->getMessage()); } - $this->assertTrue($exceptionThrown); + $this->assertTrue($exceptionThrown, 'Failed asserting that the exception was thrown.'); unlink('hyde.yml'); } @@ -680,7 +680,7 @@ public function testTypeErrorsInNavigationYamlConfigAreRethrownMoreHelpfully() $this->assertSame('Invalid navigation item configuration detected the configuration file. Please double check the syntax.', $exception->getMessage()); } - $this->assertTrue($exceptionThrown); + $this->assertTrue($exceptionThrown, 'Failed asserting that the exception was thrown.'); unlink('hyde.yml'); } @@ -702,7 +702,7 @@ public function testMustAddDestinationToYamlConfiguredNavigationItems() $this->assertSame('Invalid navigation item configuration detected the configuration file. Please double check the syntax.', $exception->getMessage()); } - $this->assertTrue($exceptionThrown); + $this->assertTrue($exceptionThrown, 'Failed asserting that the exception was thrown.'); unlink('hyde.yml'); } @@ -725,7 +725,7 @@ public function testAddingExtraYamlNavigationItemFieldsThrowsAnException() $this->assertSame('Invalid navigation item configuration detected the configuration file. Please double check the syntax.', $exception->getMessage()); } - $this->assertTrue($exceptionThrown); + $this->assertTrue($exceptionThrown, 'Failed asserting that the exception was thrown.'); unlink('hyde.yml'); } From 6a076b831b3cf07341605c314f0c29bfa4c0a8da Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 21:07:04 +0200 Subject: [PATCH 062/232] Let the generator parse navigation items instead of the loader We "lose" out on the null defaults, but they don't offer any value anyways. --- .../Internal/LoadYamlConfiguration.php | 25 ------------------- .../Feature/YamlConfigurationFeatureTest.php | 9 +++---- 2 files changed, 3 insertions(+), 31 deletions(-) diff --git a/packages/framework/src/Foundation/Internal/LoadYamlConfiguration.php b/packages/framework/src/Foundation/Internal/LoadYamlConfiguration.php index 126e8296b12..1f1dc4963e3 100644 --- a/packages/framework/src/Foundation/Internal/LoadYamlConfiguration.php +++ b/packages/framework/src/Foundation/Internal/LoadYamlConfiguration.php @@ -6,7 +6,6 @@ use Throwable; use Illuminate\Support\Arr; -use Hyde\Facades\Navigation; use Hyde\Foundation\Application; use Illuminate\Config\Repository; use Hyde\Framework\Features\Blogging\Models\PostAuthor; @@ -52,10 +51,6 @@ protected function mergeParsedConfiguration(): void $data['authors'] = $this->parseAuthors($data['authors']); } - if ($namespace === 'hyde' && isset($data['navigation']['custom'])) { - $data['navigation']['custom'] = $this->parseNavigationItems($data['navigation']['custom']); - } - $this->mergeConfiguration($namespace, Arr::undot($data ?: [])); } } @@ -82,24 +77,4 @@ protected function parseAuthors(array $authors): array } }); } - - /** - * @experimental Since the main configuration also uses arrays, the only thing this method really does is to rethrow any exceptions. - * - * @param array}> $items Where destination is a route key or an external URI. - * @return array}> - */ - protected function parseNavigationItems(array $items): array - { - return Arr::map($items, function (array $item): array { - try { - return Navigation::item(...$item); - } catch (Throwable $exception) { - throw new InvalidConfigurationException( - 'Invalid navigation item configuration detected the configuration file. Please double check the syntax.', - previous: $exception - ); - } - }); - } } diff --git a/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php b/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php index b9f6a3fc8fe..4bd0a733680 100644 --- a/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php +++ b/packages/framework/tests/Feature/YamlConfigurationFeatureTest.php @@ -501,17 +501,14 @@ public function testCanSetCustomNavigationItemsInTheYamlConfig() 'destination' => 'https://example.com', 'label' => 'Example', 'priority' => 100, - 'attributes' => [], ], [ 'destination' => 'about', 'label' => 'About Us', 'priority' => 200, - 'attributes' => [], ], [ 'destination' => 'contact', 'label' => 'Contact', 'priority' => 300, - 'attributes' => [], ], ], $configItems); @@ -615,9 +612,6 @@ public function testOnlyNeedToAddDestinationToYamlConfiguredNavigationItems() $this->assertSame([ [ 'destination' => 'about.html', - 'label' => null, - 'priority' => null, - 'attributes' => [], ], ], $configItems); @@ -675,6 +669,7 @@ public function testTypeErrorsInNavigationYamlConfigAreRethrownMoreHelpfully() try { $this->runBootstrappers(); + NavigationMenuGenerator::handle(MainNavigationMenu::class)->getItems()->all(); } catch (InvalidConfigurationException $exception) { $exceptionThrown = true; $this->assertSame('Invalid navigation item configuration detected the configuration file. Please double check the syntax.', $exception->getMessage()); @@ -697,6 +692,7 @@ public function testMustAddDestinationToYamlConfiguredNavigationItems() try { $this->runBootstrappers(); + NavigationMenuGenerator::handle(MainNavigationMenu::class)->getItems()->all(); } catch (InvalidConfigurationException $exception) { $exceptionThrown = true; $this->assertSame('Invalid navigation item configuration detected the configuration file. Please double check the syntax.', $exception->getMessage()); @@ -720,6 +716,7 @@ public function testAddingExtraYamlNavigationItemFieldsThrowsAnException() try { $this->runBootstrappers(); + NavigationMenuGenerator::handle(MainNavigationMenu::class)->getItems()->all(); } catch (InvalidConfigurationException $exception) { $exceptionThrown = true; $this->assertSame('Invalid navigation item configuration detected the configuration file. Please double check the syntax.', $exception->getMessage()); From 997a6ee47025be4f5c4ebc5fffff200f07612d37 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 21:11:00 +0200 Subject: [PATCH 063/232] Rename closure parameter --- .../Features/Navigation/NavigationMenuGenerator.php | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php b/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php index 8bcbb2c2f14..b97ecfbdf8b 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php @@ -83,10 +83,10 @@ protected function generate(): void $this->items->push(NavigationItem::create(DocumentationPage::home())); } } else { - collect(Config::getArray('hyde.navigation.custom', []))->each(function (array $item): void { - /** @var array{destination: string, label: ?string, priority: ?int, attributes: array} $item */ + collect(Config::getArray('hyde.navigation.custom', []))->each(function (array $data): void { + /** @var array{destination: string, label: ?string, priority: ?int, attributes: array} $data */ try { - $item = NavigationItem::create(...$item); + $item = NavigationItem::create(...$data); } catch (Throwable $exception) { throw new InvalidConfigurationException( 'Invalid navigation item configuration detected the configuration file. Please double check the syntax.', From 912f7b2b72f2697f8df0a57e12778b445c6dacda Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Wed, 10 Jul 2024 21:17:38 +0200 Subject: [PATCH 064/232] Extract experimental helper method to try parsing config values --- .../Internal/LoadYamlConfiguration.php | 12 ++---- .../InvalidConfigurationException.php | 14 +++++++ .../Navigation/NavigationMenuGenerator.php | 11 +---- .../tests/Unit/CustomExceptionsTest.php | 41 +++++++++++++++++++ 4 files changed, 60 insertions(+), 18 deletions(-) diff --git a/packages/framework/src/Foundation/Internal/LoadYamlConfiguration.php b/packages/framework/src/Foundation/Internal/LoadYamlConfiguration.php index 1f1dc4963e3..9ac4af5fa5b 100644 --- a/packages/framework/src/Foundation/Internal/LoadYamlConfiguration.php +++ b/packages/framework/src/Foundation/Internal/LoadYamlConfiguration.php @@ -4,7 +4,6 @@ namespace Hyde\Foundation\Internal; -use Throwable; use Illuminate\Support\Arr; use Hyde\Foundation\Application; use Illuminate\Config\Repository; @@ -67,14 +66,9 @@ protected function mergeConfiguration(string $namespace, array $yaml): void protected function parseAuthors(array $authors): array { return Arr::mapWithKeys($authors, function (array $author, string $username): array { - try { - return [$username => PostAuthor::create($author)]; - } catch (Throwable $exception) { - throw new InvalidConfigurationException( - 'Invalid author configuration detected in the YAML config file. Please double check the syntax.', - previous: $exception - ); - } + $message = 'Invalid author configuration detected in the YAML config file. Please double check the syntax.'; + + return InvalidConfigurationException::try(fn () => [$username => PostAuthor::create($author)], $message); }); } } diff --git a/packages/framework/src/Framework/Exceptions/InvalidConfigurationException.php b/packages/framework/src/Framework/Exceptions/InvalidConfigurationException.php index 694566ed717..306b6fd4a51 100644 --- a/packages/framework/src/Framework/Exceptions/InvalidConfigurationException.php +++ b/packages/framework/src/Framework/Exceptions/InvalidConfigurationException.php @@ -45,4 +45,18 @@ protected function findConfigLine(string $namespace, string $key): array return [$file, $line + 1]; } + + /** + * @internal + * + * @experimental + */ + public static function try(callable $callback, ?string $message = null): mixed + { + try { + return $callback(); + } catch (Throwable $exception) { + throw new static($message ?? $exception->getMessage(), previous: $exception); + } + } } diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php b/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php index b97ecfbdf8b..94976bcff51 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php @@ -5,7 +5,6 @@ namespace Hyde\Framework\Features\Navigation; use Hyde\Hyde; -use Throwable; use Hyde\Facades\Config; use Hyde\Support\Models\Route; use Hyde\Pages\DocumentationPage; @@ -85,14 +84,8 @@ protected function generate(): void } else { collect(Config::getArray('hyde.navigation.custom', []))->each(function (array $data): void { /** @var array{destination: string, label: ?string, priority: ?int, attributes: array} $data */ - try { - $item = NavigationItem::create(...$data); - } catch (Throwable $exception) { - throw new InvalidConfigurationException( - 'Invalid navigation item configuration detected the configuration file. Please double check the syntax.', - previous: $exception - ); - } + $message = 'Invalid navigation item configuration detected the configuration file. Please double check the syntax.'; + $item = InvalidConfigurationException::try(fn () => NavigationItem::create(...$data), $message); // Since these were added explicitly by the user, we can assume they should always be shown $this->items->push($item); diff --git a/packages/framework/tests/Unit/CustomExceptionsTest.php b/packages/framework/tests/Unit/CustomExceptionsTest.php index 6009a31bc4e..af058ac7390 100644 --- a/packages/framework/tests/Unit/CustomExceptionsTest.php +++ b/packages/framework/tests/Unit/CustomExceptionsTest.php @@ -210,4 +210,45 @@ public function testInvalidConfigurationExceptionWithPreviousThrowable() $this->assertSame('Invalid configuration.', $exception->getMessage()); $this->assertSame($previous, $exception->getPrevious()); } + + public function testInvalidConfigurationExceptionTryMethodWithSuccessfulCallback() + { + $result = InvalidConfigurationException::try(function () { + return 'success'; + }); + + $this->assertSame('success', $result); + } + + public function testInvalidConfigurationExceptionTryMethodWithThrowingCallback() + { + $this->expectException(InvalidConfigurationException::class); + $this->expectExceptionMessage('Custom error message'); + + InvalidConfigurationException::try(function () { + throw new RuntimeException('Original error'); + }, 'Custom error message'); + } + + public function testInvalidConfigurationExceptionTryMethodWithDefaultMessage() + { + $this->expectException(InvalidConfigurationException::class); + $this->expectExceptionMessage('Original error'); + + InvalidConfigurationException::try(function () { + throw new RuntimeException('Original error'); + }); + } + + public function testInvalidConfigurationExceptionTryMethodPreservesPreviousException() + { + try { + InvalidConfigurationException::try(function () { + throw new RuntimeException('Original error'); + }, 'Custom error message'); + } catch (InvalidConfigurationException $e) { + $this->assertInstanceOf(RuntimeException::class, $e->getPrevious()); + $this->assertSame('Original error', $e->getPrevious()->getMessage()); + } + } } From fabaf2920336f7cf5fcf3b66f741ebe76753b003 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 10:46:32 +0200 Subject: [PATCH 065/232] Draft builder method --- packages/framework/src/Facades/Navigation.php | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/packages/framework/src/Facades/Navigation.php b/packages/framework/src/Facades/Navigation.php index b2dda93d6c7..5dbad8c0459 100644 --- a/packages/framework/src/Facades/Navigation.php +++ b/packages/framework/src/Facades/Navigation.php @@ -28,4 +28,9 @@ public static function item(string $destination, ?string $label = null, ?int $pr { return compact('destination', 'label', 'priority', 'attributes'); } + + public static function builder() + { + // + } } From 7c896680e9544a1c68172bf515a53a88c8b61282 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 10:46:38 +0200 Subject: [PATCH 066/232] Draft method documentation --- packages/framework/src/Facades/Navigation.php | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/packages/framework/src/Facades/Navigation.php b/packages/framework/src/Facades/Navigation.php index 5dbad8c0459..fcad2f4fff8 100644 --- a/packages/framework/src/Facades/Navigation.php +++ b/packages/framework/src/Facades/Navigation.php @@ -29,6 +29,13 @@ public static function item(string $destination, ?string $label = null, ?int $pr return compact('destination', 'label', 'priority', 'attributes'); } + /** + * Configuration helper method to define the navigation menu configuration with better IDE support. + * + * The returned object will then be cast to an array that will be used by the framework to set the config data. + * + * @experimental This method is experimental and may change in the future. + */ public static function builder() { // From 7f395d9691df466dedf2827975deb1211b7c0907 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 10:47:03 +0200 Subject: [PATCH 067/232] Rename added builder method to define --- packages/framework/src/Facades/Navigation.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/framework/src/Facades/Navigation.php b/packages/framework/src/Facades/Navigation.php index fcad2f4fff8..7138c339722 100644 --- a/packages/framework/src/Facades/Navigation.php +++ b/packages/framework/src/Facades/Navigation.php @@ -36,7 +36,7 @@ public static function item(string $destination, ?string $label = null, ?int $pr * * @experimental This method is experimental and may change in the future. */ - public static function builder() + public static function define() { // } From 5415a91b4077503d41332964aed1b6eeb694bb5d Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 10:47:15 +0200 Subject: [PATCH 068/232] Rename added builder method to configure --- packages/framework/src/Facades/Navigation.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/framework/src/Facades/Navigation.php b/packages/framework/src/Facades/Navigation.php index 7138c339722..b43d205e52a 100644 --- a/packages/framework/src/Facades/Navigation.php +++ b/packages/framework/src/Facades/Navigation.php @@ -36,7 +36,7 @@ public static function item(string $destination, ?string $label = null, ?int $pr * * @experimental This method is experimental and may change in the future. */ - public static function define() + public static function configure() { // } From 2cbe18dacda323068f06fe915412eed92f66338d Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 10:48:53 +0200 Subject: [PATCH 069/232] Create NavigationMenuConfigurationBuilder.php --- .../Navigation/NavigationMenuConfigurationBuilder.php | 10 ++++++++++ 1 file changed, 10 insertions(+) create mode 100644 packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php new file mode 100644 index 00000000000..ad56ac7b08c --- /dev/null +++ b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php @@ -0,0 +1,10 @@ + Date: Thu, 11 Jul 2024 10:49:29 +0200 Subject: [PATCH 070/232] Draft the class documentation --- .../Navigation/NavigationMenuConfigurationBuilder.php | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php index ad56ac7b08c..d854f28f3fd 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php @@ -4,6 +4,13 @@ namespace Hyde\Framework\Features\Navigation; +/** + * Configuration helper method to define the navigation menu configuration with better IDE support. + * + * The configured object will be cast to an array that will be used by the framework to set the config data. + * + * @experimental This method is experimental and may change in the future. + */ class NavigationMenuConfigurationBuilder { // From 58f9b774d4c25707f3e9a5366aa9f211310a30ed Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 10:50:01 +0200 Subject: [PATCH 071/232] Return new navigation menu configuration builder --- packages/framework/src/Facades/Navigation.php | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/packages/framework/src/Facades/Navigation.php b/packages/framework/src/Facades/Navigation.php index b43d205e52a..00809edd5e1 100644 --- a/packages/framework/src/Facades/Navigation.php +++ b/packages/framework/src/Facades/Navigation.php @@ -4,6 +4,7 @@ namespace Hyde\Facades; +use Hyde\Framework\Features\Navigation\NavigationMenuConfigurationBuilder; use function compact; /** @@ -36,8 +37,8 @@ public static function item(string $destination, ?string $label = null, ?int $pr * * @experimental This method is experimental and may change in the future. */ - public static function configure() + public static function configure(): NavigationMenuConfigurationBuilder { - // + return new NavigationMenuConfigurationBuilder(); } } From 9ae9d6662d055e5473b53706e6862ab980868e74 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 10:50:39 +0200 Subject: [PATCH 072/232] Add protected config array --- .../Features/Navigation/NavigationMenuConfigurationBuilder.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php index d854f28f3fd..fd2577e3f71 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php @@ -13,5 +13,5 @@ */ class NavigationMenuConfigurationBuilder { - // + protected array $config = []; } From 4446fd1d09705fe207df61c5f7fc76acf406d9fa Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 10:51:21 +0200 Subject: [PATCH 073/232] Class NavigationMenuConfigurationBuilder extends ArrayObject --- .../Navigation/NavigationMenuConfigurationBuilder.php | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php index fd2577e3f71..53c6b082f60 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php @@ -4,6 +4,8 @@ namespace Hyde\Framework\Features\Navigation; +use ArrayObject; + /** * Configuration helper method to define the navigation menu configuration with better IDE support. * @@ -11,7 +13,7 @@ * * @experimental This method is experimental and may change in the future. */ -class NavigationMenuConfigurationBuilder +class NavigationMenuConfigurationBuilder extends ArrayObject { protected array $config = []; } From a456ff03d4cc4ae367a4f30a06a7b954dcb343cd Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 10:51:35 +0200 Subject: [PATCH 074/232] Class NavigationMenuConfigurationBuilder implements Arrayable --- .../Features/Navigation/NavigationMenuConfigurationBuilder.php | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php index 53c6b082f60..3c0218254a0 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php @@ -5,6 +5,7 @@ namespace Hyde\Framework\Features\Navigation; use ArrayObject; +use Illuminate\Contracts\Support\Arrayable; /** * Configuration helper method to define the navigation menu configuration with better IDE support. @@ -13,7 +14,7 @@ * * @experimental This method is experimental and may change in the future. */ -class NavigationMenuConfigurationBuilder extends ArrayObject +class NavigationMenuConfigurationBuilder extends ArrayObject implements Arrayable { protected array $config = []; } From 15abd0cb647f739b0b7d01aad73e100841616e86 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 10:52:01 +0200 Subject: [PATCH 075/232] Implement toArray() method --- .../Navigation/NavigationMenuConfigurationBuilder.php | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php index 3c0218254a0..5a7e3ef641c 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php @@ -17,4 +17,9 @@ class NavigationMenuConfigurationBuilder extends ArrayObject implements Arrayable { protected array $config = []; + + public function toArray(): array + { + return $this->config; + } } From 01080ddf1d11c7df555ac3064fea31d28719a2e0 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 10:55:34 +0200 Subject: [PATCH 076/232] Draft the builder methods --- .../NavigationMenuConfigurationBuilder.php | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php index 5a7e3ef641c..1d18227d409 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php @@ -22,4 +22,29 @@ public function toArray(): array { return $this->config; } + + public function order(array $order): static + { + // TODO: Implement order() method. + } + + public function labels(array $labels): static + { + // TODO: Implement labels() method. + } + + public function exclude(array $exclude): static + { + // TODO: Implement exclude() method. + } + + public function custom(array $custom): static + { + // TODO: Implement custom() method. + } + + public function subdirectoryDisplay(string $displayMode): static + { + // TODO: Implement subdirectoryDisplay() method. + } } From 1487cab2d09aaf614debc6d431d2ee12522a6c36 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 10:56:28 +0200 Subject: [PATCH 077/232] Add method descriptions --- .../NavigationMenuConfigurationBuilder.php | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php index 1d18227d409..806e2ef98ab 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php @@ -23,26 +23,41 @@ public function toArray(): array return $this->config; } + /** + * Set the order of the navigation items. + */ public function order(array $order): static { // TODO: Implement order() method. } + /** + * Set the labels for the navigation items. + */ public function labels(array $labels): static { // TODO: Implement labels() method. } + /** + * Exclude certain items from the navigation. + */ public function exclude(array $exclude): static { // TODO: Implement exclude() method. } + /** + * Add custom items to the navigation. + */ public function custom(array $custom): static { // TODO: Implement custom() method. } + /** + * Set the display mode for subdirectories. + */ public function subdirectoryDisplay(string $displayMode): static { // TODO: Implement subdirectoryDisplay() method. From 51ea211acfc98ce5760a70dd3d4a0b8383aa4e2e Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 10:56:50 +0200 Subject: [PATCH 078/232] Annotate fluent method return --- .../Navigation/NavigationMenuConfigurationBuilder.php | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php index 806e2ef98ab..0408ff7b696 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php @@ -25,6 +25,8 @@ public function toArray(): array /** * Set the order of the navigation items. + * + * @return $this */ public function order(array $order): static { @@ -33,6 +35,8 @@ public function order(array $order): static /** * Set the labels for the navigation items. + * + * @return $this */ public function labels(array $labels): static { @@ -41,6 +45,8 @@ public function labels(array $labels): static /** * Exclude certain items from the navigation. + * + * @return $this */ public function exclude(array $exclude): static { @@ -49,6 +55,8 @@ public function exclude(array $exclude): static /** * Add custom items to the navigation. + * + * @return $this */ public function custom(array $custom): static { @@ -57,6 +65,8 @@ public function custom(array $custom): static /** * Set the display mode for subdirectories. + * + * @return $this */ public function subdirectoryDisplay(string $displayMode): static { From 9ddc7aeabb242547d4b5980450776a6966a7ad6d Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 10:57:13 +0200 Subject: [PATCH 079/232] Prepare parameter annotations --- .../Navigation/NavigationMenuConfigurationBuilder.php | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php index 0408ff7b696..48c69871088 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php @@ -26,6 +26,7 @@ public function toArray(): array /** * Set the order of the navigation items. * + * @param array $order * @return $this */ public function order(array $order): static @@ -36,6 +37,7 @@ public function order(array $order): static /** * Set the labels for the navigation items. * + * @param array $labels * @return $this */ public function labels(array $labels): static @@ -46,6 +48,7 @@ public function labels(array $labels): static /** * Exclude certain items from the navigation. * + * @param array $exclude * @return $this */ public function exclude(array $exclude): static @@ -56,6 +59,7 @@ public function exclude(array $exclude): static /** * Add custom items to the navigation. * + * @param array $custom * @return $this */ public function custom(array $custom): static @@ -66,6 +70,7 @@ public function custom(array $custom): static /** * Set the display mode for subdirectories. * + * @param string $displayMode * @return $this */ public function subdirectoryDisplay(string $displayMode): static From 87936dea21b42fc53ef4863b6b3c21313a937f99 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 11:00:12 +0200 Subject: [PATCH 080/232] Annotate the parameter generics and enumerated types --- .../Navigation/NavigationMenuConfigurationBuilder.php | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php index 48c69871088..ebd0243b5de 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php @@ -26,7 +26,7 @@ public function toArray(): array /** * Set the order of the navigation items. * - * @param array $order + * @param array|array $order * @return $this */ public function order(array $order): static @@ -37,7 +37,7 @@ public function order(array $order): static /** * Set the labels for the navigation items. * - * @param array $labels + * @param array $labels * @return $this */ public function labels(array $labels): static @@ -48,7 +48,7 @@ public function labels(array $labels): static /** * Exclude certain items from the navigation. * - * @param array $exclude + * @param array $exclude * @return $this */ public function exclude(array $exclude): static @@ -59,7 +59,7 @@ public function exclude(array $exclude): static /** * Add custom items to the navigation. * - * @param array $custom + * @param array}> $custom * @return $this */ public function custom(array $custom): static @@ -70,7 +70,7 @@ public function custom(array $custom): static /** * Set the display mode for subdirectories. * - * @param string $displayMode + * @param 'dropdown'|'flat'|'hidden' $displayMode * @return $this */ public function subdirectoryDisplay(string $displayMode): static From 5328cf7b9db584aeb59044d8728b0be67d3672b3 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 11:00:37 +0200 Subject: [PATCH 081/232] Move down the toArray method --- .../Navigation/NavigationMenuConfigurationBuilder.php | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php index ebd0243b5de..62f76bf0d1d 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php @@ -18,11 +18,6 @@ class NavigationMenuConfigurationBuilder extends ArrayObject implements Arrayabl { protected array $config = []; - public function toArray(): array - { - return $this->config; - } - /** * Set the order of the navigation items. * @@ -77,4 +72,9 @@ public function subdirectoryDisplay(string $displayMode): static { // TODO: Implement subdirectoryDisplay() method. } + + public function toArray(): array + { + return $this->config; + } } From 118eb177d3a5cbec8dae08e4f6828f4c4c2f9a2a Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 11:02:20 +0200 Subject: [PATCH 082/232] Implement the builder methods --- .../NavigationMenuConfigurationBuilder.php | 20 ++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php index 62f76bf0d1d..7fea0a56c8f 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php @@ -26,7 +26,9 @@ class NavigationMenuConfigurationBuilder extends ArrayObject implements Arrayabl */ public function order(array $order): static { - // TODO: Implement order() method. + $this->config['order'] = $order; + + return $this; } /** @@ -37,7 +39,9 @@ public function order(array $order): static */ public function labels(array $labels): static { - // TODO: Implement labels() method. + $this->config['labels'] = $labels; + + return $this; } /** @@ -48,7 +52,9 @@ public function labels(array $labels): static */ public function exclude(array $exclude): static { - // TODO: Implement exclude() method. + $this->config['exclude'] = $exclude; + + return $this; } /** @@ -59,7 +65,9 @@ public function exclude(array $exclude): static */ public function custom(array $custom): static { - // TODO: Implement custom() method. + $this->config['custom'] = $custom; + + return $this; } /** @@ -70,7 +78,9 @@ public function custom(array $custom): static */ public function subdirectoryDisplay(string $displayMode): static { - // TODO: Implement subdirectoryDisplay() method. + $this->config['subdirectory_display'] = $displayMode; + + return $this; } public function toArray(): array From 283852aae2541fe12c5d16cf784c96a71055387d Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 11:02:56 +0200 Subject: [PATCH 083/232] Create NavigationMenuConfigurationBuilderTest.php --- .../NavigationMenuConfigurationBuilderTest.php | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) create mode 100644 packages/framework/tests/Unit/NavigationMenuConfigurationBuilderTest.php diff --git a/packages/framework/tests/Unit/NavigationMenuConfigurationBuilderTest.php b/packages/framework/tests/Unit/NavigationMenuConfigurationBuilderTest.php new file mode 100644 index 00000000000..c3e7125dece --- /dev/null +++ b/packages/framework/tests/Unit/NavigationMenuConfigurationBuilderTest.php @@ -0,0 +1,16 @@ +assertTrue(true); + } +} From 5a48d0a83e1721728b73142ed9c3673edf5d42b8 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 11:06:58 +0200 Subject: [PATCH 084/232] Generate unit test with Claude --- ...NavigationMenuConfigurationBuilderTest.php | 134 +++++++++++++++++- 1 file changed, 132 insertions(+), 2 deletions(-) diff --git a/packages/framework/tests/Unit/NavigationMenuConfigurationBuilderTest.php b/packages/framework/tests/Unit/NavigationMenuConfigurationBuilderTest.php index c3e7125dece..900e44875e4 100644 --- a/packages/framework/tests/Unit/NavigationMenuConfigurationBuilderTest.php +++ b/packages/framework/tests/Unit/NavigationMenuConfigurationBuilderTest.php @@ -3,14 +3,144 @@ declare(strict_types=1); use Hyde\Testing\UnitTestCase; +use Hyde\Framework\Features\Navigation\NavigationMenuConfigurationBuilder; +use Hyde\Facades\Navigation; /** * @covers \Hyde\Framework\Features\Navigation\NavigationMenuConfigurationBuilder */ class NavigationMenuConfigurationBuilderTest extends UnitTestCase { - public function testExample() + private NavigationMenuConfigurationBuilder $builder; + + protected function setUp(): void + { + parent::setUp(); + $this->builder = new NavigationMenuConfigurationBuilder(); + } + + public function testOrder() + { + $order = ['index' => 0, 'posts' => 10, 'docs/index' => 100]; + $result = $this->builder->order($order)->toArray(); + + $this->assertArrayHasKey('order', $result); + $this->assertEquals($order, $result['order']); + } + + public function testLabels() + { + $labels = ['index' => 'Home', 'docs/index' => 'Docs']; + $result = $this->builder->labels($labels)->toArray(); + + $this->assertArrayHasKey('labels', $result); + $this->assertEquals($labels, $result['labels']); + } + + public function testExclude() + { + $exclude = ['404', 'admin']; + $result = $this->builder->exclude($exclude)->toArray(); + + $this->assertArrayHasKey('exclude', $result); + $this->assertEquals($exclude, $result['exclude']); + } + + public function testCustom() + { + $custom = [ + Navigation::item('https://example.com', 'Example', 200), + Navigation::item('https://github.com', 'GitHub', 300), + ]; + $result = $this->builder->custom($custom)->toArray(); + + $this->assertArrayHasKey('custom', $result); + $this->assertEquals($custom, $result['custom']); + } + + public function testSubdirectoryDisplay() + { + $displayModes = ['dropdown', 'flat', 'hidden']; + + foreach ($displayModes as $mode) { + $result = $this->builder->subdirectoryDisplay($mode)->toArray(); + + $this->assertArrayHasKey('subdirectory_display', $result); + $this->assertEquals($mode, $result['subdirectory_display']); + } + } + + public function testChainedMethods() + { + $result = $this->builder + ->order(['index' => 0, 'posts' => 10]) + ->labels(['index' => 'Home']) + ->exclude(['404']) + ->custom([Navigation::item('https://github.com', 'GitHub', 200)]) + ->subdirectoryDisplay('dropdown') + ->toArray(); + + $this->assertArrayHasKey('order', $result); + $this->assertArrayHasKey('labels', $result); + $this->assertArrayHasKey('exclude', $result); + $this->assertArrayHasKey('custom', $result); + $this->assertArrayHasKey('subdirectory_display', $result); + } + + public function testEmptyConfiguration() + { + $result = $this->builder->toArray(); + + $this->assertEmpty($result); + } + + public function testInvalidSubdirectoryDisplay() + { + $this->expectException(\TypeError::class); + $this->builder->subdirectoryDisplay('invalid'); + } + + public function testRealLifeUsageScenario() + { + $result = $this->builder + ->order([ + 'index' => 0, + 'posts' => 10, + 'docs/index' => 100, + ]) + ->labels([ + 'index' => 'Home', + 'docs/index' => 'Docs', + ]) + ->exclude([ + '404', + ]) + ->custom([ + Navigation::item('https://github.com/hydephp/hyde', 'GitHub', 200), + ]) + ->subdirectoryDisplay('dropdown') + ->toArray(); + + $this->assertEquals([ + 'order' => ['index' => 0, 'posts' => 10, 'docs/index' => 100], + 'labels' => ['index' => 'Home', 'docs/index' => 'Docs'], + 'exclude' => ['404'], + 'custom' => [ + ['destination' => 'https://github.com/hydephp/hyde', 'label' => 'GitHub', 'priority' => 200, 'attributes' => []], + ], + 'subdirectory_display' => 'dropdown', + ], $result); + } + + public function testArrayableInterface() + { + $this->assertInstanceOf(\Illuminate\Contracts\Support\Arrayable::class, $this->builder); + } + + public function testArrayObjectMethods() { - $this->assertTrue(true); + $this->builder->order(['index' => 0]); + $this->assertCount(1, $this->builder); + $this->assertEquals(['order' => ['index' => 0]], $this->builder->getArrayCopy()); } } From 289ef291366beebb447f770ac2d05a2c00e94a43 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 11:28:25 +0200 Subject: [PATCH 085/232] Test the added facade method --- .../Unit/Facades/NavigationFacadeTest.php | 47 +++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/packages/framework/tests/Unit/Facades/NavigationFacadeTest.php b/packages/framework/tests/Unit/Facades/NavigationFacadeTest.php index a4b68d9f7c4..d16fa71c776 100644 --- a/packages/framework/tests/Unit/Facades/NavigationFacadeTest.php +++ b/packages/framework/tests/Unit/Facades/NavigationFacadeTest.php @@ -6,6 +6,7 @@ use Hyde\Facades\Navigation; use Hyde\Testing\UnitTestCase; +use Hyde\Framework\Features\Navigation\NavigationMenuConfigurationBuilder; /** * @covers \Hyde\Facades\Navigation @@ -47,4 +48,50 @@ public function testItemWithUrl() 'attributes' => [], ], $item); } + + public function testConfigure() + { + $builder = Navigation::configure(); + + $this->assertInstanceOf(NavigationMenuConfigurationBuilder::class, $builder); + } + + public function testConfigureWithChainedMethods() + { + $config = Navigation::configure() + ->order(['index' => 0, 'posts' => 10]) + ->labels(['index' => 'Home']) + ->exclude(['404']) + ->custom([Navigation::item('https://github.com', 'GitHub', 200)]) + ->subdirectoryDisplay('dropdown') + ->toArray(); + + $this->assertIsArray($config); + $this->assertArrayHasKey('order', $config); + $this->assertArrayHasKey('labels', $config); + $this->assertArrayHasKey('exclude', $config); + $this->assertArrayHasKey('custom', $config); + $this->assertArrayHasKey('subdirectory_display', $config); + + $this->assertEquals(['index' => 0, 'posts' => 10], $config['order']); + $this->assertEquals(['index' => 'Home'], $config['labels']); + $this->assertEquals(['404'], $config['exclude']); + $this->assertEquals([Navigation::item('https://github.com', 'GitHub', 200)], $config['custom']); + $this->assertEquals('dropdown', $config['subdirectory_display']); + } + + public function testConfigureWithSomeChainedMethods() + { + $config = Navigation::configure() + ->order(['about' => 1, 'contact' => 2]) + ->labels(['about' => 'About Us']) + ->subdirectoryDisplay('flat') + ->toArray(); + + $this->assertEquals(['about' => 1, 'contact' => 2], $config['order']); + $this->assertEquals(['about' => 'About Us'], $config['labels']); + $this->assertEquals('flat', $config['subdirectory_display']); + $this->assertArrayNotHasKey('exclude', $config); + $this->assertArrayNotHasKey('custom', $config); + } } From 073faa76614ca1a2e18626d89482e0852ea78331 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 11:10:46 +0200 Subject: [PATCH 086/232] Skip test for not implemented feature --- .../tests/Unit/NavigationMenuConfigurationBuilderTest.php | 2 ++ 1 file changed, 2 insertions(+) diff --git a/packages/framework/tests/Unit/NavigationMenuConfigurationBuilderTest.php b/packages/framework/tests/Unit/NavigationMenuConfigurationBuilderTest.php index 900e44875e4..b7c6d608220 100644 --- a/packages/framework/tests/Unit/NavigationMenuConfigurationBuilderTest.php +++ b/packages/framework/tests/Unit/NavigationMenuConfigurationBuilderTest.php @@ -96,6 +96,8 @@ public function testEmptyConfiguration() public function testInvalidSubdirectoryDisplay() { + $this->markTestSkipped('Not yet implemented'); + $this->expectException(\TypeError::class); $this->builder->subdirectoryDisplay('invalid'); } From 121159fb4402db3cdc2ce85540bd9f9892fe6507 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 11:11:11 +0200 Subject: [PATCH 087/232] Construct with the config property --- .../Navigation/NavigationMenuConfigurationBuilder.php | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php index 7fea0a56c8f..9ddb26ed3e9 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php @@ -18,6 +18,11 @@ class NavigationMenuConfigurationBuilder extends ArrayObject implements Arrayabl { protected array $config = []; + public function __construct() + { + parent::__construct($this->config); + } + /** * Set the order of the navigation items. * From 374c5291c58e490f353806d6524c76284b05a3ec Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 11:11:19 +0200 Subject: [PATCH 088/232] Construct with array object flags --- .../Features/Navigation/NavigationMenuConfigurationBuilder.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php index 9ddb26ed3e9..e4c59ea5e49 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php @@ -20,7 +20,7 @@ class NavigationMenuConfigurationBuilder extends ArrayObject implements Arrayabl public function __construct() { - parent::__construct($this->config); + parent::__construct($this->config, ArrayObject::ARRAY_AS_PROPS | ArrayObject::STD_PROP_LIST); } /** From 5118abea3a92f957aea2ac9a493de500b95d28f1 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 11:11:22 +0200 Subject: [PATCH 089/232] Revert "Construct with array object flags" This reverts commit 38743f97f0479b3716abcd7af674ae06559c6ffa. --- .../Features/Navigation/NavigationMenuConfigurationBuilder.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php index e4c59ea5e49..9ddb26ed3e9 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php @@ -20,7 +20,7 @@ class NavigationMenuConfigurationBuilder extends ArrayObject implements Arrayabl public function __construct() { - parent::__construct($this->config, ArrayObject::ARRAY_AS_PROPS | ArrayObject::STD_PROP_LIST); + parent::__construct($this->config); } /** From 6c60b5d2e7793354ce7734d4c9d6dd55da752839 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 11:11:26 +0200 Subject: [PATCH 090/232] Revert "Construct with the config property" This reverts commit 808b437352dbd22465288b965d651246e3f7a40c. --- .../Navigation/NavigationMenuConfigurationBuilder.php | 5 ----- 1 file changed, 5 deletions(-) diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php index 9ddb26ed3e9..7fea0a56c8f 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php @@ -18,11 +18,6 @@ class NavigationMenuConfigurationBuilder extends ArrayObject implements Arrayabl { protected array $config = []; - public function __construct() - { - parent::__construct($this->config); - } - /** * Set the order of the navigation items. * From ee6eac0b4b49c24a326cea5bdea40a0031c4045e Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 11:11:53 +0200 Subject: [PATCH 091/232] Fix typo in description --- .../Features/Navigation/NavigationMenuConfigurationBuilder.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php index 7fea0a56c8f..102346a0507 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php @@ -8,7 +8,7 @@ use Illuminate\Contracts\Support\Arrayable; /** - * Configuration helper method to define the navigation menu configuration with better IDE support. + * Configuration helper class to define the navigation menu configuration with better IDE support. * * The configured object will be cast to an array that will be used by the framework to set the config data. * From 413c12c68d216e79d6f271b021c6ff28af86535f Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 11:12:13 +0200 Subject: [PATCH 092/232] Fix typo in description --- .../Features/Navigation/NavigationMenuConfigurationBuilder.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php index 102346a0507..588d4a8599e 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php @@ -12,7 +12,7 @@ * * The configured object will be cast to an array that will be used by the framework to set the config data. * - * @experimental This method is experimental and may change in the future. + * @experimental This class is experimental and may change in the future. */ class NavigationMenuConfigurationBuilder extends ArrayObject implements Arrayable { From aff25115bee6184a99c1c79f7724ad1b0ebf8349 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 11:13:06 +0200 Subject: [PATCH 093/232] Refactor the class to property utilise the array object features --- .../NavigationMenuConfigurationBuilder.php | 14 ++++++-------- .../NavigationMenuConfigurationBuilderTest.php | 7 ++++++- 2 files changed, 12 insertions(+), 9 deletions(-) diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php index 588d4a8599e..c85dd24173b 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php @@ -16,8 +16,6 @@ */ class NavigationMenuConfigurationBuilder extends ArrayObject implements Arrayable { - protected array $config = []; - /** * Set the order of the navigation items. * @@ -26,7 +24,7 @@ class NavigationMenuConfigurationBuilder extends ArrayObject implements Arrayabl */ public function order(array $order): static { - $this->config['order'] = $order; + $this['order'] = $order; return $this; } @@ -39,7 +37,7 @@ public function order(array $order): static */ public function labels(array $labels): static { - $this->config['labels'] = $labels; + $this['labels'] = $labels; return $this; } @@ -52,7 +50,7 @@ public function labels(array $labels): static */ public function exclude(array $exclude): static { - $this->config['exclude'] = $exclude; + $this['exclude'] = $exclude; return $this; } @@ -65,7 +63,7 @@ public function exclude(array $exclude): static */ public function custom(array $custom): static { - $this->config['custom'] = $custom; + $this['custom'] = $custom; return $this; } @@ -78,13 +76,13 @@ public function custom(array $custom): static */ public function subdirectoryDisplay(string $displayMode): static { - $this->config['subdirectory_display'] = $displayMode; + $this['subdirectory_display'] = $displayMode; return $this; } public function toArray(): array { - return $this->config; + return $this->getArrayCopy(); } } diff --git a/packages/framework/tests/Unit/NavigationMenuConfigurationBuilderTest.php b/packages/framework/tests/Unit/NavigationMenuConfigurationBuilderTest.php index b7c6d608220..a31ceb06bb0 100644 --- a/packages/framework/tests/Unit/NavigationMenuConfigurationBuilderTest.php +++ b/packages/framework/tests/Unit/NavigationMenuConfigurationBuilderTest.php @@ -139,10 +139,15 @@ public function testArrayableInterface() $this->assertInstanceOf(\Illuminate\Contracts\Support\Arrayable::class, $this->builder); } - public function testArrayObjectMethods() + public function testArrayObjectBehavior() { $this->builder->order(['index' => 0]); + + // ArrayObject methods now operate on the configuration data $this->assertCount(1, $this->builder); $this->assertEquals(['order' => ['index' => 0]], $this->builder->getArrayCopy()); + + // toArray() method should return the same result + $this->assertEquals(['order' => ['index' => 0]], $this->builder->toArray()); } } From 97bb4f95f9a0053a73195c1590146943f60ea4e8 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 11:14:12 +0200 Subject: [PATCH 094/232] Replace qualifier with an import --- .../tests/Unit/NavigationMenuConfigurationBuilderTest.php | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/packages/framework/tests/Unit/NavigationMenuConfigurationBuilderTest.php b/packages/framework/tests/Unit/NavigationMenuConfigurationBuilderTest.php index a31ceb06bb0..15124bc1ea9 100644 --- a/packages/framework/tests/Unit/NavigationMenuConfigurationBuilderTest.php +++ b/packages/framework/tests/Unit/NavigationMenuConfigurationBuilderTest.php @@ -3,6 +3,7 @@ declare(strict_types=1); use Hyde\Testing\UnitTestCase; +use Illuminate\Contracts\Support\Arrayable; use Hyde\Framework\Features\Navigation\NavigationMenuConfigurationBuilder; use Hyde\Facades\Navigation; @@ -136,7 +137,7 @@ public function testRealLifeUsageScenario() public function testArrayableInterface() { - $this->assertInstanceOf(\Illuminate\Contracts\Support\Arrayable::class, $this->builder); + $this->assertInstanceOf(Arrayable::class, $this->builder); } public function testArrayObjectBehavior() From 599abdc3931d94280ccee0bbf72e1fd3c414d3bf Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 11:24:58 +0200 Subject: [PATCH 095/232] Document the array shape returns --- .../Navigation/NavigationMenuConfigurationBuilder.php | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php index c85dd24173b..6741439fa0d 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php @@ -81,6 +81,11 @@ public function subdirectoryDisplay(string $displayMode): static return $this; } + /** + * Get the instance as an array. + * + * @return array{order: array, labels: array, exclude: array, custom: array}>, subdirectory_display: string} + */ public function toArray(): array { return $this->getArrayCopy(); From b5cc7ed813dbec93ce887293b0382b6c6957e0de Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 11:29:21 +0200 Subject: [PATCH 096/232] Use assert same for scalar comparisons --- .../tests/Unit/Facades/NavigationFacadeTest.php | 16 ++++++++-------- .../NavigationMenuConfigurationBuilderTest.php | 16 ++++++++-------- 2 files changed, 16 insertions(+), 16 deletions(-) diff --git a/packages/framework/tests/Unit/Facades/NavigationFacadeTest.php b/packages/framework/tests/Unit/Facades/NavigationFacadeTest.php index d16fa71c776..f101a28263b 100644 --- a/packages/framework/tests/Unit/Facades/NavigationFacadeTest.php +++ b/packages/framework/tests/Unit/Facades/NavigationFacadeTest.php @@ -73,11 +73,11 @@ public function testConfigureWithChainedMethods() $this->assertArrayHasKey('custom', $config); $this->assertArrayHasKey('subdirectory_display', $config); - $this->assertEquals(['index' => 0, 'posts' => 10], $config['order']); - $this->assertEquals(['index' => 'Home'], $config['labels']); - $this->assertEquals(['404'], $config['exclude']); - $this->assertEquals([Navigation::item('https://github.com', 'GitHub', 200)], $config['custom']); - $this->assertEquals('dropdown', $config['subdirectory_display']); + $this->assertSame(['index' => 0, 'posts' => 10], $config['order']); + $this->assertSame(['index' => 'Home'], $config['labels']); + $this->assertSame(['404'], $config['exclude']); + $this->assertSame([Navigation::item('https://github.com', 'GitHub', 200)], $config['custom']); + $this->assertSame('dropdown', $config['subdirectory_display']); } public function testConfigureWithSomeChainedMethods() @@ -88,9 +88,9 @@ public function testConfigureWithSomeChainedMethods() ->subdirectoryDisplay('flat') ->toArray(); - $this->assertEquals(['about' => 1, 'contact' => 2], $config['order']); - $this->assertEquals(['about' => 'About Us'], $config['labels']); - $this->assertEquals('flat', $config['subdirectory_display']); + $this->assertSame(['about' => 1, 'contact' => 2], $config['order']); + $this->assertSame(['about' => 'About Us'], $config['labels']); + $this->assertSame('flat', $config['subdirectory_display']); $this->assertArrayNotHasKey('exclude', $config); $this->assertArrayNotHasKey('custom', $config); } diff --git a/packages/framework/tests/Unit/NavigationMenuConfigurationBuilderTest.php b/packages/framework/tests/Unit/NavigationMenuConfigurationBuilderTest.php index 15124bc1ea9..199c45b634d 100644 --- a/packages/framework/tests/Unit/NavigationMenuConfigurationBuilderTest.php +++ b/packages/framework/tests/Unit/NavigationMenuConfigurationBuilderTest.php @@ -26,7 +26,7 @@ public function testOrder() $result = $this->builder->order($order)->toArray(); $this->assertArrayHasKey('order', $result); - $this->assertEquals($order, $result['order']); + $this->assertSame($order, $result['order']); } public function testLabels() @@ -35,7 +35,7 @@ public function testLabels() $result = $this->builder->labels($labels)->toArray(); $this->assertArrayHasKey('labels', $result); - $this->assertEquals($labels, $result['labels']); + $this->assertSame($labels, $result['labels']); } public function testExclude() @@ -44,7 +44,7 @@ public function testExclude() $result = $this->builder->exclude($exclude)->toArray(); $this->assertArrayHasKey('exclude', $result); - $this->assertEquals($exclude, $result['exclude']); + $this->assertSame($exclude, $result['exclude']); } public function testCustom() @@ -56,7 +56,7 @@ public function testCustom() $result = $this->builder->custom($custom)->toArray(); $this->assertArrayHasKey('custom', $result); - $this->assertEquals($custom, $result['custom']); + $this->assertSame($custom, $result['custom']); } public function testSubdirectoryDisplay() @@ -67,7 +67,7 @@ public function testSubdirectoryDisplay() $result = $this->builder->subdirectoryDisplay($mode)->toArray(); $this->assertArrayHasKey('subdirectory_display', $result); - $this->assertEquals($mode, $result['subdirectory_display']); + $this->assertSame($mode, $result['subdirectory_display']); } } @@ -124,7 +124,7 @@ public function testRealLifeUsageScenario() ->subdirectoryDisplay('dropdown') ->toArray(); - $this->assertEquals([ + $this->assertSame([ 'order' => ['index' => 0, 'posts' => 10, 'docs/index' => 100], 'labels' => ['index' => 'Home', 'docs/index' => 'Docs'], 'exclude' => ['404'], @@ -146,9 +146,9 @@ public function testArrayObjectBehavior() // ArrayObject methods now operate on the configuration data $this->assertCount(1, $this->builder); - $this->assertEquals(['order' => ['index' => 0]], $this->builder->getArrayCopy()); + $this->assertSame(['order' => ['index' => 0]], $this->builder->getArrayCopy()); // toArray() method should return the same result - $this->assertEquals(['order' => ['index' => 0]], $this->builder->toArray()); + $this->assertSame(['order' => ['index' => 0]], $this->builder->toArray()); } } From 1029dc1a5a88ed2d29f555dc30bb836615f85f41 Mon Sep 17 00:00:00 2001 From: StyleCI Bot Date: Thu, 11 Jul 2024 09:25:50 +0000 Subject: [PATCH 097/232] Apply fixes from StyleCI --- packages/framework/src/Facades/Navigation.php | 1 + .../Navigation/NavigationMenuConfigurationBuilder.php | 10 +++++----- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/packages/framework/src/Facades/Navigation.php b/packages/framework/src/Facades/Navigation.php index 00809edd5e1..b6294e06e16 100644 --- a/packages/framework/src/Facades/Navigation.php +++ b/packages/framework/src/Facades/Navigation.php @@ -5,6 +5,7 @@ namespace Hyde\Facades; use Hyde\Framework\Features\Navigation\NavigationMenuConfigurationBuilder; + use function compact; /** diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php index 6741439fa0d..b28ca750daa 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php @@ -19,7 +19,7 @@ class NavigationMenuConfigurationBuilder extends ArrayObject implements Arrayabl /** * Set the order of the navigation items. * - * @param array|array $order + * @param array|array $order * @return $this */ public function order(array $order): static @@ -32,7 +32,7 @@ public function order(array $order): static /** * Set the labels for the navigation items. * - * @param array $labels + * @param array $labels * @return $this */ public function labels(array $labels): static @@ -45,7 +45,7 @@ public function labels(array $labels): static /** * Exclude certain items from the navigation. * - * @param array $exclude + * @param array $exclude * @return $this */ public function exclude(array $exclude): static @@ -58,7 +58,7 @@ public function exclude(array $exclude): static /** * Add custom items to the navigation. * - * @param array}> $custom + * @param array}> $custom * @return $this */ public function custom(array $custom): static @@ -71,7 +71,7 @@ public function custom(array $custom): static /** * Set the display mode for subdirectories. * - * @param 'dropdown'|'flat'|'hidden' $displayMode + * @param 'dropdown'|'flat'|'hidden' $displayMode * @return $this */ public function subdirectoryDisplay(string $displayMode): static From 7e9681e830748af23363baf183e6d2b9a5ce7c41 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 11:30:28 +0200 Subject: [PATCH 098/232] Remove unnecessary comment --- .../tests/Unit/NavigationMenuConfigurationBuilderTest.php | 1 - 1 file changed, 1 deletion(-) diff --git a/packages/framework/tests/Unit/NavigationMenuConfigurationBuilderTest.php b/packages/framework/tests/Unit/NavigationMenuConfigurationBuilderTest.php index 199c45b634d..dbfaa54ee60 100644 --- a/packages/framework/tests/Unit/NavigationMenuConfigurationBuilderTest.php +++ b/packages/framework/tests/Unit/NavigationMenuConfigurationBuilderTest.php @@ -144,7 +144,6 @@ public function testArrayObjectBehavior() { $this->builder->order(['index' => 0]); - // ArrayObject methods now operate on the configuration data $this->assertCount(1, $this->builder); $this->assertSame(['order' => ['index' => 0]], $this->builder->getArrayCopy()); From 6432901382ecc963bd315c9bd7c8ccf7cf400830 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 11:31:35 +0200 Subject: [PATCH 099/232] Split out assertion to dedicated test method --- .../tests/Unit/NavigationMenuConfigurationBuilderTest.php | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/packages/framework/tests/Unit/NavigationMenuConfigurationBuilderTest.php b/packages/framework/tests/Unit/NavigationMenuConfigurationBuilderTest.php index dbfaa54ee60..2419ecf1c24 100644 --- a/packages/framework/tests/Unit/NavigationMenuConfigurationBuilderTest.php +++ b/packages/framework/tests/Unit/NavigationMenuConfigurationBuilderTest.php @@ -146,8 +146,12 @@ public function testArrayObjectBehavior() $this->assertCount(1, $this->builder); $this->assertSame(['order' => ['index' => 0]], $this->builder->getArrayCopy()); + } + + public function testToArrayMethodReturnsSameResultAsArrayObject() + { + $this->builder->order(['index' => 0]); - // toArray() method should return the same result $this->assertSame(['order' => ['index' => 0]], $this->builder->toArray()); } } From 9c1afcf9508ee425df7314884cb1ce21e790bfc8 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 11:33:00 +0200 Subject: [PATCH 100/232] Revert "Skip test for not implemented feature" This reverts commit 073faa76614ca1a2e18626d89482e0852ea78331. --- .../tests/Unit/NavigationMenuConfigurationBuilderTest.php | 2 -- 1 file changed, 2 deletions(-) diff --git a/packages/framework/tests/Unit/NavigationMenuConfigurationBuilderTest.php b/packages/framework/tests/Unit/NavigationMenuConfigurationBuilderTest.php index 2419ecf1c24..e93c3dd3b72 100644 --- a/packages/framework/tests/Unit/NavigationMenuConfigurationBuilderTest.php +++ b/packages/framework/tests/Unit/NavigationMenuConfigurationBuilderTest.php @@ -97,8 +97,6 @@ public function testEmptyConfiguration() public function testInvalidSubdirectoryDisplay() { - $this->markTestSkipped('Not yet implemented'); - $this->expectException(\TypeError::class); $this->builder->subdirectoryDisplay('invalid'); } From 2842aebf136f48bd424159bdd5b0ef02271d3f3b Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 11:33:29 +0200 Subject: [PATCH 101/232] Assert the enumerated string type --- .../Navigation/NavigationMenuConfigurationBuilder.php | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php index b28ca750daa..1056bf016f8 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php @@ -4,6 +4,7 @@ namespace Hyde\Framework\Features\Navigation; +use TypeError; use ArrayObject; use Illuminate\Contracts\Support\Arrayable; @@ -76,6 +77,8 @@ public function custom(array $custom): static */ public function subdirectoryDisplay(string $displayMode): static { + self::assertType(['dropdown', 'flat', 'hidden'], $displayMode); + $this['subdirectory_display'] = $displayMode; return $this; @@ -90,4 +93,12 @@ public function toArray(): array { return $this->getArrayCopy(); } + + /** @internal */ + protected static function assertType(array $types, string $value): void + { + if (! in_array($value, $types)) { + throw new TypeError('Value must be one of: '.implode(', ', $types)); + } + } } From bd3595470d48607b39bbab992c5c343b72bb4d4a Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 11:33:57 +0200 Subject: [PATCH 102/232] Replace internal marker for already internal method with experimental --- .../Features/Navigation/NavigationMenuConfigurationBuilder.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php index 1056bf016f8..2d031badd16 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php @@ -94,7 +94,7 @@ public function toArray(): array return $this->getArrayCopy(); } - /** @internal */ + /** @experimental May be moved to a separate helper class in the future. */ protected static function assertType(array $types, string $value): void { if (! in_array($value, $types)) { From d0c9c1c9d5ed2f89f7fc04d1de58685f27e092bb Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 11:53:30 +0200 Subject: [PATCH 103/232] Improve the configuration method documentation --- .../Navigation/NavigationMenuConfigurationBuilder.php | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php index 2d031badd16..621a0a109c6 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php @@ -20,6 +20,8 @@ class NavigationMenuConfigurationBuilder extends ArrayObject implements Arrayabl /** * Set the order of the navigation items. * + * Either define a map of route keys to priorities, or just a list of route keys and we'll try to match that order. + * * @param array|array $order * @return $this */ @@ -33,6 +35,8 @@ public function order(array $order): static /** * Set the labels for the navigation items. * + * Each key should be a route key, and the value should be the label to display. + * * @param array $labels * @return $this */ @@ -46,6 +50,8 @@ public function labels(array $labels): static /** * Exclude certain items from the navigation. * + * Each item should be a route key for the page to exclude. + * * @param array $exclude * @return $this */ @@ -59,6 +65,8 @@ public function exclude(array $exclude): static /** * Add custom items to the navigation. * + * @example `[Navigation::item('https://github.com/hydephp/hyde', 'GitHub', 200, ['target' => '_blank'])]` + * * @param array}> $custom * @return $this */ @@ -72,6 +80,8 @@ public function custom(array $custom): static /** * Set the display mode for subdirectories. * + * You can choose between 'dropdown', 'flat', and 'hidden'. + * * @param 'dropdown'|'flat'|'hidden' $displayMode * @return $this */ From 80ae091dfe97beff26a28fefb66e12bb57e833da Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 13:49:21 +0200 Subject: [PATCH 104/232] Test can configure main menu using array settings --- .../AutomaticNavigationConfigurationsTest.php | 55 +++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/packages/framework/tests/Feature/AutomaticNavigationConfigurationsTest.php b/packages/framework/tests/Feature/AutomaticNavigationConfigurationsTest.php index ab6939903ba..34784461c8c 100644 --- a/packages/framework/tests/Feature/AutomaticNavigationConfigurationsTest.php +++ b/packages/framework/tests/Feature/AutomaticNavigationConfigurationsTest.php @@ -1234,6 +1234,61 @@ public function testSidebarGroupCasingUsingFrontMatter() $this->assertSidebarEquals(['Hello World'], [new DocumentationPage('foo', ['navigation.group' => 'hello world'])]); } + // Configuration tests + + public function testCanConfigureMainMenuUsingArraySettings() + { + $config = [ + 'navigation' => [ + 'order' => [ + 'foo' => 3, + 'bar' => 2, + 'baz' => 1, + ], + + 'labels' => [ + 'foo' => 'Foo Page', + 'bar' => 'Bar Page', + 'baz' => 'Baz Page', + 'dropdown/item' => 'Dropdown Item Page', + ], + + 'exclude' => [ + 'qux', + ], + + 'custom' => [ + [ + 'label' => 'Custom', + 'destination' => 'https://example.com', + 'priority' => 120, + 'attributes' => [ + 'target' => '_blank', + ], + ], + ], + + 'subdirectory_display' => 'flat', + ], + ]; + + config(['hyde' => $config]); + + $this->assertMenuEquals([ + ['label' => 'Baz Page', 'priority' => 1], + ['label' => 'Bar Page', 'priority' => 2], + ['label' => 'Foo Page', 'priority' => 3], + ['label' => 'Custom', 'priority' => 120, 'attributes' => ['target' => '_blank']], + ['label' => 'Dropdown Item Page', 'priority' => 999], + ], [ + new MarkdownPage('foo'), + new MarkdownPage('bar'), + new MarkdownPage('baz'), + new MarkdownPage('qux'), + new MarkdownPage('dropdown/item'), + ]); + } + // Testing helpers protected function assertSidebarEquals(array $expected, array $menuPages): AssertableNavigationMenu From de4e8c39958af708641c8d3a79b64ad42b4cfe9a Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 13:55:52 +0200 Subject: [PATCH 105/232] Test can configure main menu using builder settings --- .../AutomaticNavigationConfigurationsTest.php | 51 +++++++++++++++++++ 1 file changed, 51 insertions(+) diff --git a/packages/framework/tests/Feature/AutomaticNavigationConfigurationsTest.php b/packages/framework/tests/Feature/AutomaticNavigationConfigurationsTest.php index 34784461c8c..82ba3fdb209 100644 --- a/packages/framework/tests/Feature/AutomaticNavigationConfigurationsTest.php +++ b/packages/framework/tests/Feature/AutomaticNavigationConfigurationsTest.php @@ -10,6 +10,7 @@ use Hyde\Pages\MarkdownPage; use Hyde\Pages\MarkdownPost; use Hyde\Pages\InMemoryPage; +use Hyde\Facades\Navigation; use Hyde\Foundation\HydeKernel; use JetBrains\PhpStorm\NoReturn; use Hyde\Pages\Concerns\HydePage; @@ -1289,6 +1290,56 @@ public function testCanConfigureMainMenuUsingArraySettings() ]); } + public function testCanConfigureMainMenuUsingBuilderSettings() + { + $builder = Navigation::configure() + ->order([ + 'foo' => 3, + 'bar' => 2, + 'baz' => 1, + ]) + ->labels([ + 'foo' => 'Foo Page', + 'bar' => 'Bar Page', + 'baz' => 'Baz Page', + 'dropdown/item' => 'Dropdown Item Page', + ]) + ->exclude([ + 'qux', + ]) + ->custom([ + [ + 'label' => 'Custom', + 'destination' => 'https://example.com', + 'priority' => 120, + 'attributes' => [ + 'target' => '_blank', + ], + ], + ]) + ->subdirectoryDisplay('flat'); + + $config = [ + 'navigation' => $builder, + ]; + + config(['hyde' => $config]); + + $this->assertMenuEquals([ + ['label' => 'Baz Page', 'priority' => 1], + ['label' => 'Bar Page', 'priority' => 2], + ['label' => 'Foo Page', 'priority' => 3], + ['label' => 'Custom', 'priority' => 120, 'attributes' => ['target' => '_blank']], + ['label' => 'Dropdown Item Page', 'priority' => 999], + ], [ + new MarkdownPage('foo'), + new MarkdownPage('bar'), + new MarkdownPage('baz'), + new MarkdownPage('qux'), + new MarkdownPage('dropdown/item'), + ]); + } + // Testing helpers protected function assertSidebarEquals(array $expected, array $menuPages): AssertableNavigationMenu From ea05a987b2775074b304c2bcce108eb2d67e821b Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 13:59:41 +0200 Subject: [PATCH 106/232] Inline local variable --- .../AutomaticNavigationConfigurationsTest.php | 54 +++++++++---------- 1 file changed, 26 insertions(+), 28 deletions(-) diff --git a/packages/framework/tests/Feature/AutomaticNavigationConfigurationsTest.php b/packages/framework/tests/Feature/AutomaticNavigationConfigurationsTest.php index 82ba3fdb209..14757d9935a 100644 --- a/packages/framework/tests/Feature/AutomaticNavigationConfigurationsTest.php +++ b/packages/framework/tests/Feature/AutomaticNavigationConfigurationsTest.php @@ -1292,35 +1292,33 @@ public function testCanConfigureMainMenuUsingArraySettings() public function testCanConfigureMainMenuUsingBuilderSettings() { - $builder = Navigation::configure() - ->order([ - 'foo' => 3, - 'bar' => 2, - 'baz' => 1, - ]) - ->labels([ - 'foo' => 'Foo Page', - 'bar' => 'Bar Page', - 'baz' => 'Baz Page', - 'dropdown/item' => 'Dropdown Item Page', - ]) - ->exclude([ - 'qux', - ]) - ->custom([ - [ - 'label' => 'Custom', - 'destination' => 'https://example.com', - 'priority' => 120, - 'attributes' => [ - 'target' => '_blank', - ], - ], - ]) - ->subdirectoryDisplay('flat'); - $config = [ - 'navigation' => $builder, + 'navigation' => Navigation::configure() + ->order([ + 'foo' => 3, + 'bar' => 2, + 'baz' => 1, + ]) + ->labels([ + 'foo' => 'Foo Page', + 'bar' => 'Bar Page', + 'baz' => 'Baz Page', + 'dropdown/item' => 'Dropdown Item Page', + ]) + ->exclude([ + 'qux', + ]) + ->custom([ + [ + 'label' => 'Custom', + 'destination' => 'https://example.com', + 'priority' => 120, + 'attributes' => [ + 'target' => '_blank', + ], + ], + ]) + ->subdirectoryDisplay('flat'), ]; config(['hyde' => $config]); From 57b703583338d38e2f443742fbf8504cab10b109 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 16:08:29 +0200 Subject: [PATCH 107/232] Use the new Navigation configuration builder class Updates the configuration files to use the new Navigation configuration builder --- config/hyde.php | 42 +++++++++++------------------- packages/framework/config/hyde.php | 42 +++++++++++------------------- 2 files changed, 30 insertions(+), 54 deletions(-) diff --git a/config/hyde.php b/config/hyde.php index 8d9c62357c5..4b224b922ae 100644 --- a/config/hyde.php +++ b/config/hyde.php @@ -332,40 +332,28 @@ | */ - 'navigation' => [ - // This configuration sets the priorities used to determine the order of the menu. - // The default values have been added below for reference and easy editing. - // The array key is the page's route key, the value is the priority. - // Lower values show up first in the menu. The default is 999. - 'order' => [ + 'navigation' => Navigation::configure() + ->order([ + // Override page priority order 'index' => 0, 'posts' => 10, 'docs/index' => 100, - ], - - // In case you want to customize the labels for the menu items, you can do so here. - // Simply add the route key as the array key, and the label as the value. - 'labels' => [ + ]) + ->labels([ + // Override page labels 'index' => 'Home', 'docs/index' => 'Docs', - ], - - // These are the route keys of pages that should not show up in the navigation menu. - 'exclude' => [ + ]) + ->exclude([ + // Exclude pages from the navigation '404', - ], - - // Any extra links you want to add to the navigation menu can be added here. - // To get started quickly, you can uncomment the defaults here. - // See the documentation link above for more information. - 'custom' => [ + ]) + ->custom([ + // Add custom items to the navigation menu // Navigation::item('https://github.com/hydephp/hyde', 'GitHub', 200), - ], - - // How should pages in subdirectories be displayed in the menu? - // You can choose between 'dropdown', 'flat', and 'hidden'. - 'subdirectory_display' => 'hidden', - ], + ]) + // Configure how subdirectories are displayed in the navigation + ->subdirectoryDisplay('hidden'), /* |-------------------------------------------------------------------------- diff --git a/packages/framework/config/hyde.php b/packages/framework/config/hyde.php index 8d9c62357c5..4b224b922ae 100644 --- a/packages/framework/config/hyde.php +++ b/packages/framework/config/hyde.php @@ -332,40 +332,28 @@ | */ - 'navigation' => [ - // This configuration sets the priorities used to determine the order of the menu. - // The default values have been added below for reference and easy editing. - // The array key is the page's route key, the value is the priority. - // Lower values show up first in the menu. The default is 999. - 'order' => [ + 'navigation' => Navigation::configure() + ->order([ + // Override page priority order 'index' => 0, 'posts' => 10, 'docs/index' => 100, - ], - - // In case you want to customize the labels for the menu items, you can do so here. - // Simply add the route key as the array key, and the label as the value. - 'labels' => [ + ]) + ->labels([ + // Override page labels 'index' => 'Home', 'docs/index' => 'Docs', - ], - - // These are the route keys of pages that should not show up in the navigation menu. - 'exclude' => [ + ]) + ->exclude([ + // Exclude pages from the navigation '404', - ], - - // Any extra links you want to add to the navigation menu can be added here. - // To get started quickly, you can uncomment the defaults here. - // See the documentation link above for more information. - 'custom' => [ + ]) + ->custom([ + // Add custom items to the navigation menu // Navigation::item('https://github.com/hydephp/hyde', 'GitHub', 200), - ], - - // How should pages in subdirectories be displayed in the menu? - // You can choose between 'dropdown', 'flat', and 'hidden'. - 'subdirectory_display' => 'hidden', - ], + ]) + // Configure how subdirectories are displayed in the navigation + ->subdirectoryDisplay('hidden'), /* |-------------------------------------------------------------------------- From 8588cb9b12fbc64d70f0718033c43a5a7d5022f9 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 16:14:54 +0200 Subject: [PATCH 108/232] Rename builder methods to be self describing --- config/hyde.php | 10 ++-- packages/framework/config/hyde.php | 10 ++-- .../NavigationMenuConfigurationBuilder.php | 10 ++-- .../AutomaticNavigationConfigurationsTest.php | 10 ++-- .../Unit/Facades/NavigationFacadeTest.php | 16 +++---- ...NavigationMenuConfigurationBuilderTest.php | 46 +++++++++---------- 6 files changed, 51 insertions(+), 51 deletions(-) diff --git a/config/hyde.php b/config/hyde.php index 4b224b922ae..4458eabc7a4 100644 --- a/config/hyde.php +++ b/config/hyde.php @@ -333,27 +333,27 @@ */ 'navigation' => Navigation::configure() - ->order([ + ->setPagePriorities([ // Override page priority order 'index' => 0, 'posts' => 10, 'docs/index' => 100, ]) - ->labels([ + ->setPageLabels([ // Override page labels 'index' => 'Home', 'docs/index' => 'Docs', ]) - ->exclude([ + ->excludePages([ // Exclude pages from the navigation '404', ]) - ->custom([ + ->addCustomNavigationItems([ // Add custom items to the navigation menu // Navigation::item('https://github.com/hydephp/hyde', 'GitHub', 200), ]) // Configure how subdirectories are displayed in the navigation - ->subdirectoryDisplay('hidden'), + ->setSubdirectoryDisplayMode('hidden'), /* |-------------------------------------------------------------------------- diff --git a/packages/framework/config/hyde.php b/packages/framework/config/hyde.php index 4b224b922ae..4458eabc7a4 100644 --- a/packages/framework/config/hyde.php +++ b/packages/framework/config/hyde.php @@ -333,27 +333,27 @@ */ 'navigation' => Navigation::configure() - ->order([ + ->setPagePriorities([ // Override page priority order 'index' => 0, 'posts' => 10, 'docs/index' => 100, ]) - ->labels([ + ->setPageLabels([ // Override page labels 'index' => 'Home', 'docs/index' => 'Docs', ]) - ->exclude([ + ->excludePages([ // Exclude pages from the navigation '404', ]) - ->custom([ + ->addCustomNavigationItems([ // Add custom items to the navigation menu // Navigation::item('https://github.com/hydephp/hyde', 'GitHub', 200), ]) // Configure how subdirectories are displayed in the navigation - ->subdirectoryDisplay('hidden'), + ->setSubdirectoryDisplayMode('hidden'), /* |-------------------------------------------------------------------------- diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php index 621a0a109c6..aa44c5cbbe9 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php @@ -25,7 +25,7 @@ class NavigationMenuConfigurationBuilder extends ArrayObject implements Arrayabl * @param array|array $order * @return $this */ - public function order(array $order): static + public function setPagePriorities(array $order): static { $this['order'] = $order; @@ -40,7 +40,7 @@ public function order(array $order): static * @param array $labels * @return $this */ - public function labels(array $labels): static + public function setPageLabels(array $labels): static { $this['labels'] = $labels; @@ -55,7 +55,7 @@ public function labels(array $labels): static * @param array $exclude * @return $this */ - public function exclude(array $exclude): static + public function excludePages(array $exclude): static { $this['exclude'] = $exclude; @@ -70,7 +70,7 @@ public function exclude(array $exclude): static * @param array}> $custom * @return $this */ - public function custom(array $custom): static + public function addCustomNavigationItems(array $custom): static { $this['custom'] = $custom; @@ -85,7 +85,7 @@ public function custom(array $custom): static * @param 'dropdown'|'flat'|'hidden' $displayMode * @return $this */ - public function subdirectoryDisplay(string $displayMode): static + public function setSubdirectoryDisplayMode(string $displayMode): static { self::assertType(['dropdown', 'flat', 'hidden'], $displayMode); diff --git a/packages/framework/tests/Feature/AutomaticNavigationConfigurationsTest.php b/packages/framework/tests/Feature/AutomaticNavigationConfigurationsTest.php index 14757d9935a..ea5a8a48938 100644 --- a/packages/framework/tests/Feature/AutomaticNavigationConfigurationsTest.php +++ b/packages/framework/tests/Feature/AutomaticNavigationConfigurationsTest.php @@ -1294,21 +1294,21 @@ public function testCanConfigureMainMenuUsingBuilderSettings() { $config = [ 'navigation' => Navigation::configure() - ->order([ + ->setPagePriorities([ 'foo' => 3, 'bar' => 2, 'baz' => 1, ]) - ->labels([ + ->setPageLabels([ 'foo' => 'Foo Page', 'bar' => 'Bar Page', 'baz' => 'Baz Page', 'dropdown/item' => 'Dropdown Item Page', ]) - ->exclude([ + ->excludePages([ 'qux', ]) - ->custom([ + ->addCustomNavigationItems([ [ 'label' => 'Custom', 'destination' => 'https://example.com', @@ -1318,7 +1318,7 @@ public function testCanConfigureMainMenuUsingBuilderSettings() ], ], ]) - ->subdirectoryDisplay('flat'), + ->setSubdirectoryDisplayMode('flat'), ]; config(['hyde' => $config]); diff --git a/packages/framework/tests/Unit/Facades/NavigationFacadeTest.php b/packages/framework/tests/Unit/Facades/NavigationFacadeTest.php index f101a28263b..a81acc59297 100644 --- a/packages/framework/tests/Unit/Facades/NavigationFacadeTest.php +++ b/packages/framework/tests/Unit/Facades/NavigationFacadeTest.php @@ -59,11 +59,11 @@ public function testConfigure() public function testConfigureWithChainedMethods() { $config = Navigation::configure() - ->order(['index' => 0, 'posts' => 10]) - ->labels(['index' => 'Home']) - ->exclude(['404']) - ->custom([Navigation::item('https://github.com', 'GitHub', 200)]) - ->subdirectoryDisplay('dropdown') + ->setPagePriorities(['index' => 0, 'posts' => 10]) + ->setPageLabels(['index' => 'Home']) + ->excludePages(['404']) + ->addCustomNavigationItems([Navigation::item('https://github.com', 'GitHub', 200)]) + ->setSubdirectoryDisplayMode('dropdown') ->toArray(); $this->assertIsArray($config); @@ -83,9 +83,9 @@ public function testConfigureWithChainedMethods() public function testConfigureWithSomeChainedMethods() { $config = Navigation::configure() - ->order(['about' => 1, 'contact' => 2]) - ->labels(['about' => 'About Us']) - ->subdirectoryDisplay('flat') + ->setPagePriorities(['about' => 1, 'contact' => 2]) + ->setPageLabels(['about' => 'About Us']) + ->setSubdirectoryDisplayMode('flat') ->toArray(); $this->assertSame(['about' => 1, 'contact' => 2], $config['order']); diff --git a/packages/framework/tests/Unit/NavigationMenuConfigurationBuilderTest.php b/packages/framework/tests/Unit/NavigationMenuConfigurationBuilderTest.php index e93c3dd3b72..0d0035c018a 100644 --- a/packages/framework/tests/Unit/NavigationMenuConfigurationBuilderTest.php +++ b/packages/framework/tests/Unit/NavigationMenuConfigurationBuilderTest.php @@ -20,51 +20,51 @@ protected function setUp(): void $this->builder = new NavigationMenuConfigurationBuilder(); } - public function testOrder() + public function testSetPagePriorities() { $order = ['index' => 0, 'posts' => 10, 'docs/index' => 100]; - $result = $this->builder->order($order)->toArray(); + $result = $this->builder->setPagePriorities($order)->toArray(); $this->assertArrayHasKey('order', $result); $this->assertSame($order, $result['order']); } - public function testLabels() + public function testSetPageLabels() { $labels = ['index' => 'Home', 'docs/index' => 'Docs']; - $result = $this->builder->labels($labels)->toArray(); + $result = $this->builder->setPageLabels($labels)->toArray(); $this->assertArrayHasKey('labels', $result); $this->assertSame($labels, $result['labels']); } - public function testExclude() + public function testExcludePages() { $exclude = ['404', 'admin']; - $result = $this->builder->exclude($exclude)->toArray(); + $result = $this->builder->excludePages($exclude)->toArray(); $this->assertArrayHasKey('exclude', $result); $this->assertSame($exclude, $result['exclude']); } - public function testCustom() + public function testAddCustomNavigationItems() { $custom = [ Navigation::item('https://example.com', 'Example', 200), Navigation::item('https://github.com', 'GitHub', 300), ]; - $result = $this->builder->custom($custom)->toArray(); + $result = $this->builder->addCustomNavigationItems($custom)->toArray(); $this->assertArrayHasKey('custom', $result); $this->assertSame($custom, $result['custom']); } - public function testSubdirectoryDisplay() + public function testSetSubdirectoryDisplayMode() { $displayModes = ['dropdown', 'flat', 'hidden']; foreach ($displayModes as $mode) { - $result = $this->builder->subdirectoryDisplay($mode)->toArray(); + $result = $this->builder->setSubdirectoryDisplayMode($mode)->toArray(); $this->assertArrayHasKey('subdirectory_display', $result); $this->assertSame($mode, $result['subdirectory_display']); @@ -74,11 +74,11 @@ public function testSubdirectoryDisplay() public function testChainedMethods() { $result = $this->builder - ->order(['index' => 0, 'posts' => 10]) - ->labels(['index' => 'Home']) - ->exclude(['404']) - ->custom([Navigation::item('https://github.com', 'GitHub', 200)]) - ->subdirectoryDisplay('dropdown') + ->setPagePriorities(['index' => 0, 'posts' => 10]) + ->setPageLabels(['index' => 'Home']) + ->excludePages(['404']) + ->addCustomNavigationItems([Navigation::item('https://github.com', 'GitHub', 200)]) + ->setSubdirectoryDisplayMode('dropdown') ->toArray(); $this->assertArrayHasKey('order', $result); @@ -98,28 +98,28 @@ public function testEmptyConfiguration() public function testInvalidSubdirectoryDisplay() { $this->expectException(\TypeError::class); - $this->builder->subdirectoryDisplay('invalid'); + $this->builder->setSubdirectoryDisplayMode('invalid'); } public function testRealLifeUsageScenario() { $result = $this->builder - ->order([ + ->setPagePriorities([ 'index' => 0, 'posts' => 10, 'docs/index' => 100, ]) - ->labels([ + ->setPageLabels([ 'index' => 'Home', 'docs/index' => 'Docs', ]) - ->exclude([ + ->excludePages([ '404', ]) - ->custom([ + ->addCustomNavigationItems([ Navigation::item('https://github.com/hydephp/hyde', 'GitHub', 200), ]) - ->subdirectoryDisplay('dropdown') + ->setSubdirectoryDisplayMode('dropdown') ->toArray(); $this->assertSame([ @@ -140,7 +140,7 @@ public function testArrayableInterface() public function testArrayObjectBehavior() { - $this->builder->order(['index' => 0]); + $this->builder->setPagePriorities(['index' => 0]); $this->assertCount(1, $this->builder); $this->assertSame(['order' => ['index' => 0]], $this->builder->getArrayCopy()); @@ -148,7 +148,7 @@ public function testArrayObjectBehavior() public function testToArrayMethodReturnsSameResultAsArrayObject() { - $this->builder->order(['index' => 0]); + $this->builder->setPagePriorities(['index' => 0]); $this->assertSame(['order' => ['index' => 0]], $this->builder->toArray()); } From 93497a41048b2bc98dc5e94edbed429a1095c359 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 16:15:39 +0200 Subject: [PATCH 109/232] Remove now redundant code comments --- config/hyde.php | 5 ----- packages/framework/config/hyde.php | 5 ----- 2 files changed, 10 deletions(-) diff --git a/config/hyde.php b/config/hyde.php index 4458eabc7a4..9ae31e9a627 100644 --- a/config/hyde.php +++ b/config/hyde.php @@ -334,25 +334,20 @@ 'navigation' => Navigation::configure() ->setPagePriorities([ - // Override page priority order 'index' => 0, 'posts' => 10, 'docs/index' => 100, ]) ->setPageLabels([ - // Override page labels 'index' => 'Home', 'docs/index' => 'Docs', ]) ->excludePages([ - // Exclude pages from the navigation '404', ]) ->addCustomNavigationItems([ - // Add custom items to the navigation menu // Navigation::item('https://github.com/hydephp/hyde', 'GitHub', 200), ]) - // Configure how subdirectories are displayed in the navigation ->setSubdirectoryDisplayMode('hidden'), /* diff --git a/packages/framework/config/hyde.php b/packages/framework/config/hyde.php index 4458eabc7a4..9ae31e9a627 100644 --- a/packages/framework/config/hyde.php +++ b/packages/framework/config/hyde.php @@ -334,25 +334,20 @@ 'navigation' => Navigation::configure() ->setPagePriorities([ - // Override page priority order 'index' => 0, 'posts' => 10, 'docs/index' => 100, ]) ->setPageLabels([ - // Override page labels 'index' => 'Home', 'docs/index' => 'Docs', ]) ->excludePages([ - // Exclude pages from the navigation '404', ]) ->addCustomNavigationItems([ - // Add custom items to the navigation menu // Navigation::item('https://github.com/hydephp/hyde', 'GitHub', 200), ]) - // Configure how subdirectories are displayed in the navigation ->setSubdirectoryDisplayMode('hidden'), /* From e7b5a1ce57fb0799c1a33706491be6273e06eb04 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 16:19:22 +0200 Subject: [PATCH 110/232] Remove infix from helper method name Don't think this adds value --- config/hyde.php | 2 +- packages/framework/config/hyde.php | 2 +- .../Navigation/NavigationMenuConfigurationBuilder.php | 2 +- .../Feature/AutomaticNavigationConfigurationsTest.php | 2 +- .../framework/tests/Unit/Facades/NavigationFacadeTest.php | 2 +- .../tests/Unit/NavigationMenuConfigurationBuilderTest.php | 8 ++++---- 6 files changed, 9 insertions(+), 9 deletions(-) diff --git a/config/hyde.php b/config/hyde.php index 9ae31e9a627..67c1da3b43b 100644 --- a/config/hyde.php +++ b/config/hyde.php @@ -345,7 +345,7 @@ ->excludePages([ '404', ]) - ->addCustomNavigationItems([ + ->addNavigationItems([ // Navigation::item('https://github.com/hydephp/hyde', 'GitHub', 200), ]) ->setSubdirectoryDisplayMode('hidden'), diff --git a/packages/framework/config/hyde.php b/packages/framework/config/hyde.php index 9ae31e9a627..67c1da3b43b 100644 --- a/packages/framework/config/hyde.php +++ b/packages/framework/config/hyde.php @@ -345,7 +345,7 @@ ->excludePages([ '404', ]) - ->addCustomNavigationItems([ + ->addNavigationItems([ // Navigation::item('https://github.com/hydephp/hyde', 'GitHub', 200), ]) ->setSubdirectoryDisplayMode('hidden'), diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php index aa44c5cbbe9..ef8d409f6ef 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php @@ -70,7 +70,7 @@ public function excludePages(array $exclude): static * @param array}> $custom * @return $this */ - public function addCustomNavigationItems(array $custom): static + public function addNavigationItems(array $custom): static { $this['custom'] = $custom; diff --git a/packages/framework/tests/Feature/AutomaticNavigationConfigurationsTest.php b/packages/framework/tests/Feature/AutomaticNavigationConfigurationsTest.php index ea5a8a48938..8262d1acc8f 100644 --- a/packages/framework/tests/Feature/AutomaticNavigationConfigurationsTest.php +++ b/packages/framework/tests/Feature/AutomaticNavigationConfigurationsTest.php @@ -1308,7 +1308,7 @@ public function testCanConfigureMainMenuUsingBuilderSettings() ->excludePages([ 'qux', ]) - ->addCustomNavigationItems([ + ->addNavigationItems([ [ 'label' => 'Custom', 'destination' => 'https://example.com', diff --git a/packages/framework/tests/Unit/Facades/NavigationFacadeTest.php b/packages/framework/tests/Unit/Facades/NavigationFacadeTest.php index a81acc59297..fa2350fda8f 100644 --- a/packages/framework/tests/Unit/Facades/NavigationFacadeTest.php +++ b/packages/framework/tests/Unit/Facades/NavigationFacadeTest.php @@ -62,7 +62,7 @@ public function testConfigureWithChainedMethods() ->setPagePriorities(['index' => 0, 'posts' => 10]) ->setPageLabels(['index' => 'Home']) ->excludePages(['404']) - ->addCustomNavigationItems([Navigation::item('https://github.com', 'GitHub', 200)]) + ->addNavigationItems([Navigation::item('https://github.com', 'GitHub', 200)]) ->setSubdirectoryDisplayMode('dropdown') ->toArray(); diff --git a/packages/framework/tests/Unit/NavigationMenuConfigurationBuilderTest.php b/packages/framework/tests/Unit/NavigationMenuConfigurationBuilderTest.php index 0d0035c018a..bd0d9acdcf0 100644 --- a/packages/framework/tests/Unit/NavigationMenuConfigurationBuilderTest.php +++ b/packages/framework/tests/Unit/NavigationMenuConfigurationBuilderTest.php @@ -47,13 +47,13 @@ public function testExcludePages() $this->assertSame($exclude, $result['exclude']); } - public function testAddCustomNavigationItems() + public function testAddNavigationItems() { $custom = [ Navigation::item('https://example.com', 'Example', 200), Navigation::item('https://github.com', 'GitHub', 300), ]; - $result = $this->builder->addCustomNavigationItems($custom)->toArray(); + $result = $this->builder->addNavigationItems($custom)->toArray(); $this->assertArrayHasKey('custom', $result); $this->assertSame($custom, $result['custom']); @@ -77,7 +77,7 @@ public function testChainedMethods() ->setPagePriorities(['index' => 0, 'posts' => 10]) ->setPageLabels(['index' => 'Home']) ->excludePages(['404']) - ->addCustomNavigationItems([Navigation::item('https://github.com', 'GitHub', 200)]) + ->addNavigationItems([Navigation::item('https://github.com', 'GitHub', 200)]) ->setSubdirectoryDisplayMode('dropdown') ->toArray(); @@ -116,7 +116,7 @@ public function testRealLifeUsageScenario() ->excludePages([ '404', ]) - ->addCustomNavigationItems([ + ->addNavigationItems([ Navigation::item('https://github.com/hydephp/hyde', 'GitHub', 200), ]) ->setSubdirectoryDisplayMode('dropdown') From 491d08e0fafceaaa60693cf89724f04bf09241fb Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 16:20:07 +0200 Subject: [PATCH 111/232] Clean up formatting --- .../tests/Unit/NavigationMenuConfigurationBuilderTest.php | 2 ++ 1 file changed, 2 insertions(+) diff --git a/packages/framework/tests/Unit/NavigationMenuConfigurationBuilderTest.php b/packages/framework/tests/Unit/NavigationMenuConfigurationBuilderTest.php index bd0d9acdcf0..8e24330ef83 100644 --- a/packages/framework/tests/Unit/NavigationMenuConfigurationBuilderTest.php +++ b/packages/framework/tests/Unit/NavigationMenuConfigurationBuilderTest.php @@ -17,6 +17,7 @@ class NavigationMenuConfigurationBuilderTest extends UnitTestCase protected function setUp(): void { parent::setUp(); + $this->builder = new NavigationMenuConfigurationBuilder(); } @@ -53,6 +54,7 @@ public function testAddNavigationItems() Navigation::item('https://example.com', 'Example', 200), Navigation::item('https://github.com', 'GitHub', 300), ]; + $result = $this->builder->addNavigationItems($custom)->toArray(); $this->assertArrayHasKey('custom', $result); From 7641ff9d99d4b5269b70f5a2d58e512a9db23392 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 16:21:37 +0200 Subject: [PATCH 112/232] Clarify comment --- .../Features/Navigation/NavigationMenuConfigurationBuilder.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php index ef8d409f6ef..2686a6b3936 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php @@ -78,7 +78,7 @@ public function addNavigationItems(array $custom): static } /** - * Set the display mode for subdirectories. + * Set the display mode for pages in subdirectories. * * You can choose between 'dropdown', 'flat', and 'hidden'. * From e48da59a74ec8df1e103247d1c320b062c3bcf02 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 16:22:25 +0200 Subject: [PATCH 113/232] Document default value --- .../Features/Navigation/NavigationMenuConfigurationBuilder.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php index 2686a6b3936..78b76dd01dc 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php @@ -80,7 +80,7 @@ public function addNavigationItems(array $custom): static /** * Set the display mode for pages in subdirectories. * - * You can choose between 'dropdown', 'flat', and 'hidden'. + * You can choose between 'dropdown', 'flat', and 'hidden'. The default is 'hidden'. * * @param 'dropdown'|'flat'|'hidden' $displayMode * @return $this From 7f9f9b776e70eed0c65f76c39b1c28e5900c1d1c Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 16:23:38 +0200 Subject: [PATCH 114/232] Add experimental fluent shorthand --- .../NavigationMenuConfigurationBuilder.php | 12 ++++++++++++ .../Unit/NavigationMenuConfigurationBuilderTest.php | 7 +++++++ 2 files changed, 19 insertions(+) diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php index 78b76dd01dc..1f27c65dbc5 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php @@ -94,6 +94,18 @@ public function setSubdirectoryDisplayMode(string $displayMode): static return $this; } + /** + * Hide pages in subdirectories from the navigation. + * + * @experimental This method is experimental and may change or be removed before the final release. + * + * @return $this + */ + public function hideSubdirectoriesFromNavigation(): static + { + return $this->setSubdirectoryDisplayMode('hidden'); + } + /** * Get the instance as an array. * diff --git a/packages/framework/tests/Unit/NavigationMenuConfigurationBuilderTest.php b/packages/framework/tests/Unit/NavigationMenuConfigurationBuilderTest.php index 8e24330ef83..cde1e6c4100 100644 --- a/packages/framework/tests/Unit/NavigationMenuConfigurationBuilderTest.php +++ b/packages/framework/tests/Unit/NavigationMenuConfigurationBuilderTest.php @@ -135,6 +135,13 @@ public function testRealLifeUsageScenario() ], $result); } + public function testHideSubdirectoriesFromNavigationShorthand() + { + $result = $this->builder->hideSubdirectoriesFromNavigation()->toArray(); + + $this->assertSame('hidden', $result['subdirectory_display']); + } + public function testArrayableInterface() { $this->assertInstanceOf(Arrayable::class, $this->builder); From a961afefae6d70028525580c2ccbcb945e93248a Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 16:32:34 +0200 Subject: [PATCH 115/232] Update experimental marker --- .../Features/Navigation/NavigationMenuConfigurationBuilder.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php index 1f27c65dbc5..48bd4429489 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php @@ -13,7 +13,7 @@ * * The configured object will be cast to an array that will be used by the framework to set the config data. * - * @experimental This class is experimental and may change in the future. + * @experimental This class is experimental and may change or be removed before the final release. */ class NavigationMenuConfigurationBuilder extends ArrayObject implements Arrayable { From d5f2439dc1d13b9a9766941a009d40d8ec5c82ba Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 16:34:32 +0200 Subject: [PATCH 116/232] Link to facade method and normalize documentation --- packages/framework/src/Facades/Navigation.php | 4 ++-- .../Navigation/NavigationMenuConfigurationBuilder.php | 4 +++- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/packages/framework/src/Facades/Navigation.php b/packages/framework/src/Facades/Navigation.php index b6294e06e16..1f64d809f3c 100644 --- a/packages/framework/src/Facades/Navigation.php +++ b/packages/framework/src/Facades/Navigation.php @@ -34,9 +34,9 @@ public static function item(string $destination, ?string $label = null, ?int $pr /** * Configuration helper method to define the navigation menu configuration with better IDE support. * - * The returned object will then be cast to an array that will be used by the framework to set the config data. + * The builder is an array object that will be used by the framework to set the navigation menu configuration. * - * @experimental This method is experimental and may change in the future. + * @experimental This method is experimental and may change or be removed before the final release. */ public static function configure(): NavigationMenuConfigurationBuilder { diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php index 48bd4429489..4f5d9957628 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationMenuConfigurationBuilder.php @@ -11,7 +11,9 @@ /** * Configuration helper class to define the navigation menu configuration with better IDE support. * - * The configured object will be cast to an array that will be used by the framework to set the config data. + * The configured data will then be used by the framework to set the navigation menu configuration. + * + * @see \Hyde\Facades\Navigation::configure() * * @experimental This class is experimental and may change or be removed before the final release. */ From 210271f202ad028d80e30e5e7a500e906fd5bc95 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 18:03:10 +0200 Subject: [PATCH 117/232] Remove documentation for alternate front matter properties I think it's confusing to note these, it's best to document the canonical ones, but silently support alternates for fault tolerance and interoperability. --- docs/digging-deeper/navigation.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 3ff1d9d16b9..7c58475dccc 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -70,9 +70,9 @@ You don't need to specify all the keys, only the ones you want to customize. ```yaml navigation: label: string # The text to display - priority: int # Order is also supported - hidden: bool # Visible is also supported (but obviously invert the value) - group: string # Category is also supported + priority: int # The priority of the page used for determining the order, lower means higher up/first + hidden: bool # Whether the page should be hidden from the navigation menu + group: string # For sidebars, this is the sidebar group, for the main menu, this is the dropdown group ``` ### `label` @@ -86,7 +86,7 @@ navigation: ### `priority` -The `priority` option allows you to control the order in which the page appears in the navigation menu. You can also use `order` instead of `priority`. +The `priority` option allows you to control the order in which the page appears in the navigation menu. ```yaml navigation: @@ -95,7 +95,7 @@ navigation: ### `hidden` -The `hidden` option allows you to control if the page appears in the navigation menu. You can also use `visible` instead of `hidden`, but obviously invert the value. +The `hidden` option allows you to control if the page appears in the navigation menu. ```yaml navigation: @@ -107,7 +107,6 @@ navigation: The `group` option has a slightly different meaning depending on the type of navigation menu. For the primary navigation menu, it allows you to group pages together in dropdowns. For the sidebar, it allows you to group pages together in the sidebar under a common heading. -You can also use `category` instead of `group`. ```yaml navigation: From a6fa2951245c2dc94795a0e336e08512445788cf Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 18:15:18 +0200 Subject: [PATCH 118/232] Merge long parts of introduction to a single section --- docs/digging-deeper/navigation.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 7c58475dccc..c28d9188e3a 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -8,18 +8,16 @@ navigation: ## Introduction -A great time-saving feature of HydePHP is the automatic navigation menu and documentation sidebar generation. -Hyde is designed to automatically configure these menus for you based on the content you have in your project. +HydePHP offers an automatic navigation menu and documentation sidebar generation feature, designed to take the pain out of creating navigation menus. +While Hyde does its best to configure these menus automatically based on understanding your project files, you may want to customize them further. +This documentation will guide you through the customization process. There are two types of navigation menus in Hyde: - **Primary Navigation Menu**: This is the main navigation menu that appears on most pages of your site. - **Documentation Sidebar**: This is a sidebar that appears on documentation pages and contains links to other documentation pages. -HydePHP automatically generates all of these menus for you based on the content of your project, -and does its best to automatically configure them in the way that you most likely want them to be. -Of course, this won't always be perfect, so thankfully Hyde makes it a breeze to customize these menus to your liking. Keep on reading to learn how! To learn even more about the sidebars, visit the [Documentation Pages](documentation-pages) documentation. ### Quick primer on the internals From f72a4f525fd7d26650e8b7c8076fab91060f39a9 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 18:15:49 +0200 Subject: [PATCH 119/232] Update the menu types list text --- docs/digging-deeper/navigation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index c28d9188e3a..baaa3c409bf 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -14,8 +14,8 @@ This documentation will guide you through the customization process. There are two types of navigation menus in Hyde: -- **Primary Navigation Menu**: This is the main navigation menu that appears on most pages of your site. -- **Documentation Sidebar**: This is a sidebar that appears on documentation pages and contains links to other documentation pages. +1. **Primary Navigation Menu**: The main navigation menu appearing on most pages of your site. Unique features include dropdowns for subdirectories, depending on configuration. +2. **Documentation Sidebar**: The sidebar on documentation pages with links to other documentation pages. Unique features include automatic grouping based on subdirectories. Keep on reading to learn how! To learn even more about the sidebars, visit the [Documentation Pages](documentation-pages) documentation. From d98f73b4872def93deaac51a79d2c5aad6f710d1 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 18:16:39 +0200 Subject: [PATCH 120/232] Merge together sections in the introduction --- docs/digging-deeper/navigation.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index baaa3c409bf..c525f72d56c 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -10,15 +10,14 @@ navigation: HydePHP offers an automatic navigation menu and documentation sidebar generation feature, designed to take the pain out of creating navigation menus. While Hyde does its best to configure these menus automatically based on understanding your project files, you may want to customize them further. -This documentation will guide you through the customization process. There are two types of navigation menus in Hyde: 1. **Primary Navigation Menu**: The main navigation menu appearing on most pages of your site. Unique features include dropdowns for subdirectories, depending on configuration. 2. **Documentation Sidebar**: The sidebar on documentation pages with links to other documentation pages. Unique features include automatic grouping based on subdirectories. +This documentation will guide you through the customization process. To learn even more about sidebars, visit the [Documentation Pages](documentation-pages) documentation. -Keep on reading to learn how! To learn even more about the sidebars, visit the [Documentation Pages](documentation-pages) documentation. ### Quick primer on the internals From 49fb29c595a44278ef29e11784b65a3ae72a6afe Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 18:18:12 +0200 Subject: [PATCH 121/232] Improve headings --- docs/digging-deeper/navigation.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index c525f72d56c..5378ec31ed4 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -19,7 +19,7 @@ There are two types of navigation menus in Hyde: This documentation will guide you through the customization process. To learn even more about sidebars, visit the [Documentation Pages](documentation-pages) documentation. -### Quick primer on the internals +### Internal Structure Overview It may be beneficial to understand the internal workings of the navigation menus to take full advantage of the options. @@ -28,13 +28,13 @@ they are configured is very similar, making the documentation here applicable to See the [Digging Deeper](#digging-deeper-into-the-internals) section of this page if you want the full scoop on the internals! -### Primer on priorities +### Understanding Priorities All navigation menu items have an internal priority value that determines their order in the navigation. Lower values mean that the item will be higher up in the menu. The default for pages is `999` which puts them last. However, some pages are autoconfigured to have a lower priority, for example, the `index` page defaults to a priority of `0`. -### What to customize? +### Customization Options Here is a quick overview of what you might want to customize in your navigation menus: @@ -43,7 +43,7 @@ Here is a quick overview of what you might want to customize in your navigation - Navigation menu item visibility - control if pages may show up in the menus - Navigation menu item grouping - group pages together in dropdowns -### How and where to customize? +### Customization Methods Hyde provides a few different ways to customize the navigation menus, depending on what you prefer. From 70993a54195ff910ccdc6416eaccd38ad544458a Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 18:19:24 +0200 Subject: [PATCH 122/232] Merge internal structure section to be more concise and clear --- docs/digging-deeper/navigation.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 5378ec31ed4..6651cda3675 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -21,12 +21,10 @@ This documentation will guide you through the customization process. To learn ev ### Internal Structure Overview -It may be beneficial to understand the internal workings of the navigation menus to take full advantage of the options. +Internally, both navigation menu types extend the same base class, and thus share core functionality. This means the configuration process is similar for both types, making the documentation applicable to both. -In short, both navigation menu types extend the same class (meaning they share the same base code), this means that the way -they are configured is very similar, making the documentation here applicable to both types of menus. +For a deeper understanding of the internal workings, refer to the [Digging Deeper](#digging-deeper-into-the-internals) section. -See the [Digging Deeper](#digging-deeper-into-the-internals) section of this page if you want the full scoop on the internals! ### Understanding Priorities From e2a6934e559142aad060cc807652255c9a3d87c2 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 18:21:08 +0200 Subject: [PATCH 123/232] Improve the wording of the priorities section --- docs/digging-deeper/navigation.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 6651cda3675..a08e650d422 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -28,9 +28,7 @@ For a deeper understanding of the internal workings, refer to the [Digging Deepe ### Understanding Priorities -All navigation menu items have an internal priority value that determines their order in the navigation. -Lower values mean that the item will be higher up in the menu. The default for pages is `999` which puts them last. -However, some pages are autoconfigured to have a lower priority, for example, the `index` page defaults to a priority of `0`. +All navigation menu items have an internal priority value determining their order. Lower values place items higher in the menu. The default priority for pages is `999`, placing them last unless you specify a value. Some pages, like the `index` page, are by default configured with the lowest priority of `0`. ### Customization Options From 5b5692298129bda5475d4350a199e134130434d9 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 18:21:23 +0200 Subject: [PATCH 124/232] Reword introduction to be more concise --- docs/digging-deeper/navigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index a08e650d422..4cf0b9bf8ec 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -32,7 +32,7 @@ All navigation menu items have an internal priority value determining their orde ### Customization Options -Here is a quick overview of what you might want to customize in your navigation menus: +Here's an overview of what you can customize in your navigation menus: - Navigation menu item labels - the text that appears in the menu links - Navigation menu item priority - control the order in which the links appear From a7abfba94423968937a75e4080f8003961fd551d Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 18:22:16 +0200 Subject: [PATCH 125/232] Reword list to be more concise --- docs/digging-deeper/navigation.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 4cf0b9bf8ec..3fd008786d7 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -34,10 +34,10 @@ All navigation menu items have an internal priority value determining their orde Here's an overview of what you can customize in your navigation menus: -- Navigation menu item labels - the text that appears in the menu links -- Navigation menu item priority - control the order in which the links appear -- Navigation menu item visibility - control if pages may show up in the menus -- Navigation menu item grouping - group pages together in dropdowns +- Item labels: The text displayed in menu links +- Item priorities: Control the order of link appearance +- Item visibility: Choose to hide or show pages in the menu +- Item grouping: Group pages together in dropdowns or sidebar categories ### Customization Methods From a9ff6f36e573bc5f468c23ff6f5fdddd18636684 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 18:22:37 +0200 Subject: [PATCH 126/232] Reword introduction to be more concise --- docs/digging-deeper/navigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 3fd008786d7..eb61b4e94ca 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -41,7 +41,7 @@ Here's an overview of what you can customize in your navigation menus: ### Customization Methods -Hyde provides a few different ways to customize the navigation menus, depending on what you prefer. +Hyde provides multiple ways to customize navigation menus to suit your needs: Specifying the data in the front matter will override any dynamically inferred or config-defined priority. While this is useful for one-offs, it can make it harder to reorder items later on as you can't see the whole picture at once. From cfbc1b1a2345b1ba89799cf533e5940a9e76748f Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 18:25:23 +0200 Subject: [PATCH 127/232] Rewrite section to use an easier to read list --- docs/digging-deeper/navigation.md | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index eb61b4e94ca..a0d75d43172 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -43,16 +43,13 @@ Here's an overview of what you can customize in your navigation menus: Hyde provides multiple ways to customize navigation menus to suit your needs: -Specifying the data in the front matter will override any dynamically inferred or config-defined priority. -While this is useful for one-offs, it can make it harder to reorder items later on as you can't see the whole picture at once. -It's up to you which method you prefer to use. +1. Front matter data in Markdown and Blade page files, applicable to all menu types +2. Configuration in the `hyde` config file for main navigation items +3. Configuration in the `docs` config file for documentation sidebar items -To customize how a page is represented in navigation, you can either set the `navigation` front matter data in the page's markdown file, -or configure it in the config file. Main navigation items are in the `hyde` config file, while documentation sidebar items are in the `docs` config file. -General options for the entire navigation menus are also available in the `hyde` and `docs` config files. - -Now that you know the basics, let's dive into the details of how to customize the navigation menus! +Keep in mind that front matter data overrides dynamically inferred or config-defined priorities. While useful for quick one-off changes on small sites, it can make reordering items later on more challenging as you can't see the entire structure at once. +Additionally, general options for the entire navigation menus are also available in the `hyde` and `docs` config files. ## Front Matter Configuration From 528b4fc37487fa043c55791b81c1918e8f9ffd2e Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 18:26:38 +0200 Subject: [PATCH 128/232] Remove extra newlines --- docs/digging-deeper/navigation.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index a0d75d43172..3e23a848749 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -18,14 +18,12 @@ There are two types of navigation menus in Hyde: This documentation will guide you through the customization process. To learn even more about sidebars, visit the [Documentation Pages](documentation-pages) documentation. - ### Internal Structure Overview Internally, both navigation menu types extend the same base class, and thus share core functionality. This means the configuration process is similar for both types, making the documentation applicable to both. For a deeper understanding of the internal workings, refer to the [Digging Deeper](#digging-deeper-into-the-internals) section. - ### Understanding Priorities All navigation menu items have an internal priority value determining their order. Lower values place items higher in the menu. The default priority for pages is `999`, placing them last unless you specify a value. Some pages, like the `index` page, are by default configured with the lowest priority of `0`. From 1d8953926da7a3257a9a1f40940173c57574ccdb Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 18:40:01 +0200 Subject: [PATCH 129/232] Move down part not needed in introduction to bottom of the section --- docs/digging-deeper/navigation.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 3e23a848749..763edae235a 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -51,9 +51,7 @@ Additionally, general options for the entire navigation menus are also available ## Front Matter Configuration -The front matter options allow you to customize the navigation menus on a per-page basis. -Here is a quick reference of the available options. The full documentation of each option is below. -You don't need to specify all the keys, only the ones you want to customize. +Front matter options allow per-page customization of navigation menus. Here's a quick reference of available options: ```yaml navigation: @@ -63,6 +61,8 @@ navigation: group: string # For sidebars, this is the sidebar group, for the main menu, this is the dropdown group ``` +You only need to specify the keys you want to customize. + ### `label` The `label` option allows you to customize the text that appears in the navigation menu for the page. From a6415704d5a9f168ebb48d6767eee62908c8f9ba Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 18:42:21 +0200 Subject: [PATCH 130/232] Reword list to be more concise --- docs/digging-deeper/navigation.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 763edae235a..6a0d43098f9 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -55,10 +55,10 @@ Front matter options allow per-page customization of navigation menus. Here's a ```yaml navigation: - label: string # The text to display - priority: int # The priority of the page used for determining the order, lower means higher up/first + label: string # The displayed text in the navigation item link + priority: int # The page's priority for ordering (lower means higher up/first) hidden: bool # Whether the page should be hidden from the navigation menu - group: string # For sidebars, this is the sidebar group, for the main menu, this is the dropdown group + group: string # Set main menu dropdown or sidebar group key ``` You only need to specify the keys you want to customize. From f8b56aa5ea01e06ea1e5fface2c8ee7b938e4fa4 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 18:45:13 +0200 Subject: [PATCH 131/232] Remove redundant information from section introductions --- docs/digging-deeper/navigation.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 6a0d43098f9..9f71319485d 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -65,7 +65,7 @@ You only need to specify the keys you want to customize. ### `label` -The `label` option allows you to customize the text that appears in the navigation menu for the page. +Customizes the text appearing in the navigation menu link for the page. ```yaml navigation: @@ -74,7 +74,7 @@ navigation: ### `priority` -The `priority` option allows you to control the order in which the page appears in the navigation menu. +Controls the order in which the page appears in the navigation menu. ```yaml navigation: @@ -83,7 +83,7 @@ navigation: ### `hidden` -The `hidden` option allows you to control if the page appears in the navigation menu. +Determines if the page appears in the navigation menu. ```yaml navigation: From 0bd1377d5c0743425875abcf9233096662f2d7dc Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 18:45:23 +0200 Subject: [PATCH 132/232] Document default data sources --- docs/digging-deeper/navigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 9f71319485d..584f355cc19 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -65,7 +65,7 @@ You only need to specify the keys you want to customize. ### `label` -Customizes the text appearing in the navigation menu link for the page. +Customizes the text appearing in the navigation menu link for the page. If not set anywhere else, Hyde will search for a title in the page content or generate one from the filename. ```yaml navigation: From 059f1c6efc9125327bb2240677d7a52f0f74c6b0 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 18:45:44 +0200 Subject: [PATCH 133/232] Add tip about alternate syntax --- docs/digging-deeper/navigation.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 584f355cc19..908e0f3f8d5 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -90,6 +90,8 @@ navigation: hidden: true ``` +**Tip:** You can also use `visible: false` to achieve the same effect. + ### `group` The `group` option has a slightly different meaning depending on the type of navigation menu. From f437ba286393fd855411edf3c33169bd0482e8e8 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 18:50:09 +0200 Subject: [PATCH 134/232] Reword section to be more concise --- docs/digging-deeper/navigation.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 908e0f3f8d5..63bede80181 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -94,9 +94,7 @@ navigation: ### `group` -The `group` option has a slightly different meaning depending on the type of navigation menu. -For the primary navigation menu, it allows you to group pages together in dropdowns. -For the sidebar, it allows you to group pages together in the sidebar under a common heading. +For the primary navigation menu, this groups pages together in dropdowns. For the sidebar, it groups pages under a common heading. ```yaml navigation: From 9d6a5170ee54b70ac827628ce06a4f271f3475ff Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 18:54:12 +0200 Subject: [PATCH 135/232] Add note about grouping normalization --- docs/digging-deeper/navigation.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 63bede80181..a5fc35ff75d 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -101,6 +101,7 @@ navigation: group: "My Group" ``` +**Note:** Sidebar group keys are normalized, so `My Group` and `my-group` are equivalent. ## Config File Configuration From cb24a792435810e6faf8f674007e72df4232c6e5 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 18:58:59 +0200 Subject: [PATCH 136/232] Update introduction to allow for section to stand alone --- docs/digging-deeper/navigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index a5fc35ff75d..916069a4485 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -105,7 +105,7 @@ navigation: ## Config File Configuration -Next up, let's look at how to customize the navigation menus using the config files. +Let's explore how to customize navigation menus using config files: - To customize the navigation menu, use the setting `navigation.order` in the `hyde.php` config. - When customizing the navigation menu, you should use the [route key](core-concepts#route-keys) of the page. From b4541d2720ea799d4e39ad910e87f3151c83062f Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 18:59:38 +0200 Subject: [PATCH 137/232] Expand abbreviation --- docs/digging-deeper/navigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 916069a4485..bfa140ecbe7 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -105,7 +105,7 @@ navigation: ## Config File Configuration -Let's explore how to customize navigation menus using config files: +Let's explore how to customize navigation menus using configuration files: - To customize the navigation menu, use the setting `navigation.order` in the `hyde.php` config. - When customizing the navigation menu, you should use the [route key](core-concepts#route-keys) of the page. From f3e1195a811892006af358cf873f424509d9ec95 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 19:05:27 +0200 Subject: [PATCH 138/232] Clean up the section to be easier and clearer to read --- docs/digging-deeper/navigation.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index bfa140ecbe7..addb37cbb61 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -107,11 +107,10 @@ navigation: Let's explore how to customize navigation menus using configuration files: -- To customize the navigation menu, use the setting `navigation.order` in the `hyde.php` config. -- When customizing the navigation menu, you should use the [route key](core-concepts#route-keys) of the page. +- For the main navigation menu, use `navigation` setting in the `hyde.php` config file. +- For the sidebar, use `sidebar` setting in the `docs.php` config file. -- To customize the sidebar, use the setting `sidebar.order` in the `docs.php` config. -- When customizing the sidebar, can use the route key, or just the [page identifier](core-concepts#page-identifiers) of the page. +When customizing the main navigation menu, use the [route key](core-concepts#route-keys) of the page. For the sidebar, you can use either the route key or the [page identifier](core-concepts#page-identifiers). ### Changing the priorities From d021aca8d02980cfca30f1a9410239905e9473cf Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 19:07:36 +0200 Subject: [PATCH 139/232] Update headings to be more concise --- docs/digging-deeper/navigation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index addb37cbb61..c1fd6bd89e2 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -112,7 +112,7 @@ Let's explore how to customize navigation menus using configuration files: When customizing the main navigation menu, use the [route key](core-concepts#route-keys) of the page. For the sidebar, you can use either the route key or the [page identifier](core-concepts#page-identifiers). -### Changing the priorities +### Changing Priorities The `navigation.order` and `sidebar.order` settings allow you to customize the order of the pages in the navigation menus. @@ -145,7 +145,7 @@ The offset is added to make it easier to place pages earlier in the list using f ] ``` -#### Explicit syntax for changing the priorities +#### Explicit Priority Syntax You can also specify explicit priorities by adding a value to the array key: From a282b9cf1e38c8ba007378f334cf40829ee9d9c5 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 20:43:11 +0200 Subject: [PATCH 140/232] Update heading to be more concise --- docs/digging-deeper/navigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index c1fd6bd89e2..b36b9f3c08a 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -116,7 +116,7 @@ When customizing the main navigation menu, use the [route key](core-concepts#rou The `navigation.order` and `sidebar.order` settings allow you to customize the order of the pages in the navigation menus. -#### Basic syntax for changing the priorities +#### Basic Priority Syntax The cleanest way is to use the list-style syntax where each item will get the priority calculated according to its position in the list, plus an offset of `500`. The offset is added to make it easier to place pages earlier in the list using front matter or with explicit priority settings. From 143eb6dea46fd35c972fdbd2b351094aad78186f Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 20:43:16 +0200 Subject: [PATCH 141/232] Update sentence to be more concise --- docs/digging-deeper/navigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index b36b9f3c08a..dfa5a6a5d41 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -114,7 +114,7 @@ When customizing the main navigation menu, use the [route key](core-concepts#rou ### Changing Priorities -The `navigation.order` and `sidebar.order` settings allow you to customize the order of the pages in the navigation menus. +The `navigation.order` and `sidebar.order` settings allow you to customize the order of pages in the navigation menus. #### Basic Priority Syntax From 12c055c3fddc2d0a5e8624dd6f48f1a93c4dd70a Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 20:45:51 +0200 Subject: [PATCH 142/232] Rewrite introduction to be more fluent --- docs/digging-deeper/navigation.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index dfa5a6a5d41..b8c011200c0 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -118,8 +118,9 @@ The `navigation.order` and `sidebar.order` settings allow you to customize the o #### Basic Priority Syntax -The cleanest way is to use the list-style syntax where each item will get the priority calculated according to its position in the list, plus an offset of `500`. -The offset is added to make it easier to place pages earlier in the list using front matter or with explicit priority settings. +A nice and simple way to define the order of pages, is to add their route keys as a simple list array. We'll then match that array order. + +It may be useful to know that we internally will assign a priority calculated according to its position in the list, plus an offset of `500`. The offset is added to make it easier to place pages earlier in the list using front matter or with explicit priority settings. ```php // filepath: config/hyde.php From eed07c34005c2398dd890747f49c59d2df19183d Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 20:46:24 +0200 Subject: [PATCH 143/232] Remove unnecessary qualifiers from examples --- docs/digging-deeper/navigation.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index b8c011200c0..cb61d2372f8 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -127,9 +127,9 @@ It may be useful to know that we internally will assign a priority calculated ac 'navigation' => [ 'order' => [ - 'home', // Gets priority 500 - 'about', // Gets priority 501 - 'contact', // Gets priority 502 + 'home', // Priority: 500 + 'about', // Priority: 501 + 'contact', // Priority: 502 ] ] ``` @@ -139,9 +139,9 @@ It may be useful to know that we internally will assign a priority calculated ac 'sidebar' => [ 'order' => [ - 'readme', // Gets priority 500 - 'installation', // Gets priority 501 - 'getting-started', // Gets priority 502 + 'readme', // Priority: 500 + 'installation', // Priority: 501 + 'getting-started', // Priority: 502 ] ] ``` From 58e4ed038d9d2a8ff28608314022586b0a3f5770 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 20:48:49 +0200 Subject: [PATCH 144/232] Document explicitness in introduction instead in the examples --- docs/digging-deeper/navigation.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index cb61d2372f8..f671624c2d3 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -148,16 +148,16 @@ It may be useful to know that we internally will assign a priority calculated ac #### Explicit Priority Syntax -You can also specify explicit priorities by adding a value to the array key: +You can also specify explicit priorities by adding a value to the array keys. We'll then use these exact values as the priorities. ```php // filepath: config/hyde.php 'navigation' => [ 'order' => [ - 'home' => 10, // Gets priority 10 - 'about' => 15, // Gets priority 15 - 'contact' => 20, // Gets priority 20 + 'home' => 10, + 'about' => 15, + 'contact' => 20, ] ] ``` @@ -167,9 +167,9 @@ You can also specify explicit priorities by adding a value to the array key: 'sidebar' => [ 'order' => [ - 'readme' => 10, // Gets priority 10 - 'installation' => 15, // Gets priority 15 - 'getting-started' => 20, // Gets priority 20 + 'readme' => 10, + 'installation' => 15, + 'getting-started' => 20, ] ] ``` From 6eb7084fde5b4ff3f1702998ba2d66c793c05314 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 20:49:16 +0200 Subject: [PATCH 145/232] Remove extra lines from file path labels --- docs/digging-deeper/navigation.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index f671624c2d3..0fceaf2c8e9 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -124,7 +124,6 @@ It may be useful to know that we internally will assign a priority calculated ac ```php // filepath: config/hyde.php - 'navigation' => [ 'order' => [ 'home', // Priority: 500 @@ -136,7 +135,6 @@ It may be useful to know that we internally will assign a priority calculated ac ```php // filepath: config/docs.php - 'sidebar' => [ 'order' => [ 'readme', // Priority: 500 @@ -152,7 +150,6 @@ You can also specify explicit priorities by adding a value to the array keys. We ```php // filepath: config/hyde.php - 'navigation' => [ 'order' => [ 'home' => 10, @@ -164,7 +161,6 @@ You can also specify explicit priorities by adding a value to the array keys. We ```php // filepath: config/docs.php - 'sidebar' => [ 'order' => [ 'readme' => 10, From ecbbee3116bfcf03287d170797e41d85b6a7e3ef Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 20:49:37 +0200 Subject: [PATCH 146/232] Clean up section --- docs/digging-deeper/navigation.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 0fceaf2c8e9..0b6e5bf62d5 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -170,14 +170,14 @@ You can also specify explicit priorities by adding a value to the array keys. We ] ``` -**You can of course also combine these methods if you want:** +You could also combine these methods if desired: ```php // filepath: Applicable to both [ - 'readme' => 10, // Gets priority 10 - 'installation', // Gets priority 500 - 'getting-started', // Gets priority 501 + 'readme' => 10, // Priority: 10 + 'installation', // Priority: 500 + 'getting-started', // Priority: 501 ] ``` From 2385ac001d25bf3cd1594c7c6eb52d6ca2378388 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 20:50:03 +0200 Subject: [PATCH 147/232] Update heading to be more concise --- docs/digging-deeper/navigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 0b6e5bf62d5..3473fd75ceb 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -181,7 +181,7 @@ You could also combine these methods if desired: ] ``` -### Changing the menu item labels +### Changing Menu Item Labels Hyde makes a few attempts to find a suitable label for the navigation menu items to automatically create helpful titles. From b17bfe166e3e79a0bfee8e99ef86a13134b6b8b9 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 20:50:26 +0200 Subject: [PATCH 148/232] Normalize file path syntax --- docs/digging-deeper/navigation.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 3473fd75ceb..4314b911aef 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -189,7 +189,7 @@ From the Hyde config you can override the label of navigation links using the by This is not yet supported for the sidebar, but will be in the future. ```php -// filepath config/hyde.php +// filepath: config/hyde.php 'navigation' => [ 'labels' => [ 'index' => 'Start', @@ -204,7 +204,7 @@ Sometimes, especially if you have a lot of pages, you may want to prevent links To remove items from being automatically added, simply add the page's route key to the blacklist. ```php -// filepath config/hyde.php +// filepath: config/hyde.php 'navigation' => [ 'exclude' => [ '404' @@ -220,7 +220,7 @@ When linking to an external site, you should use the `NavigationItem::create()` destination and label, both required. The third argument is the priority, which is optional, and defaults to `500`. ```php -// filepath config/hyde.php +// filepath: config/hyde.php use Hyde\Framework\Features\Navigation\NavigationItem; 'navigation' => [ @@ -241,7 +241,7 @@ Simplified, this will then be rendered as follows: Within the Hyde config you can configure how subdirectories should be displayed in the menu. ```php -// filepath config/hyde.php +// filepath: config/hyde.php 'navigation' => [ 'subdirectory_display' => 'dropdown' ] From 1e32a89d5383fcc5ee16d6db1aba1cd2fae36f08 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 20:53:44 +0200 Subject: [PATCH 149/232] Remove introductory line offering no real information --- docs/digging-deeper/navigation.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 4314b911aef..8c4d98f340a 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -200,8 +200,7 @@ This is not yet supported for the sidebar, but will be in the future. ### Excluding Items (Blacklist) -Sometimes, especially if you have a lot of pages, you may want to prevent links from showing up in the main navigation menu. -To remove items from being automatically added, simply add the page's route key to the blacklist. +To prevent specific pages from showing up in the main navigation menu, simply add their route keys to the blacklist: ```php // filepath: config/hyde.php From 83bccaec3f527cea8354408a77518d74692eaf5c Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 20:54:27 +0200 Subject: [PATCH 150/232] Revert "Remove introductory line offering no real information" This reverts commit 1e32a89d5383fcc5ee16d6db1aba1cd2fae36f08. --- docs/digging-deeper/navigation.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 8c4d98f340a..4314b911aef 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -200,7 +200,8 @@ This is not yet supported for the sidebar, but will be in the future. ### Excluding Items (Blacklist) -To prevent specific pages from showing up in the main navigation menu, simply add their route keys to the blacklist: +Sometimes, especially if you have a lot of pages, you may want to prevent links from showing up in the main navigation menu. +To remove items from being automatically added, simply add the page's route key to the blacklist. ```php // filepath: config/hyde.php From aaeff4bd4f6fd6e2fbf4f35a4eed313d2f436cb8 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 20:56:52 +0200 Subject: [PATCH 151/232] Clean up introduction --- docs/digging-deeper/navigation.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 4314b911aef..34c7f79d62d 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -200,8 +200,9 @@ This is not yet supported for the sidebar, but will be in the future. ### Excluding Items (Blacklist) -Sometimes, especially if you have a lot of pages, you may want to prevent links from showing up in the main navigation menu. -To remove items from being automatically added, simply add the page's route key to the blacklist. +When you have a lot of pages, it may be useful to prevent links from being added to the main navigation menu. + +To exclude items from being added, simply add the page's route key to the navigation blacklist in the Hyde config: ```php // filepath: config/hyde.php From 984a02d9115e7bec8c1c284a2fa01074965f3609 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 20:57:36 +0200 Subject: [PATCH 152/232] Rewrite section to be more fluent --- docs/digging-deeper/navigation.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 34c7f79d62d..ef7608ef0fe 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -185,8 +185,7 @@ You could also combine these methods if desired: Hyde makes a few attempts to find a suitable label for the navigation menu items to automatically create helpful titles. -From the Hyde config you can override the label of navigation links using the by mapping the route key to the desired title. -This is not yet supported for the sidebar, but will be in the future. +If you're not happy with these, it's easy to override navigation link labels by mapping the route key to the desired title in the Hyde config: ```php // filepath: config/hyde.php @@ -198,6 +197,8 @@ This is not yet supported for the sidebar, but will be in the future. ] ``` +**Note:** This feature is not yet supported for the sidebar. + ### Excluding Items (Blacklist) When you have a lot of pages, it may be useful to prevent links from being added to the main navigation menu. From 0f925e14d9dfa7c6b2c1b7358dfb07bd30cfb834 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 21:01:34 +0200 Subject: [PATCH 153/232] Simplify custom navigation link section introduction --- docs/digging-deeper/navigation.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index ef7608ef0fe..2728eaa4a87 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -216,10 +216,7 @@ To exclude items from being added, simply add the page's route key to the naviga ### Adding Custom Navigation Menu Links -You can easily add custom navigation menu links similar to how we add Authors. Simply add a `NavigationItem` model to the `navigation.custom` array. - -When linking to an external site, you should use the `NavigationItem::create()` method facade. The first two arguments are the -destination and label, both required. The third argument is the priority, which is optional, and defaults to `500`. +You can easily add custom navigation menu links in the Hyde config: ```php // filepath: config/hyde.php From 13c5ef478a74a4b95dfb12dab8e2acec06035eb0 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 21:06:12 +0200 Subject: [PATCH 154/232] Update custom navigation links example to use new facade method --- docs/digging-deeper/navigation.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 2728eaa4a87..9f8e04ee4c5 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -220,11 +220,15 @@ You can easily add custom navigation menu links in the Hyde config: ```php // filepath: config/hyde.php -use Hyde\Framework\Features\Navigation\NavigationItem; +use Hyde\Facades\Navigation; 'navigation' => [ 'custom' => [ - NavigationItem::create('https://github.com/hydephp/hyde', 'GitHub', 200), + Navigation::item( + destination: 'https://github.com/hydephp/hyde', // Required + label: 'GitHub', // Optional, defaults to the destination value + priority: 200 // Optional, defaults to 500 + ), ] ] ``` From c186ae0b6a3b54d336ae9e77e0767d1788a9d1c2 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 21:06:32 +0200 Subject: [PATCH 155/232] Add tip on named arguments --- docs/digging-deeper/navigation.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 9f8e04ee4c5..0f3662a047e 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -233,6 +233,8 @@ use Hyde\Facades\Navigation; ] ``` +**Tip:** While named arguments are used in the example for clarity, they are not required. + Simplified, this will then be rendered as follows: ```html From b2f20575dc396ecf0ec56cc89e1961fb1ce3cc0f Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 21:07:01 +0200 Subject: [PATCH 156/232] Remove rendered HTML example Not sure how much value this offers --- docs/digging-deeper/navigation.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 0f3662a047e..8735c6de583 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -235,11 +235,6 @@ use Hyde\Facades\Navigation; **Tip:** While named arguments are used in the example for clarity, they are not required. -Simplified, this will then be rendered as follows: - -```html -GitHub -``` ### Configure subdirectory handling From 6ebd643e389fae46bd1e79812c5c188aee0a8c23 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 21:07:16 +0200 Subject: [PATCH 157/232] Normalize heading --- docs/digging-deeper/navigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 8735c6de583..c68fff88868 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -236,7 +236,7 @@ use Hyde\Facades\Navigation; **Tip:** While named arguments are used in the example for clarity, they are not required. -### Configure subdirectory handling +### Configure Subdirectory Display Within the Hyde config you can configure how subdirectories should be displayed in the menu. From 7c2f90cfffcf41a25fa2c4e9ecdeeaaf4fb361c1 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 21:12:10 +0200 Subject: [PATCH 158/232] Improve the subdirectory display section --- docs/digging-deeper/navigation.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index c68fff88868..04c575f296c 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -238,7 +238,7 @@ use Hyde\Facades\Navigation; ### Configure Subdirectory Display -Within the Hyde config you can configure how subdirectories should be displayed in the menu. +You can configure how subdirectories should be displayed in the menu: ```php // filepath: config/hyde.php @@ -247,9 +247,10 @@ Within the Hyde config you can configure how subdirectories should be displayed ] ``` -Dropdown means that pages in subdirectories will be displayed in a dropdown menu, -while `flat` means that pages in subdirectories will be displayed as individual items in the menu. -Hidden means that pages in subdirectories will not be displayed in the menu at all. +**Supported Options:** +- `dropdown`: Pages in subdirectories are displayed in a dropdown menu +- `hidden`: Pages in subdirectories are not displayed at all the menus +- `flat`: Pages in subdirectories are displayed as individual items ### Automatic menu groups From cc01ba341b1fee40a799f3b0991636fa291b958e Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 21:31:26 +0200 Subject: [PATCH 159/232] Normalize heading --- docs/digging-deeper/navigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 04c575f296c..cf84a14eeb0 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -252,7 +252,7 @@ You can configure how subdirectories should be displayed in the menu: - `hidden`: Pages in subdirectories are not displayed at all the menus - `flat`: Pages in subdirectories are displayed as individual items -### Automatic menu groups +### Automatic Menu Groups HydePHP has a neat feature to automatically place pages in dropdowns based on subdirectories. From 03262ef357218c21792ac7ee17efe13b18540821 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 21:57:28 +0200 Subject: [PATCH 160/232] Clean up the subdirectory grouping documentation --- docs/digging-deeper/navigation.md | 21 +++++++++------------ 1 file changed, 9 insertions(+), 12 deletions(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index cf84a14eeb0..dd55c32879c 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -254,15 +254,14 @@ You can configure how subdirectories should be displayed in the menu: ### Automatic Menu Groups -HydePHP has a neat feature to automatically place pages in dropdowns based on subdirectories. +A handy feature HydePHP has is that it can automatically place pages in dropdowns based on subdirectory structures. -#### Automatic navigation menu dropdowns +#### Automatic Navigation Menu Dropdowns -For pages that can be in the main site menu, this feature needs to be enabled in the `hyde.php` config file. +Enable this feature in the `hyde.php` config file by setting the `subdirectory_display` key to `dropdown`. ```php -// filepath config/hyde.php - +// filepath: config/hyde.php 'navigation' => [ 'subdirectory_display' => 'dropdown', ], @@ -270,20 +269,18 @@ For pages that can be in the main site menu, this feature needs to be enabled in Now if you create a page called `_pages/about/contact.md` it will automatically be placed in a dropdown called "About". -#### Automatic documentation sidebar grouping +#### Automatic Documentation Sidebar Grouping -This feature works similarly to the automatic navigation menu dropdowns, but instead places the sidebar items in named groups. -This feature is enabled by default, so you only need to place your pages in subdirectories to have them grouped. +This feature is always enabled for documentation pages. Simply place your pages in subdirectories to have them grouped in the sidebar. For example: `_docs/getting-started/installation.md` will be placed in a group called "Getting Started". >info Tip: When using subdirectory-based dropdowns, you can set their priority using the directory name as the array key. -#### Dropdown menu notes +#### Dropdown Menu Notes -Here are some things to keep in mind when using dropdown menus, regardless of the configuration: -- Dropdowns take priority over standard items. So if you have a dropdown with the key `about` and a page with the key `about`, the dropdown will be created, and the page won't be in the menu. - - For example: With this file structure: `_pages/foo.md`, `_pages/foo/bar.md`, `_pages/foo/baz.md`, the link to `foo` will be lost. +- Dropdowns take priority over standard items. If you have a dropdown with the key `about` and a page with the key `about`, the dropdown will be created, and the page won't be in the menu. +- Example: With this file structure: `_pages/foo.md`, `_pages/foo/bar.md`, `_pages/foo/baz.md`, the link to `foo` will be lost, so please keep this in mind when using this feature. ## Numerical Prefix Navigation Ordering From 2d1b20549ec623caf4d326385a55037e074a7af2 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 21:58:39 +0200 Subject: [PATCH 161/232] Clean up the Navigation API section to be more concise --- docs/digging-deeper/navigation.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index dd55c32879c..16cb6108e23 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -373,7 +373,6 @@ use Hyde\Framework\Features\Navigation\NavigationGroup; ## The Navigation API -If you want to interact with the site navigation programmatically, or if you want to create complex custom menus, you can do so through the new Navigation API. -For most cases you don't need this, as Hyde creates the navigation for you. But it can be useful for advanced users and package developers. +For advanced users and package developers, Hyde offers a Navigation API for programmatic interaction with site navigation. This API consists of a set of PHP classes allowing fluent interaction with navigation menus. -The Navigation API consists of a set of PHP classes, allowing you to fluently interact with the navigation menus. You can learn more about the API in the [Navigation API](navigation-api) documentation. +For more detailed information about the API, refer to the [Navigation API](navigation-api) documentation. From 5c1b73f7f8029b1dbe73f3b826d0c6b04d715545 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 22:00:56 +0200 Subject: [PATCH 162/232] Shorten the introduction to be more concise --- docs/digging-deeper/navigation.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 16cb6108e23..716e5a0a308 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -284,9 +284,7 @@ For example: `_docs/getting-started/installation.md` will be placed in a group c ## Numerical Prefix Navigation Ordering -HydePHP v2 introduces a new feature that allows navigation items to be ordered based on a numerical prefix in the filename. -This is a great way to control the ordering of pages in both the primary navigation menu and the documentation sidebar, -as your file structure will match the order of the pages in the navigation menus. +HydePHP v2 introduces navigation item ordering based on numerical prefixes in filenames. This feature works for both the primary navigation menu and the documentation sidebar. For example, the following will have the same order in the navigation menu as in a file explorer: From cfffe1d3553fcff66e31648255c73d92f7c9bd4c Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 22:01:40 +0200 Subject: [PATCH 163/232] Improve information presented in example introduction --- docs/digging-deeper/navigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 716e5a0a308..c6d52ef3aa3 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -286,7 +286,7 @@ For example: `_docs/getting-started/installation.md` will be placed in a group c HydePHP v2 introduces navigation item ordering based on numerical prefixes in filenames. This feature works for both the primary navigation menu and the documentation sidebar. -For example, the following will have the same order in the navigation menu as in a file explorer: +This has the great benefit of matching the navigation menu layout with the file structure view, and works especially great with subdirectory-based navigation grouping. ```shell _pages/ From f353b372410648ba0ac4b0410fc3dbaf006edb2b Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 22:03:11 +0200 Subject: [PATCH 164/232] Remove unnecessary information from example --- docs/digging-deeper/navigation.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index c6d52ef3aa3..032e3223d1b 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -290,9 +290,9 @@ This has the great benefit of matching the navigation menu layout with the file ```shell _pages/ - 01-home.md # Gets priority 1, putting it first (will be saved to _site/index.html) - 02-about.md # Gets priority 2, putting it second (will be saved to _site/about.html) - 03-contact.md # Gets priority 3, putting it third (will be saved to _site/contact.html) + 01-home.md # Priority: 1 (saved to _site/index.html) + 02-about.md # Priority: 2 (saved to _site/about.html) + 03-contact.md # Priority: 3 (saved to _site/contact.html) ``` Hyde will then parse the number from the filename and use it as the priority for the page in the navigation menus. From 2ff20cdcbda7e79708ccdcb2dd34026cfb8c8fe4 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 22:03:24 +0200 Subject: [PATCH 165/232] Merge in prefix stripping information into line --- docs/digging-deeper/navigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 032e3223d1b..b4b88b04ca6 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -295,7 +295,7 @@ _pages/ 03-contact.md # Priority: 3 (saved to _site/contact.html) ``` -Hyde will then parse the number from the filename and use it as the priority for the page in the navigation menus. +As you can seem Hyde parses the number from the filename and uses it as the priority for the page in navigation menus, while stripping the prefix from the route key. ### Keep in mind From 3e6b3b009a1252f337db5a7229a673fc67226ec4 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 22:03:38 +0200 Subject: [PATCH 166/232] Rename heading --- docs/digging-deeper/navigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index b4b88b04ca6..0c83b1f73c3 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -297,7 +297,7 @@ _pages/ As you can seem Hyde parses the number from the filename and uses it as the priority for the page in navigation menus, while stripping the prefix from the route key. -### Keep in mind +### Important Notes Here are some things to keep in mind, especially if you mix numerical prefix ordering with other ordering methods: From f7e71fd910d4eabfc3bbc020046aca171f0284f3 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 22:05:19 +0200 Subject: [PATCH 167/232] Remove introduction containing discouraged usage --- docs/digging-deeper/navigation.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 0c83b1f73c3..47608ed2385 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -299,7 +299,6 @@ As you can seem Hyde parses the number from the filename and uses it as the prio ### Important Notes -Here are some things to keep in mind, especially if you mix numerical prefix ordering with other ordering methods: 1. The numerical prefix will still be part of the page identifier, but it will be stripped from the route key. - For example: `_pages/01-home.md` will have the route key `home` and the page identifier `01-home`. From f18507f0db19aa250cfc83de6ff4e055afcf54c0 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 22:06:25 +0200 Subject: [PATCH 168/232] Remove extra newline --- docs/digging-deeper/navigation.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 47608ed2385..00796c89872 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -299,7 +299,6 @@ As you can seem Hyde parses the number from the filename and uses it as the prio ### Important Notes - 1. The numerical prefix will still be part of the page identifier, but it will be stripped from the route key. - For example: `_pages/01-home.md` will have the route key `home` and the page identifier `01-home`. 2. You can delimit the numerical prefix with either a dash or an underscore. From ee0e57f695c3651c366cecc863704d48c553b9cf Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 22:06:50 +0200 Subject: [PATCH 169/232] Use more concise language --- docs/digging-deeper/navigation.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 00796c89872..67d7c9df638 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -299,11 +299,11 @@ As you can seem Hyde parses the number from the filename and uses it as the prio ### Important Notes -1. The numerical prefix will still be part of the page identifier, but it will be stripped from the route key. - - For example: `_pages/01-home.md` will have the route key `home` and the page identifier `01-home`. +1. The numerical prefix remains part of the page identifier but is stripped from the route key. + For example: `_pages/01-home.md` has route key `home` and page identifier `01-home`. 2. You can delimit the numerical prefix with either a dash or an underscore. - - For example: `_pages/01-home.md` and `_pages/01_home.md` are both valid. -3. The leading zeroes are optional, so `_pages/1-home.md` is also valid. + For example: Both `_pages/01-home.md` and `_pages/01_home.md` are valid. +3. Leading zeros are optional. `_pages/1-home.md` is equally valid. ### Using numerical prefix ordering in subdirectories From 23ff410807405bed7e5f908d631202f780b76a79 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 22:07:07 +0200 Subject: [PATCH 170/232] Normalize heading --- docs/digging-deeper/navigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 67d7c9df638..1a2fd68bf90 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -305,7 +305,7 @@ As you can seem Hyde parses the number from the filename and uses it as the prio For example: Both `_pages/01-home.md` and `_pages/01_home.md` are valid. 3. Leading zeros are optional. `_pages/1-home.md` is equally valid. -### Using numerical prefix ordering in subdirectories +### Using Numerical Prefix Ordering in Subdirectories The numerical prefix ordering feature works great when using the automatic subdirectory-based grouping for navigation menu dropdowns and documentation sidebar categories. From a505a0b626b2ba62e62128d9ef31a4687d98a474 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 22:08:05 +0200 Subject: [PATCH 171/232] Use more concise wording --- docs/digging-deeper/navigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 1a2fd68bf90..0f6cd5f7573 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -313,7 +313,7 @@ This integration has two main features to consider: 1. You can use numerical prefixes in subdirectories to control the order of dropdowns. 2. The ordering within a subdirectory works independently of its siblings, so you can start from one in each subdirectory. -Here is an example structure of how you may want to organize a documentation site: +Here is an example structure of how could organize a documentation site: ```shell _docs/ From a32354c0d66607daa013a227ef9c2a1661e166a4 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 22:08:16 +0200 Subject: [PATCH 172/232] Use more concise wording --- docs/digging-deeper/navigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 0f6cd5f7573..abed3eb3432 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -307,7 +307,7 @@ As you can seem Hyde parses the number from the filename and uses it as the prio ### Using Numerical Prefix Ordering in Subdirectories -The numerical prefix ordering feature works great when using the automatic subdirectory-based grouping for navigation menu dropdowns and documentation sidebar categories. +This feature integrates well with automatic subdirectory-based grouping for navigation menu dropdowns and documentation sidebar categories: This integration has two main features to consider: 1. You can use numerical prefixes in subdirectories to control the order of dropdowns. From 995bd8148021a0141cf07f4a3fce52f91f4f5c4f Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 22:10:20 +0200 Subject: [PATCH 173/232] Update section to be more concise --- docs/digging-deeper/navigation.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index abed3eb3432..9d82c7df5fa 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -307,11 +307,10 @@ As you can seem Hyde parses the number from the filename and uses it as the prio ### Using Numerical Prefix Ordering in Subdirectories -This feature integrates well with automatic subdirectory-based grouping for navigation menu dropdowns and documentation sidebar categories: +This feature integrates well with automatic subdirectory-based navigation grouping. Here are two useful tips: -This integration has two main features to consider: -1. You can use numerical prefixes in subdirectories to control the order of dropdowns. -2. The ordering within a subdirectory works independently of its siblings, so you can start from one in each subdirectory. +1. You can use numerical prefixes in subdirectories to control the dropdown/sidebar order. +2. The numbering within a subdirectory works independently of its siblings, so you can start from one in each subdirectory. Here is an example structure of how could organize a documentation site: From 23e610d104bdd95adcfa3f901ae10b573af398df Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 22:11:28 +0200 Subject: [PATCH 174/232] Remove section detailing discouraged use with no real benefit --- docs/digging-deeper/navigation.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 9d82c7df5fa..7fefa32f269 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -338,7 +338,6 @@ You can disable this feature by setting the `numerical_page_ordering` setting to 'numerical_page_ordering' => false, ``` -While it's not recommended, as you lose out on the convenience of the automatic ordering, any front matter priority settings will override the numerical prefix ordering if you for some reason need to. ## Digging Deeper into the internals From e8639f487e9f7e3760a4958567e100a6979c2f64 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 22:12:14 +0200 Subject: [PATCH 175/232] Reword section introduction --- docs/digging-deeper/navigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 7fefa32f269..e7702c4926a 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -330,7 +330,7 @@ _docs/ ### Customization -You can disable this feature by setting the `numerical_page_ordering` setting to `false` in the `hyde.php` config file. Hyde will then no longer extract the priority and will no longer strip the prefix from the route key. +If you're not interested in using numerical prefix ordering, you can disable it in the Hyde config file. Hyde will then no longer extract the priority and will no longer strip the prefix from the route key. ```php // filepath config/hyde.php From f0e2ff3330d1871bd920fc7cd03df286ebcdd660 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 22:12:24 +0200 Subject: [PATCH 176/232] Normalize file path label syntax --- docs/digging-deeper/navigation.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index e7702c4926a..bed7f3d1488 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -333,8 +333,7 @@ _docs/ If you're not interested in using numerical prefix ordering, you can disable it in the Hyde config file. Hyde will then no longer extract the priority and will no longer strip the prefix from the route key. ```php -// filepath config/hyde.php - +// filepath: config/hyde.php 'numerical_page_ordering' => false, ``` From 14e5c4c0d7fee93855ccc3aebbd574a3baf4103d Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 22:12:36 +0200 Subject: [PATCH 177/232] Normalize heading formatting --- docs/digging-deeper/navigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index bed7f3d1488..f5cf1737888 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -338,7 +338,7 @@ If you're not interested in using numerical prefix ordering, you can disable it ``` -## Digging Deeper into the internals +## Digging Deeper into the Internals While not required to know, you may find it interesting to learn more about how the navigation is handled internally. Here is a high level overview, but you can find more detailed information in the [Navigation API](navigation-api) documentation. From 519002a35d91145f61ad259d0b13036402d73dfe Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 22:13:43 +0200 Subject: [PATCH 178/232] Remove newline --- docs/digging-deeper/navigation.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index f5cf1737888..e809f33d418 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -337,7 +337,6 @@ If you're not interested in using numerical prefix ordering, you can disable it 'numerical_page_ordering' => false, ``` - ## Digging Deeper into the Internals While not required to know, you may find it interesting to learn more about how the navigation is handled internally. Here is a high level overview, From bd2f05a9b8e05df2c30c0e28a1136b674b1b3c44 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 22:15:11 +0200 Subject: [PATCH 179/232] Merge introduction sections --- docs/digging-deeper/navigation.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index e809f33d418..949c92cf8e8 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -339,8 +339,7 @@ If you're not interested in using numerical prefix ordering, you can disable it ## Digging Deeper into the Internals -While not required to know, you may find it interesting to learn more about how the navigation is handled internally. Here is a high level overview, -but you can find more detailed information in the [Navigation API](navigation-api) documentation. +While not essential, understanding the internal workings of the navigation system can be as beneficial as it's interesting. Here's a quick high-level overview of the [Navigation API](navigation-api). The main navigation menu is the `MainNavigationMenu` class, and the documentation sidebar is the `DocumentationSidebar` class. Both extend the same base `NavigationMenu` class. From 9206cf410dc7075f8c111e8a9a3f77bf4c576eec Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 22:15:48 +0200 Subject: [PATCH 180/232] Add subheading --- docs/digging-deeper/navigation.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 949c92cf8e8..4c50dfee198 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -341,6 +341,8 @@ If you're not interested in using numerical prefix ordering, you can disable it While not essential, understanding the internal workings of the navigation system can be as beneficial as it's interesting. Here's a quick high-level overview of the [Navigation API](navigation-api). +### Navigation Menu Classes + The main navigation menu is the `MainNavigationMenu` class, and the documentation sidebar is the `DocumentationSidebar` class. Both extend the same base `NavigationMenu` class. ```php From 17bf95fa9bbeca9c5ec33812ddf0b1fd089e3846 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 22:16:43 +0200 Subject: [PATCH 181/232] Reword and summarize parts of the internals overview --- docs/digging-deeper/navigation.md | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 4c50dfee198..1f037908a70 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -343,7 +343,7 @@ While not essential, understanding the internal workings of the navigation syste ### Navigation Menu Classes -The main navigation menu is the `MainNavigationMenu` class, and the documentation sidebar is the `DocumentationSidebar` class. Both extend the same base `NavigationMenu` class. +The main navigation menu uses the `MainNavigationMenu` class, while the documentation sidebar uses the `DocumentationSidebar` class. Both extend the base `NavigationMenu` class: ```php use Hyde\Framework\Features\Navigation\MainNavigationMenu; @@ -351,13 +351,9 @@ use Hyde\Framework\Features\Navigation\DocumentationSidebar; use Hyde\Framework\Features\Navigation\NavigationMenu; ``` -Within the base `NavigationMenu` class, you will find the main logic for how the menus are generated, -while the child implementations contain the extra logic tailored for their specific use cases. +The base `NavigationMenu` class contains the main logic for menu generation, while child implementations contain extra logic for specific use cases. -All the navigation menus store the menu items in their `$items` collection containing instances of the `NavigationItem` class. - -The `NavigationItem` class is a simple class that contains the label and URL of the menu item and is used to represent each item in the menu. -Dropdowns are represented by `NavigationGroup` instances, which extend the `NavigationMenu` class and contain a collection of additional `NavigationItem` instances. +All navigation menus store items in their `$items` collection, containing instances of the `NavigationItem` class. Dropdowns are represented by `NavigationGroup` instances, which extend the `NavigationMenu` class and contain additional `NavigationItem` instances: ```php use Hyde\Framework\Features\Navigation\NavigationItem; From b47bae066476f74577915572be52a51ebdddee72 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Thu, 11 Jul 2024 22:18:47 +0200 Subject: [PATCH 182/232] Link to the related class --- packages/framework/src/Facades/Navigation.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/framework/src/Facades/Navigation.php b/packages/framework/src/Facades/Navigation.php index 1f64d809f3c..2eb846b0613 100644 --- a/packages/framework/src/Facades/Navigation.php +++ b/packages/framework/src/Facades/Navigation.php @@ -16,7 +16,7 @@ class Navigation /** * Configuration helper method to define a new navigation item, with better IDE support. * - * The returned array will then be used by the framework to create a new NavigationItem instance. + * The returned array will then be used by the framework to create a new NavigationItem instance. {@see \Hyde\Framework\Features\Navigation\NavigationItem} * * @see https://hydephp.com/docs/2.x/navigation-api * From 901b810ef1f0846b1cb4bc30780ba2a2f1d568c1 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 12 Jul 2024 10:42:54 +0200 Subject: [PATCH 183/232] Create Claude draft --- context.php | 330 ++++++++++++++++++++++++++ docs/digging-deeper/navigation.md | 371 ++++++++---------------------- 2 files changed, 428 insertions(+), 273 deletions(-) create mode 100644 context.php diff --git a/context.php b/context.php new file mode 100644 index 00000000000..b338e14ca4d --- /dev/null +++ b/context.php @@ -0,0 +1,330 @@ + + /* + |-------------------------------------------------------------------------- + | Navigation Menu Configuration + |-------------------------------------------------------------------------- + | + | If you are looking to customize the main navigation menu, this is the place! + | + | All these settings uses Route Keys to identify the page you want to configure. + | A route key is simply the URL path to the page, without the file extension. + | So `_site/posts/hello-world.html` has the route key 'posts/hello-world'. + | + */ + + // OLD + + 'navigation' => [ + // This configuration sets the priorities used to determine the order of the menu. + // The default values have been added below for reference and easy editing. + // The array key is the page's route key, the value is the priority. + // Lower values show up first in the menu. The default is 999. + 'order' => [ + 'index' => 0, + 'posts' => 10, + 'docs/index' => 100, + ], + + // In case you want to customize the labels for the menu items, you can do so here. + // Simply add the route key as the array key, and the label as the value. + 'labels' => [ + 'index' => 'Home', + 'docs/index' => 'Docs', + ], + + // These are the route keys of pages that should not show up in the navigation menu. + 'exclude' => [ + '404', + ], + + // Any extra links you want to add to the navigation menu can be added here. + // To get started quickly, you can uncomment the defaults here. + // See the documentation link above for more information. + 'custom' => [ + // NavigationItem::create('https://github.com/hydephp/hyde', 'GitHub', 200), + ], + + // How should pages in subdirectories be displayed in the menu? + // You can choose between 'dropdown', 'flat', and 'hidden'. + 'subdirectories' => 'hidden', + ], + + + // NEW (creates an array exactly like the one above, but with a more fluent API that supports better autocomplete) + + 'navigation' => Navigation::configure() + ->setPagePriorities([ + 'index' => 0, + 'posts' => 10, + 'docs/index' => 100, + ]) + ->setPageLabels([ + 'index' => 'Home', + 'docs/index' => 'Docs', + ]) + ->excludePages([ + '404', + ]) + ->addNavigationItems([ + // Navigation::item('https://github.com/hydephp/hyde', 'GitHub', 200), + ]) + ->setSubdirectoryDisplayMode('hidden'), + + // All of these options work in the yaml config (this is just an example, please use the same example data as above in the docs) + hyde: + navigation: + custom: + - destination: 'https://example.com' + label: 'Example' + priority: 100 + attributes: + class: 'example' + - destination: 'about' + label: 'About Us' + priority: 200 + attributes: + class: 'about' + id: 'about' + - destination: 'contact' + label: 'Contact' + priority: 300 + attributes: + target: '_blank' + rel: 'noopener noreferrer' + foo: 'bar' + + +// relevant code snippets + +|string $destination Route key, or an external URI. + * @param string|null $label If not provided, Hyde will try to get it from the route's connected page, or from the URL. + * @param int|null $priority If not provided, Hyde will try to get it from the route or the default priority of 500. + * @param array $attributes Additional attributes for the navigation item. + * @return array{destination: string, label: ?string, priority: ?int, attributes: array} + */ + public static function item(string $destination, ?string $label = null, ?int $priority = null, array $attributes = []): array + { + return compact('destination', 'label', 'priority', 'attributes'); + } + + /** + * Configuration helper method to define the navigation menu configuration with better IDE support. + * + * The builder is an array object that will be used by the framework to set the navigation menu configuration. + * + * @experimental This method is experimental and may change or be removed before the final release. + */ + public static function configure(): NavigationMenuConfigurationBuilder + { + return new NavigationMenuConfigurationBuilder(); + } +} + +|array $order + * @return $this + */ + public function setPagePriorities(array $order): static + { + $this['order'] = $order; + + return $this; + } + + /** + * Set the labels for the navigation items. + * + * Each key should be a route key, and the value should be the label to display. + * + * @param array $labels + * @return $this + */ + public function setPageLabels(array $labels): static + { + $this['labels'] = $labels; + + return $this; + } + + /** + * Exclude certain items from the navigation. + * + * Each item should be a route key for the page to exclude. + * + * @param array $exclude + * @return $this + */ + public function excludePages(array $exclude): static + { + $this['exclude'] = $exclude; + + return $this; + } + + /** + * Add custom items to the navigation. + * + * @example `[Navigation::item('https://github.com/hydephp/hyde', 'GitHub', 200, ['target' => '_blank'])]` + * + * @param array}> $custom + * @return $this + */ + public function addNavigationItems(array $custom): static + { + $this['custom'] = $custom; + + return $this; + } + + /** + * Set the display mode for pages in subdirectories. + * + * You can choose between 'dropdown', 'flat', and 'hidden'. The default is 'hidden'. + * + * @param 'dropdown'|'flat'|'hidden' $displayMode + * @return $this + */ + public function setSubdirectoryDisplayMode(string $displayMode): static + { + self::assertType(['dropdown', 'flat', 'hidden'], $displayMode); + + $this['subdirectory_display'] = $displayMode; + + return $this; + } + + /** + * Hide pages in subdirectories from the navigation. + * + * @experimental This method is experimental and may change or be removed before the final release. + * + * @return $this + */ + public function hideSubdirectoriesFromNavigation(): static + { + return $this->setSubdirectoryDisplayMode('hidden'); + } + + /** + * Get the instance as an array. + * + * @return array{order: array, labels: array, exclude: array, custom: array}>, subdirectory_display: string} + */ + public function toArray(): array + { + return $this->getArrayCopy(); + } + + /** @experimental May be moved to a separate helper class in the future. */ + protected static function assertType(array $types, string $value): void + { + if (! in_array($value, $types)) { + throw new TypeError('Value must be one of: '.implode(', ', $types)); + } + } +} + + +// The docs config has not been updated to use the builder api + + /* + |-------------------------------------------------------------------------- + | Sidebar Settings + |-------------------------------------------------------------------------- + | + | The Hyde Documentation Module comes with a fancy Sidebar that is + | automatically populated with links to your documentation pages. + | Here, you can configure its behavior, content, look and feel. + | + */ + + 'sidebar' => [ + // The title in the sidebar header + 'header' => env('SITE_NAME', 'HydePHP').' Docs', + + // When using a grouped sidebar, should the groups be collapsible? + 'collapsible' => true, + + // 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, + ], + + ], \ No newline at end of file diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 1f037908a70..36482372801 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -37,331 +37,156 @@ Here's an overview of what you can customize in your navigation menus: - Item visibility: Choose to hide or show pages in the menu - Item grouping: Group pages together in dropdowns or sidebar categories -### Customization Methods +## Configuration Methods Hyde provides multiple ways to customize navigation menus to suit your needs: 1. Front matter data in Markdown and Blade page files, applicable to all menu types -2. Configuration in the `hyde` config file for main navigation items -3. Configuration in the `docs` config file for documentation sidebar items +2. Configuration in the `hyde.php` or `hyde.yml` config file for main navigation items +3. Configuration in the `docs.php` config file for documentation sidebar items -Keep in mind that front matter data overrides dynamically inferred or config-defined priorities. While useful for quick one-off changes on small sites, it can make reordering items later on more challenging as you can't see the entire structure at once. +The new builder pattern in the configuration allows for a more fluent and IDE-friendly way to customize navigation. However, the old array-based method still works, as the navigation builder is an `ArrayObject` and can be used as an array. -Additionally, general options for the entire navigation menus are also available in the `hyde` and `docs` config files. +### Using the Navigation Builder -## Front Matter Configuration - -Front matter options allow per-page customization of navigation menus. Here's a quick reference of available options: - -```yaml -navigation: - label: string # The displayed text in the navigation item link - priority: int # The page's priority for ordering (lower means higher up/first) - hidden: bool # Whether the page should be hidden from the navigation menu - group: string # Set main menu dropdown or sidebar group key -``` - -You only need to specify the keys you want to customize. - -### `label` - -Customizes the text appearing in the navigation menu link for the page. If not set anywhere else, Hyde will search for a title in the page content or generate one from the filename. - -```yaml -navigation: - label: "My Custom Label" -``` - -### `priority` - -Controls the order in which the page appears in the navigation menu. - -```yaml -navigation: - priority: 10 -``` - -### `hidden` - -Determines if the page appears in the navigation menu. - -```yaml -navigation: - hidden: true -``` - -**Tip:** You can also use `visible: false` to achieve the same effect. - -### `group` - -For the primary navigation menu, this groups pages together in dropdowns. For the sidebar, it groups pages under a common heading. - -```yaml -navigation: - group: "My Group" -``` - -**Note:** Sidebar group keys are normalized, so `My Group` and `my-group` are equivalent. - -## Config File Configuration - -Let's explore how to customize navigation menus using configuration files: - -- For the main navigation menu, use `navigation` setting in the `hyde.php` config file. -- For the sidebar, use `sidebar` setting in the `docs.php` config file. - -When customizing the main navigation menu, use the [route key](core-concepts#route-keys) of the page. For the sidebar, you can use either the route key or the [page identifier](core-concepts#page-identifiers). - -### Changing Priorities - -The `navigation.order` and `sidebar.order` settings allow you to customize the order of pages in the navigation menus. - -#### Basic Priority Syntax - -A nice and simple way to define the order of pages, is to add their route keys as a simple list array. We'll then match that array order. - -It may be useful to know that we internally will assign a priority calculated according to its position in the list, plus an offset of `500`. The offset is added to make it easier to place pages earlier in the list using front matter or with explicit priority settings. +To use the new builder pattern, you can configure your navigation in the `hyde.php` file like this: ```php -// filepath: config/hyde.php -'navigation' => [ - 'order' => [ - 'home', // Priority: 500 - 'about', // Priority: 501 - 'contact', // Priority: 502 - ] -] -``` +use Hyde\Facades\Navigation; -```php -// filepath: config/docs.php -'sidebar' => [ - 'order' => [ - 'readme', // Priority: 500 - 'installation', // Priority: 501 - 'getting-started', // Priority: 502 - ] -] -``` +return [ + // ... + + 'navigation' => Navigation::configure() + ->setPagePriorities([ + 'index' => 0, + 'posts' => 10, + 'docs/index' => 100, + ]) + ->setPageLabels([ + 'index' => 'Home', + 'docs/index' => 'Docs', + ]) + ->excludePages([ + '404', + ]) + ->addNavigationItems([ + Navigation::item('https://github.com/hydephp/hyde', 'GitHub', 200), + ]) + ->setSubdirectoryDisplayMode('hidden'), +]; +``` + +### Using YAML Configuration + +You can also set the navigation configuration in the `hyde.yml` file. The structure remains the same as the array-based method: -#### Explicit Priority Syntax +```yaml +hyde: + navigation: + order: + index: 0 + posts: 10 + docs/index: 100 + labels: + index: Home + docs/index: Docs + exclude: + - 404 + custom: + - destination: 'https://github.com/hydephp/hyde' + label: 'GitHub' + priority: 200 + subdirectory_display: hidden +``` + +## Customization Options -You can also specify explicit priorities by adding a value to the array keys. We'll then use these exact values as the priorities. +Here's an overview of what you can customize in your navigation menus: -```php -// filepath: config/hyde.php -'navigation' => [ - 'order' => [ - 'home' => 10, - 'about' => 15, - 'contact' => 20, - ] -] -``` +- Item labels: The text displayed in menu links +- Item priorities: Control the order of link appearance +- Item visibility: Choose to hide or show pages in the menu +- Item grouping: Group pages together in dropdowns or sidebar categories -```php -// filepath: config/docs.php -'sidebar' => [ - 'order' => [ - 'readme' => 10, - 'installation' => 15, - 'getting-started' => 20, - ] -] -``` +### Setting Page Priorities -You could also combine these methods if desired: +Use the `setPagePriorities` method to define the order of pages in the navigation menu: ```php -// filepath: Applicable to both -[ - 'readme' => 10, // Priority: 10 - 'installation', // Priority: 500 - 'getting-started', // Priority: 501 -] +->setPagePriorities([ + 'index' => 0, + 'posts' => 10, + 'docs/index' => 100, +]) ``` ### Changing Menu Item Labels -Hyde makes a few attempts to find a suitable label for the navigation menu items to automatically create helpful titles. - -If you're not happy with these, it's easy to override navigation link labels by mapping the route key to the desired title in the Hyde config: +Override navigation link labels using the `setPageLabels` method: ```php -// filepath: config/hyde.php -'navigation' => [ - 'labels' => [ - 'index' => 'Start', - 'docs/index' => 'Documentation', - ] -] +->setPageLabels([ + 'index' => 'Home', + 'docs/index' => 'Documentation', +]) ``` -**Note:** This feature is not yet supported for the sidebar. - -### Excluding Items (Blacklist) +### Excluding Items -When you have a lot of pages, it may be useful to prevent links from being added to the main navigation menu. - -To exclude items from being added, simply add the page's route key to the navigation blacklist in the Hyde config: +Prevent links from being added to the main navigation menu using the `excludePages` method: ```php -// filepath: config/hyde.php -'navigation' => [ - 'exclude' => [ - '404' - ] -] +->excludePages([ + '404', +]) ``` ### Adding Custom Navigation Menu Links -You can easily add custom navigation menu links in the Hyde config: +Add custom navigation menu links using the `addNavigationItems` method: ```php -// filepath: config/hyde.php -use Hyde\Facades\Navigation; - -'navigation' => [ - 'custom' => [ - Navigation::item( - destination: 'https://github.com/hydephp/hyde', // Required - label: 'GitHub', // Optional, defaults to the destination value - priority: 200 // Optional, defaults to 500 - ), - ] -] +->addNavigationItems([ + Navigation::item('https://github.com/hydephp/hyde', 'GitHub', 200), +]) ``` -**Tip:** While named arguments are used in the example for clarity, they are not required. - - ### Configure Subdirectory Display -You can configure how subdirectories should be displayed in the menu: +Set how subdirectories should be displayed in the menu using the `setSubdirectoryDisplayMode` method: ```php -// filepath: config/hyde.php -'navigation' => [ - 'subdirectory_display' => 'dropdown' -] +->setSubdirectoryDisplayMode('dropdown') ``` -**Supported Options:** -- `dropdown`: Pages in subdirectories are displayed in a dropdown menu -- `hidden`: Pages in subdirectories are not displayed at all the menus -- `flat`: Pages in subdirectories are displayed as individual items - -### Automatic Menu Groups +Supported options are 'dropdown', 'hidden', and 'flat'. -A handy feature HydePHP has is that it can automatically place pages in dropdowns based on subdirectory structures. - -#### Automatic Navigation Menu Dropdowns +## Front Matter Configuration -Enable this feature in the `hyde.php` config file by setting the `subdirectory_display` key to `dropdown`. +Front matter options allow per-page customization of navigation menus. These options remain unchanged: -```php -// filepath: config/hyde.php -'navigation' => [ - 'subdirectory_display' => 'dropdown', -], +```yaml +navigation: + label: string # The displayed text in the navigation item link + priority: int # The page's priority for ordering (lower means higher up/first) + hidden: bool # Whether the page should be hidden from the navigation menu + group: string # Set main menu dropdown or sidebar group key ``` -Now if you create a page called `_pages/about/contact.md` it will automatically be placed in a dropdown called "About". - -#### Automatic Documentation Sidebar Grouping - -This feature is always enabled for documentation pages. Simply place your pages in subdirectories to have them grouped in the sidebar. - -For example: `_docs/getting-started/installation.md` will be placed in a group called "Getting Started". - ->info Tip: When using subdirectory-based dropdowns, you can set their priority using the directory name as the array key. - -#### Dropdown Menu Notes - -- Dropdowns take priority over standard items. If you have a dropdown with the key `about` and a page with the key `about`, the dropdown will be created, and the page won't be in the menu. -- Example: With this file structure: `_pages/foo.md`, `_pages/foo/bar.md`, `_pages/foo/baz.md`, the link to `foo` will be lost, so please keep this in mind when using this feature. - ## Numerical Prefix Navigation Ordering -HydePHP v2 introduces navigation item ordering based on numerical prefixes in filenames. This feature works for both the primary navigation menu and the documentation sidebar. +The numerical prefix navigation ordering feature remains unchanged. You can still use numerical prefixes in filenames to control the order of navigation items. -This has the great benefit of matching the navigation menu layout with the file structure view, and works especially great with subdirectory-based navigation grouping. - -```shell -_pages/ - 01-home.md # Priority: 1 (saved to _site/index.html) - 02-about.md # Priority: 2 (saved to _site/about.html) - 03-contact.md # Priority: 3 (saved to _site/contact.html) -``` - -As you can seem Hyde parses the number from the filename and uses it as the priority for the page in navigation menus, while stripping the prefix from the route key. - -### Important Notes - -1. The numerical prefix remains part of the page identifier but is stripped from the route key. - For example: `_pages/01-home.md` has route key `home` and page identifier `01-home`. -2. You can delimit the numerical prefix with either a dash or an underscore. - For example: Both `_pages/01-home.md` and `_pages/01_home.md` are valid. -3. Leading zeros are optional. `_pages/1-home.md` is equally valid. - -### Using Numerical Prefix Ordering in Subdirectories - -This feature integrates well with automatic subdirectory-based navigation grouping. Here are two useful tips: - -1. You can use numerical prefixes in subdirectories to control the dropdown/sidebar order. -2. The numbering within a subdirectory works independently of its siblings, so you can start from one in each subdirectory. - -Here is an example structure of how could organize a documentation site: - -```shell -_docs/ - 01-getting-started/ - 01-installation.md - 02-requirements.md - 03-configuration.md - 02-usage/ - 01-quick-start.md - 02-advanced-usage.md - 03-features/ - 01-feature-1.md - 02-feature-2.md -``` - -### Customization - -If you're not interested in using numerical prefix ordering, you can disable it in the Hyde config file. Hyde will then no longer extract the priority and will no longer strip the prefix from the route key. +To disable this feature, you can use the following configuration: ```php -// filepath: config/hyde.php -'numerical_page_ordering' => false, +return [ + // ... + 'numerical_page_ordering' => false, +]; ``` -## Digging Deeper into the Internals - -While not essential, understanding the internal workings of the navigation system can be as beneficial as it's interesting. Here's a quick high-level overview of the [Navigation API](navigation-api). - -### Navigation Menu Classes - -The main navigation menu uses the `MainNavigationMenu` class, while the documentation sidebar uses the `DocumentationSidebar` class. Both extend the base `NavigationMenu` class: - -```php -use Hyde\Framework\Features\Navigation\MainNavigationMenu; -use Hyde\Framework\Features\Navigation\DocumentationSidebar; -use Hyde\Framework\Features\Navigation\NavigationMenu; -``` - -The base `NavigationMenu` class contains the main logic for menu generation, while child implementations contain extra logic for specific use cases. - -All navigation menus store items in their `$items` collection, containing instances of the `NavigationItem` class. Dropdowns are represented by `NavigationGroup` instances, which extend the `NavigationMenu` class and contain additional `NavigationItem` instances: - -```php -use Hyde\Framework\Features\Navigation\NavigationItem; -use Hyde\Framework\Features\Navigation\NavigationGroup; -``` - -## The Navigation API - -For advanced users and package developers, Hyde offers a Navigation API for programmatic interaction with site navigation. This API consists of a set of PHP classes allowing fluent interaction with navigation menus. +## Conclusion -For more detailed information about the API, refer to the [Navigation API](navigation-api) documentation. +The new builder pattern provides a more fluent and IDE-friendly way to configure navigation in HydePHP. However, the old array-based method and YAML configuration are still supported, giving you flexibility in how you choose to customize your site's navigation. \ No newline at end of file From d51c4af5e4cc2810b9616769c1d4178f81ce6f2b Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 12 Jul 2024 12:54:18 +0200 Subject: [PATCH 184/232] Revert "Create Claude draft" This reverts commit 901b810ef1f0846b1cb4bc30780ba2a2f1d568c1. --- context.php | 330 -------------------------- docs/digging-deeper/navigation.md | 371 ++++++++++++++++++++++-------- 2 files changed, 273 insertions(+), 428 deletions(-) delete mode 100644 context.php diff --git a/context.php b/context.php deleted file mode 100644 index b338e14ca4d..00000000000 --- a/context.php +++ /dev/null @@ -1,330 +0,0 @@ - - /* - |-------------------------------------------------------------------------- - | Navigation Menu Configuration - |-------------------------------------------------------------------------- - | - | If you are looking to customize the main navigation menu, this is the place! - | - | All these settings uses Route Keys to identify the page you want to configure. - | A route key is simply the URL path to the page, without the file extension. - | So `_site/posts/hello-world.html` has the route key 'posts/hello-world'. - | - */ - - // OLD - - 'navigation' => [ - // This configuration sets the priorities used to determine the order of the menu. - // The default values have been added below for reference and easy editing. - // The array key is the page's route key, the value is the priority. - // Lower values show up first in the menu. The default is 999. - 'order' => [ - 'index' => 0, - 'posts' => 10, - 'docs/index' => 100, - ], - - // In case you want to customize the labels for the menu items, you can do so here. - // Simply add the route key as the array key, and the label as the value. - 'labels' => [ - 'index' => 'Home', - 'docs/index' => 'Docs', - ], - - // These are the route keys of pages that should not show up in the navigation menu. - 'exclude' => [ - '404', - ], - - // Any extra links you want to add to the navigation menu can be added here. - // To get started quickly, you can uncomment the defaults here. - // See the documentation link above for more information. - 'custom' => [ - // NavigationItem::create('https://github.com/hydephp/hyde', 'GitHub', 200), - ], - - // How should pages in subdirectories be displayed in the menu? - // You can choose between 'dropdown', 'flat', and 'hidden'. - 'subdirectories' => 'hidden', - ], - - - // NEW (creates an array exactly like the one above, but with a more fluent API that supports better autocomplete) - - 'navigation' => Navigation::configure() - ->setPagePriorities([ - 'index' => 0, - 'posts' => 10, - 'docs/index' => 100, - ]) - ->setPageLabels([ - 'index' => 'Home', - 'docs/index' => 'Docs', - ]) - ->excludePages([ - '404', - ]) - ->addNavigationItems([ - // Navigation::item('https://github.com/hydephp/hyde', 'GitHub', 200), - ]) - ->setSubdirectoryDisplayMode('hidden'), - - // All of these options work in the yaml config (this is just an example, please use the same example data as above in the docs) - hyde: - navigation: - custom: - - destination: 'https://example.com' - label: 'Example' - priority: 100 - attributes: - class: 'example' - - destination: 'about' - label: 'About Us' - priority: 200 - attributes: - class: 'about' - id: 'about' - - destination: 'contact' - label: 'Contact' - priority: 300 - attributes: - target: '_blank' - rel: 'noopener noreferrer' - foo: 'bar' - - -// relevant code snippets - -|string $destination Route key, or an external URI. - * @param string|null $label If not provided, Hyde will try to get it from the route's connected page, or from the URL. - * @param int|null $priority If not provided, Hyde will try to get it from the route or the default priority of 500. - * @param array $attributes Additional attributes for the navigation item. - * @return array{destination: string, label: ?string, priority: ?int, attributes: array} - */ - public static function item(string $destination, ?string $label = null, ?int $priority = null, array $attributes = []): array - { - return compact('destination', 'label', 'priority', 'attributes'); - } - - /** - * Configuration helper method to define the navigation menu configuration with better IDE support. - * - * The builder is an array object that will be used by the framework to set the navigation menu configuration. - * - * @experimental This method is experimental and may change or be removed before the final release. - */ - public static function configure(): NavigationMenuConfigurationBuilder - { - return new NavigationMenuConfigurationBuilder(); - } -} - -|array $order - * @return $this - */ - public function setPagePriorities(array $order): static - { - $this['order'] = $order; - - return $this; - } - - /** - * Set the labels for the navigation items. - * - * Each key should be a route key, and the value should be the label to display. - * - * @param array $labels - * @return $this - */ - public function setPageLabels(array $labels): static - { - $this['labels'] = $labels; - - return $this; - } - - /** - * Exclude certain items from the navigation. - * - * Each item should be a route key for the page to exclude. - * - * @param array $exclude - * @return $this - */ - public function excludePages(array $exclude): static - { - $this['exclude'] = $exclude; - - return $this; - } - - /** - * Add custom items to the navigation. - * - * @example `[Navigation::item('https://github.com/hydephp/hyde', 'GitHub', 200, ['target' => '_blank'])]` - * - * @param array}> $custom - * @return $this - */ - public function addNavigationItems(array $custom): static - { - $this['custom'] = $custom; - - return $this; - } - - /** - * Set the display mode for pages in subdirectories. - * - * You can choose between 'dropdown', 'flat', and 'hidden'. The default is 'hidden'. - * - * @param 'dropdown'|'flat'|'hidden' $displayMode - * @return $this - */ - public function setSubdirectoryDisplayMode(string $displayMode): static - { - self::assertType(['dropdown', 'flat', 'hidden'], $displayMode); - - $this['subdirectory_display'] = $displayMode; - - return $this; - } - - /** - * Hide pages in subdirectories from the navigation. - * - * @experimental This method is experimental and may change or be removed before the final release. - * - * @return $this - */ - public function hideSubdirectoriesFromNavigation(): static - { - return $this->setSubdirectoryDisplayMode('hidden'); - } - - /** - * Get the instance as an array. - * - * @return array{order: array, labels: array, exclude: array, custom: array}>, subdirectory_display: string} - */ - public function toArray(): array - { - return $this->getArrayCopy(); - } - - /** @experimental May be moved to a separate helper class in the future. */ - protected static function assertType(array $types, string $value): void - { - if (! in_array($value, $types)) { - throw new TypeError('Value must be one of: '.implode(', ', $types)); - } - } -} - - -// The docs config has not been updated to use the builder api - - /* - |-------------------------------------------------------------------------- - | Sidebar Settings - |-------------------------------------------------------------------------- - | - | The Hyde Documentation Module comes with a fancy Sidebar that is - | automatically populated with links to your documentation pages. - | Here, you can configure its behavior, content, look and feel. - | - */ - - 'sidebar' => [ - // The title in the sidebar header - 'header' => env('SITE_NAME', 'HydePHP').' Docs', - - // When using a grouped sidebar, should the groups be collapsible? - 'collapsible' => true, - - // 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, - ], - - ], \ No newline at end of file diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 36482372801..1f037908a70 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -37,156 +37,331 @@ Here's an overview of what you can customize in your navigation menus: - Item visibility: Choose to hide or show pages in the menu - Item grouping: Group pages together in dropdowns or sidebar categories -## Configuration Methods +### Customization Methods Hyde provides multiple ways to customize navigation menus to suit your needs: 1. Front matter data in Markdown and Blade page files, applicable to all menu types -2. Configuration in the `hyde.php` or `hyde.yml` config file for main navigation items -3. Configuration in the `docs.php` config file for documentation sidebar items +2. Configuration in the `hyde` config file for main navigation items +3. Configuration in the `docs` config file for documentation sidebar items -The new builder pattern in the configuration allows for a more fluent and IDE-friendly way to customize navigation. However, the old array-based method still works, as the navigation builder is an `ArrayObject` and can be used as an array. +Keep in mind that front matter data overrides dynamically inferred or config-defined priorities. While useful for quick one-off changes on small sites, it can make reordering items later on more challenging as you can't see the entire structure at once. -### Using the Navigation Builder +Additionally, general options for the entire navigation menus are also available in the `hyde` and `docs` config files. -To use the new builder pattern, you can configure your navigation in the `hyde.php` file like this: +## Front Matter Configuration -```php -use Hyde\Facades\Navigation; +Front matter options allow per-page customization of navigation menus. Here's a quick reference of available options: + +```yaml +navigation: + label: string # The displayed text in the navigation item link + priority: int # The page's priority for ordering (lower means higher up/first) + hidden: bool # Whether the page should be hidden from the navigation menu + group: string # Set main menu dropdown or sidebar group key +``` -return [ - // ... - - 'navigation' => Navigation::configure() - ->setPagePriorities([ - 'index' => 0, - 'posts' => 10, - 'docs/index' => 100, - ]) - ->setPageLabels([ - 'index' => 'Home', - 'docs/index' => 'Docs', - ]) - ->excludePages([ - '404', - ]) - ->addNavigationItems([ - Navigation::item('https://github.com/hydephp/hyde', 'GitHub', 200), - ]) - ->setSubdirectoryDisplayMode('hidden'), -]; -``` - -### Using YAML Configuration - -You can also set the navigation configuration in the `hyde.yml` file. The structure remains the same as the array-based method: +You only need to specify the keys you want to customize. + +### `label` + +Customizes the text appearing in the navigation menu link for the page. If not set anywhere else, Hyde will search for a title in the page content or generate one from the filename. ```yaml -hyde: - navigation: - order: - index: 0 - posts: 10 - docs/index: 100 - labels: - index: Home - docs/index: Docs - exclude: - - 404 - custom: - - destination: 'https://github.com/hydephp/hyde' - label: 'GitHub' - priority: 200 - subdirectory_display: hidden -``` - -## Customization Options +navigation: + label: "My Custom Label" +``` -Here's an overview of what you can customize in your navigation menus: +### `priority` -- Item labels: The text displayed in menu links -- Item priorities: Control the order of link appearance -- Item visibility: Choose to hide or show pages in the menu -- Item grouping: Group pages together in dropdowns or sidebar categories +Controls the order in which the page appears in the navigation menu. + +```yaml +navigation: + priority: 10 +``` + +### `hidden` + +Determines if the page appears in the navigation menu. + +```yaml +navigation: + hidden: true +``` + +**Tip:** You can also use `visible: false` to achieve the same effect. + +### `group` + +For the primary navigation menu, this groups pages together in dropdowns. For the sidebar, it groups pages under a common heading. + +```yaml +navigation: + group: "My Group" +``` + +**Note:** Sidebar group keys are normalized, so `My Group` and `my-group` are equivalent. + +## Config File Configuration + +Let's explore how to customize navigation menus using configuration files: + +- For the main navigation menu, use `navigation` setting in the `hyde.php` config file. +- For the sidebar, use `sidebar` setting in the `docs.php` config file. + +When customizing the main navigation menu, use the [route key](core-concepts#route-keys) of the page. For the sidebar, you can use either the route key or the [page identifier](core-concepts#page-identifiers). + +### Changing Priorities + +The `navigation.order` and `sidebar.order` settings allow you to customize the order of pages in the navigation menus. + +#### Basic Priority Syntax + +A nice and simple way to define the order of pages, is to add their route keys as a simple list array. We'll then match that array order. + +It may be useful to know that we internally will assign a priority calculated according to its position in the list, plus an offset of `500`. The offset is added to make it easier to place pages earlier in the list using front matter or with explicit priority settings. + +```php +// filepath: config/hyde.php +'navigation' => [ + 'order' => [ + 'home', // Priority: 500 + 'about', // Priority: 501 + 'contact', // Priority: 502 + ] +] +``` + +```php +// filepath: config/docs.php +'sidebar' => [ + 'order' => [ + 'readme', // Priority: 500 + 'installation', // Priority: 501 + 'getting-started', // Priority: 502 + ] +] +``` + +#### Explicit Priority Syntax + +You can also specify explicit priorities by adding a value to the array keys. We'll then use these exact values as the priorities. -### Setting Page Priorities +```php +// filepath: config/hyde.php +'navigation' => [ + 'order' => [ + 'home' => 10, + 'about' => 15, + 'contact' => 20, + ] +] +``` -Use the `setPagePriorities` method to define the order of pages in the navigation menu: +```php +// filepath: config/docs.php +'sidebar' => [ + 'order' => [ + 'readme' => 10, + 'installation' => 15, + 'getting-started' => 20, + ] +] +``` + +You could also combine these methods if desired: ```php -->setPagePriorities([ - 'index' => 0, - 'posts' => 10, - 'docs/index' => 100, -]) +// filepath: Applicable to both +[ + 'readme' => 10, // Priority: 10 + 'installation', // Priority: 500 + 'getting-started', // Priority: 501 +] ``` ### Changing Menu Item Labels -Override navigation link labels using the `setPageLabels` method: +Hyde makes a few attempts to find a suitable label for the navigation menu items to automatically create helpful titles. + +If you're not happy with these, it's easy to override navigation link labels by mapping the route key to the desired title in the Hyde config: ```php -->setPageLabels([ - 'index' => 'Home', - 'docs/index' => 'Documentation', -]) +// filepath: config/hyde.php +'navigation' => [ + 'labels' => [ + 'index' => 'Start', + 'docs/index' => 'Documentation', + ] +] ``` -### Excluding Items +**Note:** This feature is not yet supported for the sidebar. + +### Excluding Items (Blacklist) -Prevent links from being added to the main navigation menu using the `excludePages` method: +When you have a lot of pages, it may be useful to prevent links from being added to the main navigation menu. + +To exclude items from being added, simply add the page's route key to the navigation blacklist in the Hyde config: ```php -->excludePages([ - '404', -]) +// filepath: config/hyde.php +'navigation' => [ + 'exclude' => [ + '404' + ] +] ``` ### Adding Custom Navigation Menu Links -Add custom navigation menu links using the `addNavigationItems` method: +You can easily add custom navigation menu links in the Hyde config: ```php -->addNavigationItems([ - Navigation::item('https://github.com/hydephp/hyde', 'GitHub', 200), -]) +// filepath: config/hyde.php +use Hyde\Facades\Navigation; + +'navigation' => [ + 'custom' => [ + Navigation::item( + destination: 'https://github.com/hydephp/hyde', // Required + label: 'GitHub', // Optional, defaults to the destination value + priority: 200 // Optional, defaults to 500 + ), + ] +] ``` +**Tip:** While named arguments are used in the example for clarity, they are not required. + + ### Configure Subdirectory Display -Set how subdirectories should be displayed in the menu using the `setSubdirectoryDisplayMode` method: +You can configure how subdirectories should be displayed in the menu: ```php -->setSubdirectoryDisplayMode('dropdown') +// filepath: config/hyde.php +'navigation' => [ + 'subdirectory_display' => 'dropdown' +] ``` -Supported options are 'dropdown', 'hidden', and 'flat'. +**Supported Options:** +- `dropdown`: Pages in subdirectories are displayed in a dropdown menu +- `hidden`: Pages in subdirectories are not displayed at all the menus +- `flat`: Pages in subdirectories are displayed as individual items -## Front Matter Configuration +### Automatic Menu Groups -Front matter options allow per-page customization of navigation menus. These options remain unchanged: +A handy feature HydePHP has is that it can automatically place pages in dropdowns based on subdirectory structures. -```yaml -navigation: - label: string # The displayed text in the navigation item link - priority: int # The page's priority for ordering (lower means higher up/first) - hidden: bool # Whether the page should be hidden from the navigation menu - group: string # Set main menu dropdown or sidebar group key +#### Automatic Navigation Menu Dropdowns + +Enable this feature in the `hyde.php` config file by setting the `subdirectory_display` key to `dropdown`. + +```php +// filepath: config/hyde.php +'navigation' => [ + 'subdirectory_display' => 'dropdown', +], ``` +Now if you create a page called `_pages/about/contact.md` it will automatically be placed in a dropdown called "About". + +#### Automatic Documentation Sidebar Grouping + +This feature is always enabled for documentation pages. Simply place your pages in subdirectories to have them grouped in the sidebar. + +For example: `_docs/getting-started/installation.md` will be placed in a group called "Getting Started". + +>info Tip: When using subdirectory-based dropdowns, you can set their priority using the directory name as the array key. + +#### Dropdown Menu Notes + +- Dropdowns take priority over standard items. If you have a dropdown with the key `about` and a page with the key `about`, the dropdown will be created, and the page won't be in the menu. +- Example: With this file structure: `_pages/foo.md`, `_pages/foo/bar.md`, `_pages/foo/baz.md`, the link to `foo` will be lost, so please keep this in mind when using this feature. + ## Numerical Prefix Navigation Ordering -The numerical prefix navigation ordering feature remains unchanged. You can still use numerical prefixes in filenames to control the order of navigation items. +HydePHP v2 introduces navigation item ordering based on numerical prefixes in filenames. This feature works for both the primary navigation menu and the documentation sidebar. -To disable this feature, you can use the following configuration: +This has the great benefit of matching the navigation menu layout with the file structure view, and works especially great with subdirectory-based navigation grouping. + +```shell +_pages/ + 01-home.md # Priority: 1 (saved to _site/index.html) + 02-about.md # Priority: 2 (saved to _site/about.html) + 03-contact.md # Priority: 3 (saved to _site/contact.html) +``` + +As you can seem Hyde parses the number from the filename and uses it as the priority for the page in navigation menus, while stripping the prefix from the route key. + +### Important Notes + +1. The numerical prefix remains part of the page identifier but is stripped from the route key. + For example: `_pages/01-home.md` has route key `home` and page identifier `01-home`. +2. You can delimit the numerical prefix with either a dash or an underscore. + For example: Both `_pages/01-home.md` and `_pages/01_home.md` are valid. +3. Leading zeros are optional. `_pages/1-home.md` is equally valid. + +### Using Numerical Prefix Ordering in Subdirectories + +This feature integrates well with automatic subdirectory-based navigation grouping. Here are two useful tips: + +1. You can use numerical prefixes in subdirectories to control the dropdown/sidebar order. +2. The numbering within a subdirectory works independently of its siblings, so you can start from one in each subdirectory. + +Here is an example structure of how could organize a documentation site: + +```shell +_docs/ + 01-getting-started/ + 01-installation.md + 02-requirements.md + 03-configuration.md + 02-usage/ + 01-quick-start.md + 02-advanced-usage.md + 03-features/ + 01-feature-1.md + 02-feature-2.md +``` + +### Customization + +If you're not interested in using numerical prefix ordering, you can disable it in the Hyde config file. Hyde will then no longer extract the priority and will no longer strip the prefix from the route key. ```php -return [ - // ... - 'numerical_page_ordering' => false, -]; +// filepath: config/hyde.php +'numerical_page_ordering' => false, ``` -## Conclusion +## Digging Deeper into the Internals + +While not essential, understanding the internal workings of the navigation system can be as beneficial as it's interesting. Here's a quick high-level overview of the [Navigation API](navigation-api). + +### Navigation Menu Classes + +The main navigation menu uses the `MainNavigationMenu` class, while the documentation sidebar uses the `DocumentationSidebar` class. Both extend the base `NavigationMenu` class: + +```php +use Hyde\Framework\Features\Navigation\MainNavigationMenu; +use Hyde\Framework\Features\Navigation\DocumentationSidebar; +use Hyde\Framework\Features\Navigation\NavigationMenu; +``` + +The base `NavigationMenu` class contains the main logic for menu generation, while child implementations contain extra logic for specific use cases. + +All navigation menus store items in their `$items` collection, containing instances of the `NavigationItem` class. Dropdowns are represented by `NavigationGroup` instances, which extend the `NavigationMenu` class and contain additional `NavigationItem` instances: + +```php +use Hyde\Framework\Features\Navigation\NavigationItem; +use Hyde\Framework\Features\Navigation\NavigationGroup; +``` + +## The Navigation API + +For advanced users and package developers, Hyde offers a Navigation API for programmatic interaction with site navigation. This API consists of a set of PHP classes allowing fluent interaction with navigation menus. -The new builder pattern provides a more fluent and IDE-friendly way to configure navigation in HydePHP. However, the old array-based method and YAML configuration are still supported, giving you flexibility in how you choose to customize your site's navigation. \ No newline at end of file +For more detailed information about the API, refer to the [Navigation API](navigation-api) documentation. From 3f9f9f8cfff988e7a8980a5447efce7e9127cd36 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 12 Jul 2024 13:06:37 +0200 Subject: [PATCH 185/232] Remove hard line breaks from sections --- docs/creating-content/documentation-pages.md | 90 +++++++------------- 1 file changed, 29 insertions(+), 61 deletions(-) diff --git a/docs/creating-content/documentation-pages.md b/docs/creating-content/documentation-pages.md index aed6f445be6..689e8bebdcf 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -8,23 +8,17 @@ navigation: ## Introduction to Hyde Documentation Pages -Welcome to the Hyde Documentation Pages, where creating professional-looking documentation sites has never been easier. -Using the Hyde Documentation module, all you need to do is place standard Markdown files in the _docs/ directory, and Hyde takes care of the rest. +Welcome to the Hyde Documentation Pages, where creating professional-looking documentation sites has never been easier. Using the Hyde Documentation module, all you need to do is place standard Markdown files in the _docs/ directory, and Hyde takes care of the rest. -Hyde compiles your Markdown content into beautiful static HTML pages using a TailwindCSS frontend, complete with a -responsive sidebar that is automatically generated based on your Markdown files. You can even customize the order, -labels, and even groups, of the sidebar items to suit your needs. +Hyde compiles your Markdown content into beautiful static HTML pages using a TailwindCSS frontend, complete with a responsive sidebar that is automatically generated based on your Markdown files. You can even customize the order, labels, and even groups, of the sidebar items to suit your needs. -Additionally, if you have a `_docs/index.md` file, the sidebar header will link to it, and an automatically generated -"Docs" link will be added to your site's main navigation menu, pointing to your documentation page. +Additionally, if you have a `_docs/index.md` file, the sidebar header will link to it, and an automatically generated "Docs" link will be added to your site's main navigation menu, pointing to your documentation page. -If you have a Torchlight API token in your .env file, Hyde will even enable syntax highlighting automatically, -saving you time and effort. For more information about this feature, see the [extensions page](extensions#torchlight). +If you have a Torchlight API token in your .env file, Hyde will even enable syntax highlighting automatically, saving you time and effort. For more information about this feature, see the [extensions page](extensions#torchlight). ### Best Practices and Hyde Expectations -Since Hyde does a lot of things automatically, there are some things you may need -to keep in mind when creating blog posts so that you don't get unexpected results. +Since Hyde does a lot of things automatically, there are some things you may need to keep in mind when creating blog posts so that you don't get unexpected results. #### Filenames @@ -78,13 +72,11 @@ navigation: ## Dynamic Content Generation -Hyde makes documentation pages easy to create by automatically generating dynamic content such as the sidebar and page title. -If you are not happy with the results you can customize them in the config or with front matter. +Hyde makes documentation pages easy to create by automatically generating dynamic content such as the sidebar and page title. If you are not happy with the results you can customize them in the config or with front matter. ### Front Matter reference -Before we look at how to override things, here is an overview of the relevant content Hyde generates, -and where the data is from as well as where it can be overridden. +Before we look at how to override things, here is an overview of the relevant content Hyde generates, and where the data is from as well as where it can be overridden. | Property | Description | Dynamic Data Source | Override in | |---------------------------------|--------------------------------------------------------|-------------------------------------|----------------------| @@ -97,29 +89,26 @@ and where the data is from as well as where it can be overridden. ## Sidebar -The sidebar is automatically generated from the files in the `_docs` directory. You will probably want to change the order -of these items. You can do this in two ways, either in the config or with front matter using the navigation array settings. +The sidebar is automatically generated from the files in the `_docs` directory. You will probably want to change the order of these items. You can do this in two ways, either in the config or with front matter using the navigation array settings. -Since this feature shares a lot of similarities and implementation details with the navigation menu, -I recommend you read the [navigation menu documentation](navigation) page as well to learn more about the fundamentals and terminology. +Since this feature shares a lot of similarities and implementation details with the navigation menu, I recommend you read the [navigation menu documentation](navigation) page as well to learn more about the fundamentals and terminology. ### Sidebar ordering -The sidebar is sorted/ordered by the `priority` property. The higher the priority the further down in the sidebar it will be. -The default priority is 999. You can override the priority using the following front matter: +The sidebar is sorted/ordered by the `priority` property. The higher the priority the further down in the sidebar it will be. The default priority is 999. You can override the priority using the following front matter: ```yaml navigation: priority: 5 ``` -You can also change the order in the Docs configuration file. -See [the chapter in the customization page](customization#navigation-menu--sidebar) for more details.
+You can also change the order in the Docs configuration file. See [the chapter in the customization page](customization#navigation-menu--sidebar) for more details.
_I personally think the config route is easier as it gives an instant overview, however the first way is nice as well._ ### Sidebar labels The sidebar items are labelled with the `label` property. The default label is the filename of the file. + You can change it with the following front matter: ```yaml @@ -129,12 +118,9 @@ navigation: ### Sidebar grouping -Sidebar grouping allows you to group items in the sidebar into categories. This is useful for creating a sidebar with a lot of items. -The Hyde docs for instance use this. +Sidebar grouping allows you to group items in the sidebar into categories. This is useful for creating a sidebar with a lot of items. The Hyde docs for instance use this. -The feature is enabled automatically when one or more of your documentation pages have the `navigation.group` property set -in the front matter, or when subdirectories are used. This will then switch to a slightly more compact sidebar layout with pages sorted into categories. -Any pages without the group front matter will get put in the "Other" group. +The feature is enabled automatically when one or more of your documentation pages have the `navigation.group` property set in the front matter, or when subdirectories are used. This will then switch to a slightly more compact sidebar layout with pages sorted into categories. Any pages without the group front matter will get put in the "Other" group. ### Sidebar footer customization @@ -185,13 +171,12 @@ This can be useful to create redirects or other items that should not be shown i ## Customization -Please see the [customization page](customization) for in-depth information on how to customize Hyde, -including the documentation pages. Here is a high level overview for quick reference though. +Please see the [customization page](customization) for in-depth information on how to customize Hyde, including the documentation pages. Here is a high level overview for quick reference though. ### Output directory -If you want to store the compiled documentation pages in a different directory than the default 'docs' directory, -for example to specify a version like the Hyde docs does, you can specify the output directory in the Hyde configuration file. +If you want to store the compiled documentation pages in a different directory than the default 'docs' directory, for example to specify a version like the Hyde docs does, you can specify the output directory in the Hyde configuration file. + The path is relative to the site output, typically `_site`. ```php @@ -210,8 +195,7 @@ By default, a link to the documentation page is added to the navigation menu whe ### Sidebar header name -By default, the site title shown in the sidebar header is generated from the configured site name suffixed with "docs". -You can change this in the Docs configuration file. Tip: The header will link to the docs/index page, if it exists. +By default, the site title shown in the sidebar header is generated from the configured site name suffixed with "docs". You can change this in the Docs configuration file. Tip: The header will link to the docs/index page, if it exists. ```php 'title' => 'API Documentation', @@ -219,8 +203,7 @@ You can change this in the Docs configuration file. Tip: The header will link to ### Sidebar page order -To quickly arrange the order of items in the sidebar, you can reorder the page identifiers in the list and the links will be sorted in that order. -Link items without an entry here will fall back to the default priority of 999, putting them last. +To quickly arrange the order of items in the sidebar, you can reorder the page identifiers in the list and the links will be sorted in that order. Link items without an entry here will fall back to the default priority of 999, putting them last. ```php 'sidebar' => [ @@ -236,9 +219,7 @@ See [the chapter in the customization page](customization#navigation-menu--sideb ### Automatic sidebar group labels -When using the automatic sidebar grouping feature (based on subdirectories), the titles of the groups are generated from the directory names. -If these are not to your liking, for example if you need to use special characters, you can override them in the Docs configuration file. -The array key is the directory name, and the value is the label. +When using the automatic sidebar grouping feature (based on subdirectories), the titles of the groups are generated from the directory names. If these are not to your liking, for example if you need to use special characters, you can override them in the Docs configuration file. The array key is the directory name, and the value is the label. Please note that this option is not added to the config file by default, as it's not a super common use case. No worries though, just add the following yourself! @@ -254,8 +235,7 @@ Please note that this option is not added to the config file by default, as it's Hyde automatically generates a table of contents for the page and adds it to the sidebar. -In the `config/docs.php` file you can configure the behaviour, content, and the look and feel of the sidebar table of contents. -You can also disable the feature completely. +In the `config/docs.php` file you can configure the behaviour, content, and the look and feel of the sidebar table of contents. You can also disable the feature completely. ```php 'sidebar' => [ @@ -269,9 +249,7 @@ You can also disable the feature completely. ### Using flattened output paths -If this setting is set to true, Hyde will output all documentation pages into the same configured documentation output directory. -This means that you can use the automatic directory-based grouping feature, but still have a "flat" output structure. -Note that this means that you can't have two documentation pages with the same filename or navigation menu label as they will overwrite each other. +If this setting is set to true, Hyde will output all documentation pages into the same configured documentation output directory. This means that you can use the automatic directory-based grouping feature, but still have a "flat" output structure. Note that this means that you can't have two documentation pages with the same filename or navigation menu label as they will overwrite each other. If you set this to false, Hyde will match the directory structure of the source files (just like all other pages). @@ -285,8 +263,7 @@ If you set this to false, Hyde will match the directory structure of the source ### Introduction -The HydeSearch plugin adds a search feature to documentation pages. It consists of two parts, a search index generator -that runs during the build command, and a frontend JavaScript plugin that adds the actual search widget. +The HydeSearch plugin adds a search feature to documentation pages. It consists of two parts, a search index generator that runs during the build command, and a frontend JavaScript plugin that adds the actual search widget. >info Tip: The HydeSearch plugin is what powers the search feature on this site! Why not [try it out](search)? @@ -305,16 +282,13 @@ The search works by generating a JSON search index which the JavaScript plugin l Two ways to access the search are added, one is a full page search screen that will be saved to `docs/search.html`. -The second method is a button added to the documentation pages, similar to how Algolia DocSearch works. -Opening it will open a modal with an integrated search screen. You can also open the dialogue using the keyboard shortcut `/`. +The second method is a button added to the documentation pages, similar to how Algolia DocSearch works. Opening it will open a modal with an integrated search screen. You can also open the dialogue using the keyboard shortcut `/`. >info The full page can be disabled by setting `create_search_page` to `false` in the `docs` config. ### Hiding pages from indexing -If you have a large page on your documentation site, like a changelog, you may want to hide it from the search index. -You can do this by adding the page identifier to the `exclude_from_search` array in the `docs` config, similar to how -navigation menu items are hidden. The page will still be accessible as normal but will be added to the search index JSON file. +If you have a large page on your documentation site, like a changelog, you may want to hide it from the search index. You can do this by adding the page identifier to the `exclude_from_search` array in the `docs` config, similar to how navigation menu items are hidden. The page will still be accessible as normal but will be added to the search index JSON file. ```php // filepath: config/docs.php @@ -332,13 +306,9 @@ The Realtime Compiler that powers the `php hyde serve` command will automaticall ### Introduction -Hyde can automatically add links to documentation pages that take the user -to a GitHub page (or similar) to edit the page. This makes it great for open-source projects -looking to allow others to contribute to the documentation in a quick and easy manner. +Hyde can automatically add links to documentation pages that take the user to a GitHub page (or similar) to edit the page. This makes it great for open-source projects looking to allow others to contribute to the documentation in a quick and easy manner. -The feature is automatically enabled when you specify a base URL in the Docs configuration file. -Hyde expects this to be a GitHub path, but it will probably work with other methods as well, -if not, please send a PR and/or create an issue on the [GitHub repository](https://github.com/hydephp/framework)! +The feature is automatically enabled when you specify a base URL in the Docs configuration file. Hyde expects this to be a GitHub path, but it will probably work with other methods as well, if not, please send a PR and/or create an issue on the [GitHub repository](https://github.com/hydephp/framework)! >info Tip: This documentation site uses this feature, scroll down to the bottom of this page and try it out! @@ -363,8 +333,7 @@ Changing the label is easy, just change the following config setting: #### Changing the position -By default, the button will be shown in both the documentation page footer. -You can change this by setting the following config setting to `'header'`, `'footer'`, or `'both'` +By default, the button will be shown in both the documentation page footer. You can change this by setting the following config setting to `'header'`, `'footer'`, or `'both'` ```php // Filepath: config/docs.php @@ -373,8 +342,7 @@ You can change this by setting the following config setting to `'header'`, `'foo #### Adding a button icon -This is not included out of the box, but is easy to add with some CSS! -Just target the `.edit-page-link` class. +This is not included out of the box, but is easy to add with some CSS! Just target the `.edit-page-link` class. ```css // filepath e.g. app.css From 7a85697a90b4c4fc066a5ba0ea4975fc3694234c Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 12 Jul 2024 13:07:26 +0200 Subject: [PATCH 186/232] Remove extra newlines --- docs/creating-content/documentation-pages.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/docs/creating-content/documentation-pages.md b/docs/creating-content/documentation-pages.md index 689e8bebdcf..68bf8361e8a 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -34,7 +34,6 @@ Since Hyde does a lot of things automatically, there are some things you may nee Like most of HydePHP, the Hyde Documentation module is highly customizable. Much of the frontend is composed using Blade templates and components, which you can customize to your heart's content. Since there are so many components, it's hard to list them all here in the documentation, so I encourage you to check out the [source code](https://github.com/hydephp/framework/tree/master/resources/views/components/docs) to see how it's all put together and find the customizations you are looking for. - ## Creating Documentation Pages You can create a Documentation page by adding a file to the `_docs` directory where the filename ends in `.md`. @@ -69,7 +68,6 @@ navigation: --- ``` - ## Dynamic Content Generation Hyde makes documentation pages easy to create by automatically generating dynamic content such as the sidebar and page title. If you are not happy with the results you can customize them in the config or with front matter. @@ -168,7 +166,6 @@ This can be useful to create redirects or other items that should not be shown i >info The index page is by default not shown as a sidebar item, but instead is linked in the sidebar header.
- ## Customization Please see the [customization page](customization) for in-depth information on how to customize Hyde, including the documentation pages. Here is a high level overview for quick reference though. @@ -258,7 +255,6 @@ If you set this to false, Hyde will match the directory structure of the source 'flattened_output_paths' => true, ``` - ## Search Feature ### Introduction @@ -301,7 +297,6 @@ If you have a large page on your documentation site, like a changelog, you may w The Realtime Compiler that powers the `php hyde serve` command will automatically generate a fresh search index each time the browser requests it. - ## Automatic "Edit Page" Button ### Introduction From 467b99191848153bf7ec4af1c1024ca7d12ec72f Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 12 Jul 2024 13:08:37 +0200 Subject: [PATCH 187/232] Cleanup line --- docs/creating-content/documentation-pages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/creating-content/documentation-pages.md b/docs/creating-content/documentation-pages.md index 68bf8361e8a..ce0daea81e7 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -10,7 +10,7 @@ navigation: Welcome to the Hyde Documentation Pages, where creating professional-looking documentation sites has never been easier. Using the Hyde Documentation module, all you need to do is place standard Markdown files in the _docs/ directory, and Hyde takes care of the rest. -Hyde compiles your Markdown content into beautiful static HTML pages using a TailwindCSS frontend, complete with a responsive sidebar that is automatically generated based on your Markdown files. You can even customize the order, labels, and even groups, of the sidebar items to suit your needs. +Hyde compiles your Markdown content into beautiful static HTML pages using a TailwindCSS frontend, complete with a responsive sidebar that is automatically generated based on your Markdown files. You can even customize the order, labels, and groups of the sidebar items to suit your needs. Additionally, if you have a `_docs/index.md` file, the sidebar header will link to it, and an automatically generated "Docs" link will be added to your site's main navigation menu, pointing to your documentation page. From ac511dbb872f148b676a86c2f6d5eb521c1bab2d Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 12 Jul 2024 13:09:55 +0200 Subject: [PATCH 188/232] Shorten line --- docs/creating-content/documentation-pages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/creating-content/documentation-pages.md b/docs/creating-content/documentation-pages.md index ce0daea81e7..65f708c2c8e 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -309,7 +309,7 @@ The feature is automatically enabled when you specify a base URL in the Docs con ### Configuration -As an example configuration, let's take a practical example of how HydePHP.com uses this feature. +Here's an example configuration from the official HydePHP.com documentation: ```php // Filepath: config/docs.php From 51dc2ed0d77780924a4aa3b1bee81b76dbe22768 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 12 Jul 2024 13:06:37 +0200 Subject: [PATCH 189/232] Remove hard line breaks from sections --- docs/creating-content/documentation-pages.md | 90 +++++++------------- 1 file changed, 29 insertions(+), 61 deletions(-) diff --git a/docs/creating-content/documentation-pages.md b/docs/creating-content/documentation-pages.md index 309fc0cd7f7..f2e86881ab3 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -8,23 +8,17 @@ navigation: ## Introduction to Hyde Documentation Pages -Welcome to the Hyde Documentation Pages, where creating professional-looking documentation sites has never been easier. -Using the Hyde Documentation module, all you need to do is place standard Markdown files in the _docs/ directory, and Hyde takes care of the rest. +Welcome to the Hyde Documentation Pages, where creating professional-looking documentation sites has never been easier. Using the Hyde Documentation module, all you need to do is place standard Markdown files in the _docs/ directory, and Hyde takes care of the rest. -Hyde compiles your Markdown content into beautiful static HTML pages using a TailwindCSS frontend, complete with a -responsive sidebar that is automatically generated based on your Markdown files. You can even customize the order, -labels, and even groups, of the sidebar items to suit your needs. +Hyde compiles your Markdown content into beautiful static HTML pages using a TailwindCSS frontend, complete with a responsive sidebar that is automatically generated based on your Markdown files. You can even customize the order, labels, and even groups, of the sidebar items to suit your needs. -Additionally, if you have a `_docs/index.md` file, the sidebar header will link to it, and an automatically generated -"Docs" link will be added to your site's main navigation menu, pointing to your documentation page. +Additionally, if you have a `_docs/index.md` file, the sidebar header will link to it, and an automatically generated "Docs" link will be added to your site's main navigation menu, pointing to your documentation page. -If you have a Torchlight API token in your .env file, Hyde will even enable syntax highlighting automatically, -saving you time and effort. For more information about this feature, see the [extensions page](extensions#torchlight). +If you have a Torchlight API token in your .env file, Hyde will even enable syntax highlighting automatically, saving you time and effort. For more information about this feature, see the [extensions page](extensions#torchlight). ### Best Practices and Hyde Expectations -Since Hyde does a lot of things automatically, there are some things you may need -to keep in mind when creating blog posts so that you don't get unexpected results. +Since Hyde does a lot of things automatically, there are some things you may need to keep in mind when creating blog posts so that you don't get unexpected results. #### Filenames @@ -77,13 +71,11 @@ navigation: ## Dynamic Content Generation -Hyde makes documentation pages easy to create by automatically generating dynamic content such as the sidebar and page title. -If you are not happy with the results you can customize them in the config or with front matter. +Hyde makes documentation pages easy to create by automatically generating dynamic content such as the sidebar and page title. If you are not happy with the results you can customize them in the config or with front matter. ### Front Matter reference -Before we look at how to override things, here is an overview of the relevant content Hyde generates, -and where the data is from as well as where it can be overridden. +Before we look at how to override things, here is an overview of the relevant content Hyde generates, and where the data is from as well as where it can be overridden. | Property | Description | Dynamic Data Source | Override in | |---------------------------------|--------------------------------------------------------|-------------------------------------|----------------------| @@ -95,29 +87,26 @@ and where the data is from as well as where it can be overridden. ## Sidebar -The sidebar is automatically generated from the files in the `_docs` directory. You will probably want to change the order -of these items. You can do this in two ways, either in the config or with front matter using the navigation array settings. +The sidebar is automatically generated from the files in the `_docs` directory. You will probably want to change the order of these items. You can do this in two ways, either in the config or with front matter using the navigation array settings. -Since this feature shares a lot of similarities and implementation details with the navigation menu, -I recommend you read the [navigation menu documentation](navigation) page as well to learn more about the fundamentals and terminology. +Since this feature shares a lot of similarities and implementation details with the navigation menu, I recommend you read the [navigation menu documentation](navigation) page as well to learn more about the fundamentals and terminology. ### Sidebar ordering -The sidebar is sorted/ordered by the `priority` property. The higher the priority the further down in the sidebar it will be. -The default priority is 999. You can override the priority using the following front matter: +The sidebar is sorted/ordered by the `priority` property. The higher the priority the further down in the sidebar it will be. The default priority is 999. You can override the priority using the following front matter: ```yaml navigation: priority: 5 ``` -You can also change the order in the Docs configuration file. -See [the chapter in the customization page](customization#navigation-menu--sidebar) for more details.
+You can also change the order in the Docs configuration file. See [the chapter in the customization page](customization#navigation-menu--sidebar) for more details.
_I personally think the config route is easier as it gives an instant overview, however the first way is nice as well._ ### Sidebar labels The sidebar items are labelled with the `label` property. The default label is the filename of the file. + You can change it with the following front matter: ```yaml @@ -127,12 +116,9 @@ navigation: ### Sidebar grouping -Sidebar grouping allows you to group items in the sidebar into categories. This is useful for creating a sidebar with a lot of items. -The Hyde docs for instance use this. +Sidebar grouping allows you to group items in the sidebar into categories. This is useful for creating a sidebar with a lot of items. The Hyde docs for instance use this. -The feature is enabled automatically when one or more of your documentation pages have the `navigation.group` property set -in the front matter, or when subdirectories are used. This will then switch to a slightly more compact sidebar layout with pages sorted into categories. -Any pages without the group front matter will get put in the "Other" group. +The feature is enabled automatically when one or more of your documentation pages have the `navigation.group` property set in the front matter, or when subdirectories are used. This will then switch to a slightly more compact sidebar layout with pages sorted into categories. Any pages without the group front matter will get put in the "Other" group. ### Sidebar footer customization @@ -182,13 +168,12 @@ This can be useful to create redirects or other items that should not be shown i ## Customization -Please see the [customization page](customization) for in-depth information on how to customize Hyde, -including the documentation pages. Here is a high level overview for quick reference though. +Please see the [customization page](customization) for in-depth information on how to customize Hyde, including the documentation pages. Here is a high level overview for quick reference though. ### Output directory -If you want to store the compiled documentation pages in a different directory than the default 'docs' directory, -for example to specify a version like the Hyde docs does, you can specify the output directory in the Hyde configuration file. +If you want to store the compiled documentation pages in a different directory than the default 'docs' directory, for example to specify a version like the Hyde docs does, you can specify the output directory in the Hyde configuration file. + The path is relative to the site output, typically `_site`. ```php @@ -207,8 +192,7 @@ By default, a link to the documentation page is added to the navigation menu whe ### Sidebar header name -By default, the site title shown in the sidebar header is generated from the configured site name suffixed with "docs". -You can change this in the Docs configuration file. Tip: The header will link to the docs/index page, if it exists. +By default, the site title shown in the sidebar header is generated from the configured site name suffixed with "docs". You can change this in the Docs configuration file. Tip: The header will link to the docs/index page, if it exists. ```php 'title' => 'API Documentation', @@ -216,8 +200,7 @@ You can change this in the Docs configuration file. Tip: The header will link to ### Sidebar page order -To quickly arrange the order of items in the sidebar, you can reorder the page identifiers in the list and the links will be sorted in that order. -Link items without an entry here will fall back to the default priority of 999, putting them last. +To quickly arrange the order of items in the sidebar, you can reorder the page identifiers in the list and the links will be sorted in that order. Link items without an entry here will fall back to the default priority of 999, putting them last. ```php 'sidebar' => [ @@ -233,9 +216,7 @@ See [the chapter in the customization page](customization#navigation-menu--sideb ### Automatic sidebar group labels -When using the automatic sidebar grouping feature (based on subdirectories), the titles of the groups are generated from the directory names. -If these are not to your liking, for example if you need to use special characters, you can override them in the Docs configuration file. -The array key is the directory name, and the value is the label. +When using the automatic sidebar grouping feature (based on subdirectories), the titles of the groups are generated from the directory names. If these are not to your liking, for example if you need to use special characters, you can override them in the Docs configuration file. The array key is the directory name, and the value is the label. Please note that this option is not added to the config file by default, as it's not a super common use case. No worries though, just add the following yourself! @@ -251,8 +232,7 @@ Please note that this option is not added to the config file by default, as it's Hyde automatically generates a table of contents for the page and adds it to the sidebar. -In the `config/docs.php` file you can configure the behaviour, content, and the look and feel of the sidebar table of contents. -You can also disable the feature completely. +In the `config/docs.php` file you can configure the behaviour, content, and the look and feel of the sidebar table of contents. You can also disable the feature completely. ```php 'sidebar' => [ @@ -266,9 +246,7 @@ You can also disable the feature completely. ### Using flattened output paths -If this setting is set to true, Hyde will output all documentation pages into the same configured documentation output directory. -This means that you can use the automatic directory-based grouping feature, but still have a "flat" output structure. -Note that this means that you can't have two documentation pages with the same filename or navigation menu label as they will overwrite each other. +If this setting is set to true, Hyde will output all documentation pages into the same configured documentation output directory. This means that you can use the automatic directory-based grouping feature, but still have a "flat" output structure. Note that this means that you can't have two documentation pages with the same filename or navigation menu label as they will overwrite each other. If you set this to false, Hyde will match the directory structure of the source files (just like all other pages). @@ -281,8 +259,7 @@ If you set this to false, Hyde will match the directory structure of the source ### Introduction -The HydeSearch plugin adds a search feature to documentation pages. It consists of two parts, a search index generator -that runs during the build command, and a frontend JavaScript plugin that adds the actual search widget. +The HydeSearch plugin adds a search feature to documentation pages. It consists of two parts, a search index generator that runs during the build command, and a frontend JavaScript plugin that adds the actual search widget. >info Tip: The HydeSearch plugin is what powers the search feature on this site! Why not [try it out](search)? @@ -301,16 +278,13 @@ The search works by generating a JSON search index which the JavaScript plugin l Two ways to access the search are added, one is a full page search screen that will be saved to `docs/search.html`. -The second method is a button added to the documentation pages, similar to how Algolia DocSearch works. -Opening it will open a modal with an integrated search screen. You can also open the dialogue using the keyboard shortcut `/`. +The second method is a button added to the documentation pages, similar to how Algolia DocSearch works. Opening it will open a modal with an integrated search screen. You can also open the dialogue using the keyboard shortcut `/`. >info The full page can be disabled by setting `create_search_page` to `false` in the `docs` config. ### Hiding pages from indexing -If you have a large page on your documentation site, like a changelog, you may want to hide it from the search index. -You can do this by adding the page identifier to the `exclude_from_search` array in the `docs` config, similar to how -navigation menu items are hidden. The page will still be accessible as normal but will be added to the search index JSON file. +If you have a large page on your documentation site, like a changelog, you may want to hide it from the search index. You can do this by adding the page identifier to the `exclude_from_search` array in the `docs` config, similar to how navigation menu items are hidden. The page will still be accessible as normal but will be added to the search index JSON file. ```php // filepath: config/docs.php @@ -327,13 +301,9 @@ The Realtime Compiler that powers the `php hyde serve` command will automaticall ### Introduction -Hyde can automatically add links to documentation pages that take the user -to a GitHub page (or similar) to edit the page. This makes it great for open-source projects -looking to allow others to contribute to the documentation in a quick and easy manner. +Hyde can automatically add links to documentation pages that take the user to a GitHub page (or similar) to edit the page. This makes it great for open-source projects looking to allow others to contribute to the documentation in a quick and easy manner. -The feature is automatically enabled when you specify a base URL in the Docs configuration file. -Hyde expects this to be a GitHub path, but it will probably work with other methods as well, -if not, please send a PR and/or create an issue on the [GitHub repository](https://github.com/hydephp/framework)! +The feature is automatically enabled when you specify a base URL in the Docs configuration file. Hyde expects this to be a GitHub path, but it will probably work with other methods as well, if not, please send a PR and/or create an issue on the [GitHub repository](https://github.com/hydephp/framework)! >info Tip: This documentation site uses this feature, scroll down to the bottom of this page and try it out! @@ -358,8 +328,7 @@ Changing the label is easy, just change the following config setting: #### Changing the position -By default, the button will be shown in both the documentation page footer. -You can change this by setting the following config setting to `'header'`, `'footer'`, or `'both'` +By default, the button will be shown in both the documentation page footer. You can change this by setting the following config setting to `'header'`, `'footer'`, or `'both'` ```php // Filepath: config/docs.php @@ -368,8 +337,7 @@ You can change this by setting the following config setting to `'header'`, `'foo #### Adding a button icon -This is not included out of the box, but is easy to add with some CSS! -Just target the `.edit-page-link` class. +This is not included out of the box, but is easy to add with some CSS! Just target the `.edit-page-link` class. ```css // filepath e.g. app.css From accc2f7c36a0783424083ae0b877d08bea2d4da6 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 12 Jul 2024 14:31:23 +0200 Subject: [PATCH 190/232] Clarify that lower priority values result in higher placement in the sidebar Matches writing style, and is more intuitive --- docs/creating-content/documentation-pages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/creating-content/documentation-pages.md b/docs/creating-content/documentation-pages.md index ed64817e624..d9c498e01a9 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -93,7 +93,7 @@ Since this feature shares a lot of similarities and implementation details with ### Sidebar ordering -The sidebar is sorted/ordered by the `priority` property. The higher the priority the further down in the sidebar it will be. The default priority is 999. You can override the priority using the following front matter: +The sidebar is sorted/ordered by the `priority` property. The lower the priority value, the higher up in the sidebar it will be. The default priority is 999. You can override the priority using the following front matter: ```yaml navigation: From cc0d2e3ef0eedf94a02e448d665eec1a8dce9f01 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 12 Jul 2024 14:32:57 +0200 Subject: [PATCH 191/232] Clean up section --- docs/creating-content/documentation-pages.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/creating-content/documentation-pages.md b/docs/creating-content/documentation-pages.md index d9c498e01a9..c3aa6d2f3d3 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -100,8 +100,7 @@ navigation: priority: 5 ``` -You can also change the order in the Docs configuration file. See [the chapter in the customization page](customization#navigation-menu--sidebar) for more details.
-_I personally think the config route is easier as it gives an instant overview, however the first way is nice as well._ +You can also change the order in the `config/docs.php` configuration file, which may be easier to manage for larger sites. See [the chapter in the customization page](customization#navigation-menu--sidebar) for more details. ### Sidebar labels From 0df917bd7eed259c1797cd1f9960bdfaf68e54a9 Mon Sep 17 00:00:00 2001 From: Caen De Silva Date: Fri, 12 Jul 2024 14:34:50 +0200 Subject: [PATCH 192/232] Reformat table --- docs/creating-content/documentation-pages.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/creating-content/documentation-pages.md b/docs/creating-content/documentation-pages.md index c3aa6d2f3d3..8e98b4722ce 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -77,13 +77,13 @@ Hyde makes documentation pages easy to create by automatically generating dynami Before we look at how to override things, here is an overview of the relevant content Hyde generates, and where the data is from as well as where it can be overridden. -| Property | Description | Dynamic Data Source | Override in | -|---------------------------------|--------------------------------------------------------|-------------------------------------|----------------------| -| `title` (string) | The title of the page used in the HTML `` tag | The first H1 heading (`# Foo`) | Front matter | -| `navigation.label` (string) | The label for the page shown in the sidebar | The page basename | Front matter, config | -| `navigation.priority` (integer) | The priority of the page used for ordering the sidebar | Defaults to 999 | Front matter, config | -| `navigation.hidden` (boolean) | Hides the page from the sidebar | _none_ | Front matter, config | -| `navigation.group` (string) | The group the page belongs to in the sidebar | Subdirectory, if nested | Front matter | +| Property | Description | Dynamic Data Source | Override in | +|---------------------------------|--------------------------------------------------------|--------------------------------|----------------------| +| `title` (string) | The title of the page used in the HTML `<title>` tag | The first H1 heading (`# Foo`) | Front matter | +| `navigation.label` (string) | The label for the page shown in the sidebar | The page basename | Front matter, config | +| `navigation.priority` (integer) | The priority of the page used for ordering the sidebar | Defaults to 999 | Front matter, config | +| `navigation.hidden` (boolean) | Hides the page from the sidebar | _none_ | Front matter, config | +| `navigation.group` (string) | The group the page belongs to in the sidebar | Subdirectory, if nested | Front matter | ## Sidebar From ab46ba42448864011e1a540aca972f13178f7891 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 14:35:16 +0200 Subject: [PATCH 193/232] Clarify that label is generated not literal --- docs/creating-content/documentation-pages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/creating-content/documentation-pages.md b/docs/creating-content/documentation-pages.md index 8e98b4722ce..6c1844014cb 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -104,7 +104,7 @@ You can also change the order in the `config/docs.php` configuration file, which ### Sidebar labels -The sidebar items are labelled with the `label` property. The default label is the filename of the file. +The sidebar items are labelled with the `label` property. The default label is generated from the filename of the file. You can change it with the following front matter: From ad504acffba78e30e05e835eb5e9153274c66176 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 14:39:41 +0200 Subject: [PATCH 194/232] Improve grouping documentation wording --- docs/creating-content/documentation-pages.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/creating-content/documentation-pages.md b/docs/creating-content/documentation-pages.md index 6c1844014cb..b1e75ad3bf2 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -115,9 +115,8 @@ navigation: ### Sidebar grouping -Sidebar grouping allows you to group items in the sidebar into categories. This is useful for creating a sidebar with a lot of items. The Hyde docs for instance use this. +Sidebar grouping allows you to group items in the sidebar under category headings. This is useful for creating a sidebar with a lot of items. The official HydePHP.com docs, for instance, use this feature. -The feature is enabled automatically when one or more of your documentation pages have the `navigation.group` property set in the front matter, or when subdirectories are used. This will then switch to a slightly more compact sidebar layout with pages sorted into categories. Any pages without the group front matter will get put in the "Other" group. ### Sidebar footer customization @@ -132,6 +131,7 @@ The sidebar footer contains, by default, a link to your site homepage. You can c ``` You can also set the option to `false` to disable it entirely. +The feature is enabled automatically when one or more of your documentation pages have the `navigation.group` property set in the front matter, or when documentation pages are organized in subdirectories. Once activated, Hyde will switch to a slightly more compact sidebar layout with pages sorted into labeled groups. Any pages without the group information will be put in the "Other" group. #### Using Front Matter From 5aa2fa59a06fbf9f6f2ed0fd29475d02aa449550 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 14:40:44 +0200 Subject: [PATCH 195/232] Fix wrong term used for sidebars --- docs/creating-content/documentation-pages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/creating-content/documentation-pages.md b/docs/creating-content/documentation-pages.md index b1e75ad3bf2..2b9d87d78db 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -150,7 +150,7 @@ For example, putting a Markdown file in `_docs/getting-started/`, is equivalent >info Note that when the [flattened output paths](#using-flattened-output-paths) setting is enabled (which it is by default), the file will still be compiled to the `_site/docs/` directory like it would be if you didn't use the subdirectories. Note that this means that you can't have two documentation pages with the same filename as they overwrite each other. ->info Tip: When using subdirectory-based dropdowns, you can set their priority using the directory name as the array key. +>info Tip: When using subdirectory-based grouping, you can set their priority using the directory name as the array key. ### Hiding items From cff03ac0513db462bf7ce087b44d2455e0996c25 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 14:41:07 +0200 Subject: [PATCH 196/232] Improve wording to be clearer --- docs/creating-content/documentation-pages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/creating-content/documentation-pages.md b/docs/creating-content/documentation-pages.md index 2b9d87d78db..bb6b10d5af6 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -150,7 +150,7 @@ For example, putting a Markdown file in `_docs/getting-started/`, is equivalent >info Note that when the [flattened output paths](#using-flattened-output-paths) setting is enabled (which it is by default), the file will still be compiled to the `_site/docs/` directory like it would be if you didn't use the subdirectories. Note that this means that you can't have two documentation pages with the same filename as they overwrite each other. ->info Tip: When using subdirectory-based grouping, you can set their priority using the directory name as the array key. +>info Tip: When using subdirectory-based grouping, you can set the priority of the groups using the directory name as the array key in the config file. ### Hiding items From c3fe8fb30ec3490acaa9bc820ab119c2c24ad1f9 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 14:41:40 +0200 Subject: [PATCH 197/232] Remove unnecessary line break --- docs/creating-content/documentation-pages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/creating-content/documentation-pages.md b/docs/creating-content/documentation-pages.md index bb6b10d5af6..6d94081a09c 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -163,7 +163,7 @@ navigation: This can be useful to create redirects or other items that should not be shown in the sidebar. ->info The index page is by default not shown as a sidebar item, but instead is linked in the sidebar header. <br> +>info The index page is by default not shown as a sidebar item, but instead is linked in the sidebar header. ## Customization From 9a2b2ef92c0a75327f0b3a218f8f0fa8799e7223 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 14:43:13 +0200 Subject: [PATCH 198/232] Fix punctuation --- docs/creating-content/documentation-pages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/creating-content/documentation-pages.md b/docs/creating-content/documentation-pages.md index 6d94081a09c..429c52fdf02 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -146,7 +146,7 @@ navigation: You can also automatically group your documentation pages by placing source files in sub-directories. -For example, putting a Markdown file in `_docs/getting-started/`, is equivalent to adding the same front matter seen above. +For example, putting a Markdown file in `_docs/getting-started/` is equivalent to adding the same front matter seen above. >info Note that when the [flattened output paths](#using-flattened-output-paths) setting is enabled (which it is by default), the file will still be compiled to the `_site/docs/` directory like it would be if you didn't use the subdirectories. Note that this means that you can't have two documentation pages with the same filename as they overwrite each other. From a7c6f8fd872a714df24de5fd084b57fbef99f2fe Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 14:43:23 +0200 Subject: [PATCH 199/232] Clarify wording --- docs/creating-content/documentation-pages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/creating-content/documentation-pages.md b/docs/creating-content/documentation-pages.md index 429c52fdf02..a41b0051a9d 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -148,7 +148,7 @@ You can also automatically group your documentation pages by placing source file For example, putting a Markdown file in `_docs/getting-started/` is equivalent to adding the same front matter seen above. ->info Note that when the [flattened output paths](#using-flattened-output-paths) setting is enabled (which it is by default), the file will still be compiled to the `_site/docs/` directory like it would be if you didn't use the subdirectories. Note that this means that you can't have two documentation pages with the same filename as they overwrite each other. +>info Note that when the [flattened output paths](#using-flattened-output-paths) setting is enabled (which it is by default), the file will still be compiled to the `_site/docs/` directory like it would be if you didn't use the subdirectories. Note that this means that you can't have two documentation pages with the same filename as they would overwrite each other. >info Tip: When using subdirectory-based grouping, you can set the priority of the groups using the directory name as the array key in the config file. From 87eec33dc43d08702dc59e04fe7e7159e7dcc04e Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 14:43:59 +0200 Subject: [PATCH 200/232] Fix section order --- docs/creating-content/documentation-pages.md | 28 ++++++++++---------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/creating-content/documentation-pages.md b/docs/creating-content/documentation-pages.md index a41b0051a9d..9781b605969 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -117,20 +117,6 @@ navigation: Sidebar grouping allows you to group items in the sidebar under category headings. This is useful for creating a sidebar with a lot of items. The official HydePHP.com docs, for instance, use this feature. - -### Sidebar footer customization - -The sidebar footer contains, by default, a link to your site homepage. You can change this in the `config/docs.php` file. - -```php -// filepath: config/docs.php - -'sidebar' => [ - 'footer' => 'My **Markdown** Footer Text', -], -``` - -You can also set the option to `false` to disable it entirely. The feature is enabled automatically when one or more of your documentation pages have the `navigation.group` property set in the front matter, or when documentation pages are organized in subdirectories. Once activated, Hyde will switch to a slightly more compact sidebar layout with pages sorted into labeled groups. Any pages without the group information will be put in the "Other" group. #### Using Front Matter @@ -197,6 +183,20 @@ By default, the site title shown in the sidebar header is generated from the con 'title' => 'API Documentation', ``` +### Sidebar footer customization + +The sidebar footer contains, by default, a link to your site homepage. You can change this in the `config/docs.php` file. + +```php +// filepath: config/docs.php + +'sidebar' => [ + 'footer' => 'My **Markdown** Footer Text', +], +``` + +You can also set the option to `false` to disable it entirely. + ### Sidebar page order To quickly arrange the order of items in the sidebar, you can reorder the page identifiers in the list and the links will be sorted in that order. Link items without an entry here will fall back to the default priority of 999, putting them last. From 3fb32ab31fec7aaa72f81059d121613ef121de99 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 14:50:30 +0200 Subject: [PATCH 201/232] Fix inline code formatting --- docs/creating-content/documentation-pages.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/creating-content/documentation-pages.md b/docs/creating-content/documentation-pages.md index 9781b605969..4e93ca87311 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -8,13 +8,13 @@ navigation: ## Introduction to Hyde Documentation Pages -Welcome to the Hyde Documentation Pages, where creating professional-looking documentation sites has never been easier. Using the Hyde Documentation module, all you need to do is place standard Markdown files in the _docs/ directory, and Hyde takes care of the rest. +Welcome to the Hyde Documentation Pages, where creating professional-looking documentation sites has never been easier. Using the Hyde Documentation module, all you need to do is place standard Markdown files in the `_docs/` directory, and Hyde takes care of the rest. Hyde compiles your Markdown content into beautiful static HTML pages using a TailwindCSS frontend, complete with a responsive sidebar that is automatically generated based on your Markdown files. You can even customize the order, labels, and groups of the sidebar items to suit your needs. Additionally, if you have a `_docs/index.md` file, the sidebar header will link to it, and an automatically generated "Docs" link will be added to your site's main navigation menu, pointing to your documentation page. -If you have a Torchlight API token in your .env file, Hyde will even enable syntax highlighting automatically, saving you time and effort. For more information about this feature, see the [extensions page](extensions#torchlight). +If you have a Torchlight API token in your `.env` file, Hyde will even enable syntax highlighting automatically, saving you time and effort. For more information about this feature, see the [extensions page](extensions#torchlight). ### Best Practices and Hyde Expectations From 79ef5b2c65fc3a83f592089c20d03dd29852bb94 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 14:50:42 +0200 Subject: [PATCH 202/232] Fix wrong page type name --- docs/creating-content/documentation-pages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/creating-content/documentation-pages.md b/docs/creating-content/documentation-pages.md index 4e93ca87311..d346b4b5356 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -18,7 +18,7 @@ If you have a Torchlight API token in your `.env` file, Hyde will even enable sy ### Best Practices and Hyde Expectations -Since Hyde does a lot of things automatically, there are some things you may need to keep in mind when creating blog posts so that you don't get unexpected results. +Since Hyde does a lot of things automatically, there are some things you may need to keep in mind when creating documentation pages so that you don't get unexpected results. #### Filenames From 591ae52148af9ef461f228b86f721a44a1308eea Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 14:57:29 +0200 Subject: [PATCH 203/232] Fix grammar --- docs/creating-content/documentation-pages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/creating-content/documentation-pages.md b/docs/creating-content/documentation-pages.md index d346b4b5356..14b6931f2dd 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -12,7 +12,7 @@ Welcome to the Hyde Documentation Pages, where creating professional-looking doc Hyde compiles your Markdown content into beautiful static HTML pages using a TailwindCSS frontend, complete with a responsive sidebar that is automatically generated based on your Markdown files. You can even customize the order, labels, and groups of the sidebar items to suit your needs. -Additionally, if you have a `_docs/index.md` file, the sidebar header will link to it, and an automatically generated "Docs" link will be added to your site's main navigation menu, pointing to your documentation page. +Additionally, if you have an `_docs/index.md` file, the sidebar header will link to it, and an automatically generated "Docs" link will be added to your site's main navigation menu, pointing to your documentation page. If you have a Torchlight API token in your `.env` file, Hyde will even enable syntax highlighting automatically, saving you time and effort. For more information about this feature, see the [extensions page](extensions#torchlight). From 3d3932d004744b8e94a1ba1de43c2323f2839331 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 15:26:48 +0200 Subject: [PATCH 204/232] Remove word that isn't to be there --- docs/creating-content/documentation-pages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/creating-content/documentation-pages.md b/docs/creating-content/documentation-pages.md index 3b32dec349a..708ed7e3d42 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -327,7 +327,7 @@ Changing the label is easy, just change the following config setting: #### Changing the position -By default, the button will be shown in both the documentation page footer. You can change this by setting the following config setting to `'header'`, `'footer'`, or `'both'` +By default, the button will be shown in the documentation page footer. You can change this by setting the following config setting to `'header'`, `'footer'`, or `'both'` ```php // Filepath: config/docs.php From 3f5a4dd3a74aceb80955a32fa83db4a153268afb Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 15:27:07 +0200 Subject: [PATCH 205/232] Add missing important word --- docs/creating-content/documentation-pages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/creating-content/documentation-pages.md b/docs/creating-content/documentation-pages.md index 708ed7e3d42..362dce28406 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -283,7 +283,7 @@ The second method is a button added to the documentation pages, similar to how A ### Hiding pages from indexing -If you have a large page on your documentation site, like a changelog, you may want to hide it from the search index. You can do this by adding the page identifier to the `exclude_from_search` array in the `docs` config, similar to how navigation menu items are hidden. The page will still be accessible as normal but will be added to the search index JSON file. +If you have a large page on your documentation site, like a changelog, you may want to hide it from the search index. You can do this by adding the page identifier to the `exclude_from_search` array in the `docs` config, similar to how navigation menu items are hidden. The page will still be accessible as normal but will not be added to the search index JSON file. ```php // filepath: config/docs.php From 4b5c86de32cb0b79fb52b4491545a71f3224b443 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 15:27:13 +0200 Subject: [PATCH 206/232] Use American English --- docs/creating-content/documentation-pages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/creating-content/documentation-pages.md b/docs/creating-content/documentation-pages.md index 362dce28406..7c809614f51 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -277,7 +277,7 @@ The search works by generating a JSON search index which the JavaScript plugin l Two ways to access the search are added, one is a full page search screen that will be saved to `docs/search.html`. -The second method is a button added to the documentation pages, similar to how Algolia DocSearch works. Opening it will open a modal with an integrated search screen. You can also open the dialogue using the keyboard shortcut `/`. +The second method is a button added to the documentation pages, similar to how Algolia DocSearch works. Opening it will open a modal with an integrated search screen. You can also open the dialog using the keyboard shortcut `/`. >info The full page can be disabled by setting `create_search_page` to `false` in the `docs` config. From f3c494e0a92818506fefb3e6c777f00a69485a74 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 15:27:36 +0200 Subject: [PATCH 207/232] Split out subordinate clause to separate sentence --- docs/creating-content/documentation-pages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/creating-content/documentation-pages.md b/docs/creating-content/documentation-pages.md index 7c809614f51..1c566e85cd0 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -302,7 +302,7 @@ The Realtime Compiler that powers the `php hyde serve` command will automaticall Hyde can automatically add links to documentation pages that take the user to a GitHub page (or similar) to edit the page. This makes it great for open-source projects looking to allow others to contribute to the documentation in a quick and easy manner. -The feature is automatically enabled when you specify a base URL in the Docs configuration file. Hyde expects this to be a GitHub path, but it will probably work with other methods as well, if not, please send a PR and/or create an issue on the [GitHub repository](https://github.com/hydephp/framework)! +The feature is automatically enabled when you specify a base URL in the Docs configuration file. Hyde expects this to be a GitHub path, but it will probably work with other methods as well. If not, please send a PR and/or create an issue on the [GitHub repository](https://github.com/hydephp/framework)! >info Tip: This documentation site uses this feature, scroll down to the bottom of this page and try it out! From dc69f6ab6b58df53a9dd2af7469139d0499c6b3d Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 15:28:00 +0200 Subject: [PATCH 208/232] Use APA style headings --- docs/creating-content/documentation-pages.md | 44 ++++++++++---------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/docs/creating-content/documentation-pages.md b/docs/creating-content/documentation-pages.md index 1c566e85cd0..185a6539b2f 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -29,7 +29,7 @@ Since Hyde does a lot of things automatically, there are some things you may nee - You should always have an `index.md` file in the `_docs/` directory - Your page will be stored in `_site/docs/<identifier>.html` unless you [change it in the config](#output-directory) -### Advanced usage and customization +### Advanced Usage and Customization Like most of HydePHP, the Hyde Documentation module is highly customizable. Much of the frontend is composed using Blade templates and components, which you can customize to your heart's content. Since there are so many components, it's hard to list them all here in the documentation, so I encourage you to check out the [source code](https://github.com/hydephp/framework/tree/master/resources/views/components/docs) to see how it's all put together and find the customizations you are looking for. @@ -51,7 +51,7 @@ This will create the following file saved as `_docs/page-title.md` ``` -### Front Matter is optional +### Front Matter Is Optional You don't need to use [front matter](blog-posts#supported-front-matter-properties) to create a documentation page. @@ -73,7 +73,7 @@ navigation: Hyde makes documentation pages easy to create by automatically generating dynamic content such as the sidebar and page title. If you are not happy with the results you can customize them in the config or with front matter. -### Front Matter reference +### Front Matter Reference Before we look at how to override things, here is an overview of the relevant content Hyde generates, and where the data is from as well as where it can be overridden. @@ -91,7 +91,7 @@ The sidebar is automatically generated from the files in the `_docs` directory. Since this feature shares a lot of similarities and implementation details with the navigation menu, I recommend you read the [navigation menu documentation](navigation) page as well to learn more about the fundamentals and terminology. -### Sidebar ordering +### Sidebar Ordering The sidebar is sorted/ordered by the `priority` property. The lower the priority value, the higher up in the sidebar it will be. The default priority is 999. You can override the priority using the following front matter: @@ -102,7 +102,7 @@ navigation: You can also change the order in the `config/docs.php` configuration file, which may be easier to manage for larger sites. See [the chapter in the customization page](customization#navigation-menu--sidebar) for more details. -### Sidebar labels +### Sidebar Labels The sidebar items are labelled with the `label` property. The default label is generated from the filename of the file. @@ -113,7 +113,7 @@ navigation: label: "My Custom Sidebar Label" ``` -### Sidebar grouping +### Sidebar Grouping Sidebar grouping allows you to group items in the sidebar under category headings. This is useful for creating a sidebar with a lot of items. The official HydePHP.com docs, for instance, use this feature. @@ -128,7 +128,7 @@ navigation: group: "Getting Started" ``` -#### Automatic subdirectory-based grouping +#### Automatic Subdirectory-Based Grouping You can also automatically group your documentation pages by placing source files in sub-directories. @@ -155,7 +155,7 @@ This can be useful to create redirects or other items that should not be shown i Please see the [customization page](customization) for in-depth information on how to customize Hyde, including the documentation pages. Here is a high level overview for quick reference though. -### Output directory +### Output Directory If you want to store the compiled documentation pages in a different directory than the default 'docs' directory, for example to specify a version like the Hyde docs does, you can specify the output directory in the Hyde configuration file. @@ -171,11 +171,11 @@ The path is relative to the site output, typically `_site`. Note that you need to take care as to not set it to something that may conflict with other parts, such as media or posts directories. -### Automatic navigation menu +### Automatic Navigation Menu By default, a link to the documentation page is added to the navigation menu when an index.md file is found in the `_docs` directory. Please see [the customization page](customization#navigation-menu--sidebar) for more information. -### Sidebar header name +### Sidebar Header Name By default, the site title shown in the sidebar header is generated from the configured site name suffixed with "docs". You can change this in the Docs configuration file. Tip: The header will link to the docs/index page, if it exists. @@ -183,7 +183,7 @@ By default, the site title shown in the sidebar header is generated from the con 'title' => 'API Documentation', ``` -### Sidebar footer customization +### Sidebar Footer Customization The sidebar footer contains, by default, a link to your site homepage. You can change this in the `config/docs.php` file. @@ -197,7 +197,7 @@ The sidebar footer contains, by default, a link to your site homepage. You can c You can also set the option to `false` to disable it entirely. -### Sidebar page order +### Sidebar Page Order To quickly arrange the order of items in the sidebar, you can reorder the page identifiers in the list and the links will be sorted in that order. Link items without an entry here will fall back to the default priority of 999, putting them last. @@ -213,7 +213,7 @@ To quickly arrange the order of items in the sidebar, you can reorder the page i See [the chapter in the customization page](customization#navigation-menu--sidebar) for more details. <br> -### Automatic sidebar group labels +### Automatic Sidebar Group Labels When using the automatic sidebar grouping feature (based on subdirectories), the titles of the groups are generated from the directory names. If these are not to your liking, for example if you need to use special characters, you can override them in the Docs configuration file. The array key is the directory name, and the value is the label. @@ -227,7 +227,7 @@ Please note that this option is not added to the config file by default, as it's ], ``` -### Table of contents settings +### Table of Contents Settings Hyde automatically generates a table of contents for the page and adds it to the sidebar. @@ -243,7 +243,7 @@ In the `config/docs.php` file you can configure the behaviour, content, and the ], ``` -### Using flattened output paths +### Using Flattened Output Paths If this setting is set to true, Hyde will output all documentation pages into the same configured documentation output directory. This means that you can use the automatic directory-based grouping feature, but still have a "flat" output structure. Note that this means that you can't have two documentation pages with the same filename or navigation menu label as they will overwrite each other. @@ -271,7 +271,7 @@ The search feature is enabled by default. You can disable it by removing the `Do ], ``` -### Using the search +### Using the Search The search works by generating a JSON search index which the JavaScript plugin loads asynchronously. @@ -281,7 +281,7 @@ The second method is a button added to the documentation pages, similar to how A >info The full page can be disabled by setting `create_search_page` to `false` in the `docs` config. -### Hiding pages from indexing +### Hiding Pages from Indexing If you have a large page on your documentation site, like a changelog, you may want to hide it from the search index. You can do this by adding the page identifier to the `exclude_from_search` array in the `docs` config, similar to how navigation menu items are hidden. The page will still be accessible as normal but will not be added to the search index JSON file. @@ -292,7 +292,7 @@ If you have a large page on your documentation site, like a changelog, you may w ] ``` -### Live search with the realtime compiler +### Live Search with the Realtime Compiler The Realtime Compiler that powers the `php hyde serve` command will automatically generate a fresh search index each time the browser requests it. @@ -316,7 +316,7 @@ Here's an example configuration from the official HydePHP.com documentation: 'source_file_location_base' => 'https://github.com/hydephp/docs/blob/master/', ``` -#### Changing the button text +#### Changing the Button Text Changing the label is easy, just change the following config setting: @@ -325,7 +325,7 @@ Changing the label is easy, just change the following config setting: 'edit_source_link_text' => 'Edit Source on GitHub', ``` -#### Changing the position +#### Changing the Position By default, the button will be shown in the documentation page footer. You can change this by setting the following config setting to `'header'`, `'footer'`, or `'both'` @@ -334,7 +334,7 @@ By default, the button will be shown in the documentation page footer. You can c 'edit_source_link_position' => 'header', ``` -#### Adding a button icon +#### Adding a Button Icon This is not included out of the box, but is easy to add with some CSS! Just target the `.edit-page-link` class. @@ -343,6 +343,6 @@ This is not included out of the box, but is easy to add with some CSS! Just targ .edit-page-link::before {content: "✏ "} ``` -#### Changing the Blade view +#### Changing the Blade View You can also publish the `edit-source-button.blade.php` view and change it to your liking. From 7021d23d5e65507b6513456f63feaef27e5fc93c Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 15:34:46 +0200 Subject: [PATCH 209/232] Fix clarity --- docs/digging-deeper/navigation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index e9ae8e50818..04832cdb3b9 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -107,8 +107,8 @@ navigation: Let's explore how to customize navigation menus using configuration files: -- For the main navigation menu, use `navigation` setting in the `hyde.php` config file. -- For the sidebar, use `sidebar` setting in the `docs.php` config file. +- For the main navigation menu, use the `navigation` setting in the `hyde.php` config file. +- For the sidebar, use the `sidebar` setting in the `docs.php` config file. When customizing the main navigation menu, use the [route key](core-concepts#route-keys) of the page. For the sidebar, you can use either the route key or the [page identifier](core-concepts#page-identifiers). From 1eb578ce29a1de6d03b703464b5b5a774afb09d1 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 15:34:59 +0200 Subject: [PATCH 210/232] Fix title formatting --- docs/digging-deeper/navigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 04832cdb3b9..a25c4329b8f 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -181,7 +181,7 @@ You could also combine these methods if desired: ] ``` -### Changing Menu item Labels +### Changing Menu Item Labels Hyde makes a few attempts to find a suitable label for the navigation menu items to automatically create helpful titles. From 14c5ac64e24340959210be825b763b929775f671 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 15:35:07 +0200 Subject: [PATCH 211/232] Use shorter synonym --- docs/digging-deeper/navigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index a25c4329b8f..bd0cfe13260 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -201,7 +201,7 @@ If you're not happy with these, it's easy to override navigation link labels by ### Excluding Items (Blacklist) -When you have a lot of pages, it may be useful to prevent links from being added to the main navigation menu. +When you have many pages, it may be useful to prevent links from being added to the main navigation menu. To exclude items from being added, simply add the page's route key to the navigation blacklist in the Hyde config: From 18fafba70484ded8328de00b272120b4698c2960 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 15:35:38 +0200 Subject: [PATCH 212/232] Remove comma from coupled clauses --- docs/digging-deeper/navigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index bd0cfe13260..561281a3bac 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -20,7 +20,7 @@ This documentation will guide you through the customization process. To learn ev ### Internal Structure Overview -Internally, both navigation menu types extend the same base class, and thus share core functionality. This means the configuration process is similar for both types, making the documentation applicable to both. +Internally, both navigation menu types extend the same base class and thus share core functionality. This means the configuration process is similar for both types, making the documentation applicable to both. For a deeper understanding of the internal workings, refer to the [Digging Deeper](#digging-deeper-into-the-internals) section. From fcc030d65aa0b115c5a19ead2683df738ba51342 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 15:35:49 +0200 Subject: [PATCH 213/232] Reword line to be more fluent --- docs/digging-deeper/navigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 561281a3bac..8019adf378e 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -33,7 +33,7 @@ All navigation menu items have an internal priority value determining their orde Here's an overview of what you can customize in your navigation menus: - Item labels: The text displayed in menu links -- Item priorities: Control the order of link appearance +- Item priorities: Control the order in which links appear - Item visibility: Choose to hide or show pages in the menu - Item grouping: Group pages together in dropdowns or sidebar categories From 714e941f0d4e07b08946f025d6fa8eab954de367 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 15:40:46 +0200 Subject: [PATCH 214/232] Use plural wording to match other pluralized terms in sentence --- docs/digging-deeper/navigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 8019adf378e..5772e667c58 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -183,7 +183,7 @@ You could also combine these methods if desired: ### Changing Menu Item Labels -Hyde makes a few attempts to find a suitable label for the navigation menu items to automatically create helpful titles. +Hyde makes a few attempts to find suitable labels for the navigation menu items to automatically create helpful titles. If you're not happy with these, it's easy to override navigation link labels by mapping the route key to the desired title in the Hyde config: From 1bea0eff74c4b698c6d3ebf0141822903d6d486a Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 15:40:55 +0200 Subject: [PATCH 215/232] Add missing infix --- docs/digging-deeper/navigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 5772e667c58..4f9f4407567 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -248,7 +248,7 @@ You can configure how subdirectories should be displayed in the menu: **Supported Options:** - `dropdown`: Pages in subdirectories are displayed in a dropdown menu -- `hidden`: Pages in subdirectories are not displayed at all the menus +- `hidden`: Pages in subdirectories are not displayed at all in the menus - `flat`: Pages in subdirectories are displayed as individual items ### Automatic Menu Groups From d269f6aa981fcd063d93e79057b18f14efe334c8 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 15:41:19 +0200 Subject: [PATCH 216/232] Add comma between independent clauses --- docs/digging-deeper/navigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 4f9f4407567..1c729c6bf28 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -266,7 +266,7 @@ Enable this feature in the `hyde.php` config file by setting the `subdirectory_d ], ``` -Now if you create a page called `_pages/about/contact.md` it will automatically be placed in a dropdown called "About". +Now if you create a page called `_pages/about/contact.md`, it will automatically be placed in a dropdown called "About". #### Automatic Documentation Sidebar Grouping From 74c4924e24c44134f00d9a5adf62102cc64b070e Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 15:41:27 +0200 Subject: [PATCH 217/232] Fix typo should be a comma --- docs/digging-deeper/navigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 1c729c6bf28..cad3ff23fd3 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -294,7 +294,7 @@ _pages/ 03-contact.md # Priority: 3 (saved to _site/contact.html) ``` -As you can seem Hyde parses the number from the filename and uses it as the priority for the page in navigation menus, while stripping the prefix from the route key. +As you can see, Hyde parses the number from the filename and uses it as the priority for the page in navigation menus, while stripping the prefix from the route key. ### Important Notes From c00ab1b394d3337b43eb687ba1b11a968a8213c6 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 15:41:33 +0200 Subject: [PATCH 218/232] Add missing word --- docs/digging-deeper/navigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index cad3ff23fd3..6dbfcca6c9a 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -311,7 +311,7 @@ This feature integrates well with automatic subdirectory-based navigation groupi 1. You can use numerical prefixes in subdirectories to control the dropdown/sidebar order. 2. The numbering within a subdirectory works independently of its siblings, so you can start from one in each subdirectory. -Here is an example structure of how could organize a documentation site: +Here is an example structure of how you could organize a documentation site: ```shell _docs/ From 8129241d413a1d92d1f08e1ee6de895937a5a22d Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 15:41:49 +0200 Subject: [PATCH 219/232] Remove comma from coupled clauses --- docs/digging-deeper/navigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 6dbfcca6c9a..532c40ab24a 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -118,7 +118,7 @@ The `navigation.order` and `sidebar.order` settings allow you to customize the o #### Basic Priority Syntax -A nice and simple way to define the order of pages, is to add their route keys as a simple list array. We'll then match that array order. +A nice and simple way to define the order of pages is to add their route keys as a simple list array. We'll then match that array order. It may be useful to know that we internally will assign a priority calculated according to its position in the list, plus an offset of `500`. The offset is added to make it easier to place pages earlier in the list using front matter or with explicit priority settings. From 312135ee71eefc64e64ab3c7dc911adc6a605e3a Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 15:42:00 +0200 Subject: [PATCH 220/232] Change word order to be more fluent --- docs/digging-deeper/navigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 532c40ab24a..1e8c73bce68 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -26,7 +26,7 @@ For a deeper understanding of the internal workings, refer to the [Digging Deepe ### Understanding Priorities -All navigation menu items have an internal priority value determining their order. Lower values place items higher in the menu. The default priority for pages is `999`, placing them last unless you specify a value. Some pages, like the `index` page, are by default configured with the lowest priority of `0`. +All navigation menu items have an internal priority value determining their order. Lower values place items higher in the menu. The default priority for pages is `999`, placing them last unless you specify a value. Some pages, like the `index` page, are configured by default with the lowest priority of `0`. ### Customization Options From e46b837feec20ec8673068ded7ef346e22cd158f Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 15:42:38 +0200 Subject: [PATCH 221/232] Split out coupled clause to standalone sentence --- docs/digging-deeper/navigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 1e8c73bce68..b79b2f39478 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -285,7 +285,7 @@ For example: `_docs/getting-started/installation.md` will be placed in a group c HydePHP v2 introduces navigation item ordering based on numerical prefixes in filenames. This feature works for both the primary navigation menu and the documentation sidebar. -This has the great benefit of matching the navigation menu layout with the file structure view, and works especially great with subdirectory-based navigation grouping. +This has the great benefit of matching the navigation menu layout with the file structure view. It also works especially well with subdirectory-based navigation grouping. ```shell _pages/ From a5df67f53181ebc8277d9f25fa9e675a19a0c08a Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 15:42:54 +0200 Subject: [PATCH 222/232] Reword to pluralize feature in introduction --- docs/digging-deeper/navigation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index b79b2f39478..95e926b45c9 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -8,7 +8,7 @@ navigation: ## Introduction -HydePHP offers an automatic navigation menu and documentation sidebar generation feature, designed to take the pain out of creating navigation menus. +HydePHP offers automatic navigation menu and documentation sidebar generation features, designed to take the pain out of creating navigation menus. While Hyde does its best to configure these menus automatically based on understanding your project files, you may want to customize them further. There are two types of navigation menus in Hyde: From 5a5d36d9c593a914e2c71a3d9ded631f7ed0b73c Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 17:28:58 +0200 Subject: [PATCH 223/232] Move the sidebar documentation to the documentation pages page --- docs/creating-content/documentation-pages.md | 47 +++++++++++- docs/digging-deeper/customization.md | 7 +- docs/digging-deeper/navigation.md | 78 ++++---------------- 3 files changed, 66 insertions(+), 66 deletions(-) diff --git a/docs/creating-content/documentation-pages.md b/docs/creating-content/documentation-pages.md index 185a6539b2f..08cb115a596 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -100,7 +100,52 @@ navigation: priority: 5 ``` -You can also change the order in the `config/docs.php` configuration file, which may be easier to manage for larger sites. See [the chapter in the customization page](customization#navigation-menu--sidebar) for more details. +You can also change the order in the `config/docs.php` configuration file, which may be easier to manage for larger sites. + +#### Basic Priority Syntax + +A nice and simple way to define the order of pages is to add their route keys as a simple list array. Hyde will then match that array order. + +It may be useful to know that Hyde internally will assign a priority calculated according to its position in the list, plus an offset of `500`. The offset is added to make it easier to place pages earlier in the list using front matter or with explicit priority settings. + +```php +// filepath: config/docs.php +'sidebar' => [ + 'order' => [ + 'readme', // Priority: 500 + 'installation', // Priority: 501 + 'getting-started', // Priority: 502 + ] +] +``` + +#### Explicit Priority Syntax + +You can also specify explicit priorities by adding a value to the array keys. Hyde will then use these exact values as the priorities. + +```php +// filepath: config/docs.php +'sidebar' => [ + 'order' => [ + 'readme' => 10, + 'installation' => 15, + 'getting-started' => 20, + ] +] +``` + +You could also combine these methods if desired: + +```php +// filepath: config/docs.php +'sidebar' => [ + 'order' => [ + 'readme' => 10, // Priority: 10 + 'installation', // Priority: 500 + 'getting-started', // Priority: 501 + ] +] +``` ### Sidebar Labels diff --git a/docs/digging-deeper/customization.md b/docs/digging-deeper/customization.md index 19b78e541f7..f9c7a0f5682 100644 --- a/docs/digging-deeper/customization.md +++ b/docs/digging-deeper/customization.md @@ -283,15 +283,18 @@ Still, you will likely want to customize some parts of these menus, and thankful - To customize the navigation menu, use the setting `navigation.order` in the `hyde.php` config. - When customizing the navigation menu, you should use the [route key](core-concepts#route-keys) of the page. +- You can use either a basic list array or specify explicit priorities. Learn more in the [Navigation Menu](navigation) documentation. #### Customizing the documentation sidebar - To customize the sidebar, use the setting `sidebar.order` in the `docs.php` config. -- When customizing the sidebar, can use the route key, or just the [page identifier](core-concepts#page-identifiers) of the page. +- When customizing the sidebar, you can use the route key, or just the [page identifier](core-concepts#page-identifiers) of the page. +- Similar to the navigation menu, you can use a basic list array or specify explicit priorities. +- You can also use front matter in individual documentation pages to customize their appearance and behavior in the sidebar. -Learn more in the [Documentation Pages](documentation-pages) documentation. +Learn more in the [Documentation Pages](documentation-pages#sidebar) documentation. ## Additional Advanced Options diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 95e926b45c9..1eaa8464876 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -8,7 +8,7 @@ navigation: ## Introduction -HydePHP offers automatic navigation menu and documentation sidebar generation features, designed to take the pain out of creating navigation menus. +HydePHP offers automatic navigation menu generation features, designed to take the pain out of creating navigation menus. While Hyde does its best to configure these menus automatically based on understanding your project files, you may want to customize them further. There are two types of navigation menus in Hyde: @@ -16,7 +16,7 @@ There are two types of navigation menus in Hyde: 1. **Primary Navigation Menu**: The main navigation menu appearing on most pages of your site. Unique features include dropdowns for subdirectories, depending on configuration. 2. **Documentation Sidebar**: The sidebar on documentation pages with links to other documentation pages. Unique features include automatic grouping based on subdirectories. -This documentation will guide you through the customization process. To learn even more about sidebars, visit the [Documentation Pages](documentation-pages) documentation. +This documentation will guide you through the customization process of the primary navigation menu. To learn about the documentation sidebar, visit the [Documentation Pages](documentation-pages) documentation. ### Internal Structure Overview @@ -43,11 +43,10 @@ Hyde provides multiple ways to customize navigation menus to suit your needs: 1. Front matter data in Markdown and Blade page files, applicable to all menu types 2. Configuration in the `hyde` config file for main navigation items -3. Configuration in the `docs` config file for documentation sidebar items Keep in mind that front matter data overrides dynamically inferred or config-defined priorities. While useful for quick one-off changes on small sites, it can make reordering items later on more challenging as you can't see the entire structure at once. -Additionally, general options for the entire navigation menus are also available in the `hyde` and `docs` config files. +Additionally, general options for the entire navigation menus are also available in the `hyde` config file. ## Front Matter Configuration @@ -105,16 +104,15 @@ navigation: ## Config File Configuration -Let's explore how to customize navigation menus using configuration files: +Let's explore how to customize the main navigation menu using configuration files: - For the main navigation menu, use the `navigation` setting in the `hyde.php` config file. -- For the sidebar, use the `sidebar` setting in the `docs.php` config file. -When customizing the main navigation menu, use the [route key](core-concepts#route-keys) of the page. For the sidebar, you can use either the route key or the [page identifier](core-concepts#page-identifiers). +When customizing the main navigation menu, use the [route key](core-concepts#route-keys) of the page. ### Changing Priorities -The `navigation.order` and `sidebar.order` settings allow you to customize the order of pages in the navigation menus. +The `navigation.order` setting allows you to customize the order of pages in the main navigation menu. #### Basic Priority Syntax @@ -133,17 +131,6 @@ It may be useful to know that we internally will assign a priority calculated ac ] ``` -```php -// filepath: config/docs.php -'sidebar' => [ - 'order' => [ - 'readme', // Priority: 500 - 'installation', // Priority: 501 - 'getting-started', // Priority: 502 - ] -] -``` - #### Explicit Priority Syntax You can also specify explicit priorities by adding a value to the array keys. We'll then use these exact values as the priorities. @@ -159,25 +146,16 @@ You can also specify explicit priorities by adding a value to the array keys. We ] ``` -```php -// filepath: config/docs.php -'sidebar' => [ - 'order' => [ - 'readme' => 10, - 'installation' => 15, - 'getting-started' => 20, - ] -] -``` - You could also combine these methods if desired: ```php -// filepath: Applicable to both -[ - 'readme' => 10, // Priority: 10 - 'installation', // Priority: 500 - 'getting-started', // Priority: 501 +// filepath: config/hyde.php +'navigation' => [ + 'order' => [ + 'home' => 10, // Priority: 10 + 'about', // Priority: 500 + 'contact', // Priority: 501 + ] ] ``` @@ -197,8 +175,6 @@ If you're not happy with these, it's easy to override navigation link labels by ] ``` -**Note:** This feature is not yet supported for the sidebar. - ### Excluding Items (Blacklist) When you have many pages, it may be useful to prevent links from being added to the main navigation menu. @@ -268,14 +244,6 @@ Enable this feature in the `hyde.php` config file by setting the `subdirectory_d Now if you create a page called `_pages/about/contact.md`, it will automatically be placed in a dropdown called "About". -#### Automatic Documentation Sidebar Grouping - -This feature is always enabled for documentation pages. Simply place your pages in subdirectories to have them grouped in the sidebar. - -For example: `_docs/getting-started/installation.md` will be placed in a group called "Getting Started". - ->info Tip: When using subdirectory-based dropdowns, you can set their priority using the directory name as the array key. - #### Dropdown Menu Notes - Dropdowns take priority over standard items. If you have a dropdown with the key `about` and a page with the key `about`, the dropdown will be created, and the page won't be in the menu. @@ -283,7 +251,7 @@ For example: `_docs/getting-started/installation.md` will be placed in a group c ## Numerical Prefix Navigation Ordering -HydePHP v2 introduces navigation item ordering based on numerical prefixes in filenames. This feature works for both the primary navigation menu and the documentation sidebar. +HydePHP v2 introduces navigation item ordering based on numerical prefixes in filenames. This feature works for the primary navigation menu. This has the great benefit of matching the navigation menu layout with the file structure view. It also works especially well with subdirectory-based navigation grouping. @@ -308,25 +276,9 @@ As you can see, Hyde parses the number from the filename and uses it as the prio This feature integrates well with automatic subdirectory-based navigation grouping. Here are two useful tips: -1. You can use numerical prefixes in subdirectories to control the dropdown/sidebar order. +1. You can use numerical prefixes in subdirectories to control the dropdown order. 2. The numbering within a subdirectory works independently of its siblings, so you can start from one in each subdirectory. -Here is an example structure of how you could organize a documentation site: - -```shell -_docs/ - 01-getting-started/ - 01-installation.md - 02-requirements.md - 03-configuration.md - 02-usage/ - 01-quick-start.md - 02-advanced-usage.md - 03-features/ - 01-feature-1.md - 02-feature-2.md -``` - ### Customization If you're not interested in using numerical prefix ordering, you can disable it in the Hyde config file. Hyde will then no longer extract the priority and will no longer strip the prefix from the route key. From 8427e55bb455cc446ba07b9eb75a6691c99aae74 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 17:29:43 +0200 Subject: [PATCH 224/232] Add lost section --- docs/creating-content/documentation-pages.md | 55 ++++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/docs/creating-content/documentation-pages.md b/docs/creating-content/documentation-pages.md index 08cb115a596..5341159625b 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -272,6 +272,61 @@ Please note that this option is not added to the config file by default, as it's ], ``` +### Numerical Prefix Sidebar Ordering + +HydePHP v2 introduces sidebar item ordering based on numerical prefixes in filenames. This feature works for the documentation sidebar. + +This has the great benefit of matching the sidebar layout with the file structure view. It also works especially well with subdirectory-based sidebar grouping. + +```shell +_docs/ + 01-installation.md # Priority: 1 + 02-configuration.md # Priority: 2 + 03-usage.md # Priority: 3 +``` + +As you can see, Hyde parses the number from the filename and uses it as the priority for the page in the sidebar, while stripping the prefix from the route key. + +#### Important Notes + +1. The numerical prefix remains part of the page identifier but is stripped from the route key. + For example: `_docs/01-installation.md` has route key `installation` and page identifier `01-installation`. +2. You can delimit the numerical prefix with either a dash or an underscore. + For example: Both `_docs/01-installation.md` and `_docs/01_installation.md` are valid. +3. Leading zeros are optional. `_docs/1-installation.md` is equally valid. + +#### Using Numerical Prefix Ordering in Subdirectories + +This feature integrates well with automatic subdirectory-based sidebar grouping. Here's an example of how you could organize a documentation site: + +```shell +_docs/ + 01-getting-started/ + 01-installation.md + 02-requirements.md + 03-configuration.md + 02-usage/ + 01-quick-start.md + 02-advanced-usage.md + 03-features/ + 01-feature-1.md + 02-feature-2.md +``` + +Here are two useful tips: + +1. You can use numerical prefixes in subdirectories to control the sidebar group order. +2. The numbering within a subdirectory works independently of its siblings, so you can start from one in each subdirectory. + +#### Customization + +If you're not interested in using numerical prefix ordering, you can disable it in the Hyde config file. Hyde will then no longer extract the priority and will no longer strip the prefix from the route key. + +```php +// filepath: config/hyde.php +'numerical_page_ordering' => false, +``` + ### Table of Contents Settings Hyde automatically generates a table of contents for the page and adds it to the sidebar. From 68f3d33d9d1fd8beb258938e32f3d6084a037be8 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 17:43:03 +0200 Subject: [PATCH 225/232] Remove documentation for syntax with no benefit --- docs/creating-content/documentation-pages.md | 13 ------------- docs/digging-deeper/navigation.md | 13 ------------- 2 files changed, 26 deletions(-) diff --git a/docs/creating-content/documentation-pages.md b/docs/creating-content/documentation-pages.md index 5341159625b..3c7d7680026 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -134,19 +134,6 @@ You can also specify explicit priorities by adding a value to the array keys. Hy ] ``` -You could also combine these methods if desired: - -```php -// filepath: config/docs.php -'sidebar' => [ - 'order' => [ - 'readme' => 10, // Priority: 10 - 'installation', // Priority: 500 - 'getting-started', // Priority: 501 - ] -] -``` - ### Sidebar Labels The sidebar items are labelled with the `label` property. The default label is generated from the filename of the file. diff --git a/docs/digging-deeper/navigation.md b/docs/digging-deeper/navigation.md index 1eaa8464876..ffef925624d 100644 --- a/docs/digging-deeper/navigation.md +++ b/docs/digging-deeper/navigation.md @@ -146,19 +146,6 @@ You can also specify explicit priorities by adding a value to the array keys. We ] ``` -You could also combine these methods if desired: - -```php -// filepath: config/hyde.php -'navigation' => [ - 'order' => [ - 'home' => 10, // Priority: 10 - 'about', // Priority: 500 - 'contact', // Priority: 501 - ] -] -``` - ### Changing Menu Item Labels Hyde makes a few attempts to find suitable labels for the navigation menu items to automatically create helpful titles. From 8d06b5e6f3b4f8937badfc298ff758a231e31f3a Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 17:43:46 +0200 Subject: [PATCH 226/232] Normalize spelling --- docs/creating-content/documentation-pages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/creating-content/documentation-pages.md b/docs/creating-content/documentation-pages.md index 3c7d7680026..5bc9a900133 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -162,7 +162,7 @@ navigation: #### Automatic Subdirectory-Based Grouping -You can also automatically group your documentation pages by placing source files in sub-directories. +You can also automatically group your documentation pages by placing source files in subdirectories. For example, putting a Markdown file in `_docs/getting-started/` is equivalent to adding the same front matter seen above. From c2dcb0fd2498a9cc31b779d370dd8de9c232f926 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 17:53:30 +0200 Subject: [PATCH 227/232] Restructure and improve the documentation --- docs/creating-content/documentation-pages.md | 27 +++++++++++++++----- 1 file changed, 20 insertions(+), 7 deletions(-) diff --git a/docs/creating-content/documentation-pages.md b/docs/creating-content/documentation-pages.md index 5bc9a900133..0819dc267e9 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -166,9 +166,7 @@ You can also automatically group your documentation pages by placing source file For example, putting a Markdown file in `_docs/getting-started/` is equivalent to adding the same front matter seen above. ->info Note that when the [flattened output paths](#using-flattened-output-paths) setting is enabled (which it is by default), the file will still be compiled to the `_site/docs/` directory like it would be if you didn't use the subdirectories. Note that this means that you can't have two documentation pages with the same filename as they would overwrite each other. - ->info Tip: When using subdirectory-based grouping, you can set the priority of the groups using the directory name as the array key in the config file. +>warning Note that when the [flattened output paths](#using-flattened-output-paths) setting is enabled (which it is by default), the file will still be compiled to the `_site/docs/` directory like it would be if you didn't use the subdirectories. Note that this means that you can't have two documentation pages with the same filename as they would overwrite each other. ### Hiding Items @@ -245,11 +243,9 @@ To quickly arrange the order of items in the sidebar, you can reorder the page i See [the chapter in the customization page](customization#navigation-menu--sidebar) for more details. <br> -### Automatic Sidebar Group Labels - -When using the automatic sidebar grouping feature (based on subdirectories), the titles of the groups are generated from the directory names. If these are not to your liking, for example if you need to use special characters, you can override them in the Docs configuration file. The array key is the directory name, and the value is the label. +### Setting Sidebar Group Labels -Please note that this option is not added to the config file by default, as it's not a super common use case. No worries though, just add the following yourself! +When using the automatic sidebar grouping feature the titles of the groups are generated from the subdirectory names. If these are not to your liking, for example if you need to use special characters, you can override them in the configuration file. The array key is the directory name, and the value is the label. ```php // Filepath: config/docs.php @@ -259,6 +255,23 @@ Please note that this option is not added to the config file by default, as it's ], ``` +Please note that this option is not added to the config file by default, as it's not a super common use case. No worries though, just add the following yourself! + +#### Setting Group Priorities + +When using subdirectory-based grouping, you can set the priority of the groups using the directory name as the array key in the config file: + +```php +// Filepath: config/docs.php +'sidebar' => [ + 'order' => [ + 'readme', + 'installation', + 'getting-started', + ], +], +``` + ### Numerical Prefix Sidebar Ordering HydePHP v2 introduces sidebar item ordering based on numerical prefixes in filenames. This feature works for the documentation sidebar. From 358bfcc81207676c44580dd8281f03987e2e83af Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 17:57:24 +0200 Subject: [PATCH 228/232] Improve priority setting --- docs/creating-content/documentation-pages.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/creating-content/documentation-pages.md b/docs/creating-content/documentation-pages.md index 0819dc267e9..2238f6777d9 100644 --- a/docs/creating-content/documentation-pages.md +++ b/docs/creating-content/documentation-pages.md @@ -257,9 +257,11 @@ When using the automatic sidebar grouping feature the titles of the groups are g Please note that this option is not added to the config file by default, as it's not a super common use case. No worries though, just add the following yourself! -#### Setting Group Priorities +#### Setting Sidebar Group Priorities -When using subdirectory-based grouping, you can set the priority of the groups using the directory name as the array key in the config file: +By default, each group will be assigned the lowest priority found inside the group. However, you can specify the order and priorities for sidebar group keys the same way you can for the sidebar items. + +Just use the sidebar group key as instead of the page identifier/route key: ```php // Filepath: config/docs.php From 2d5edf6967b963010f0ff171bcd5bb2cd2796715 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 17:58:35 +0200 Subject: [PATCH 229/232] Add todo --- .../Framework/Features/Navigation/NavigationMenuGenerator.php | 1 + 1 file changed, 1 insertion(+) diff --git a/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php b/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php index 94976bcff51..02467e4c986 100644 --- a/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php +++ b/packages/framework/src/Framework/Features/Navigation/NavigationMenuGenerator.php @@ -194,6 +194,7 @@ protected function normalizeGroupLabel(string $label): string protected function searchForGroupLabelInConfig(string $groupKey): ?string { + // TODO: Normalize this: sidebar_group_labels -> docs.sidebar.labels return $this->getConfigArray($this->generatesSidebar ? 'docs.sidebar_group_labels' : 'hyde.navigation.labels')[$groupKey] ?? null; } From 3cbc864bae54f28e5bf33f43e2eb98757e31013b Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 18:13:08 +0200 Subject: [PATCH 230/232] Update RELEASE_NOTES.md --- RELEASE_NOTES.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index 998c920ef11..ac9d8bce2e2 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -15,6 +15,9 @@ This serves two purposes: - Added a new `\Hyde\Framework\Exceptions\ParseException` exception class to handle parsing exceptions in data collection files in https://github.com/hydephp/develop/pull/1732 - Added a new `\Hyde\Framework\Exceptions\InvalidConfigurationException` exception class to handle invalid configuration exceptions in https://github.com/hydephp/develop/pull/1799 - The `\Hyde\Facades\Features` class is no longer marked as internal, and is now thus part of the public API. +- Added support for setting custom navigation items in the YAML configuration in https://github.com/hydephp/develop/pull/1818 +- Added support for setting extra attributes for navigation items in https://github.com/hydephp/develop/pull/1824 +- Introduced a new navigation config builder class to simplify navigation configuration in https://github.com/hydephp/develop/pull/1827 ### 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. @@ -23,6 +26,8 @@ This serves two purposes: - **Breaking:** The `hyde.authors` config setting should now be keyed by the usernames. For more information, see below. - **Breaking:** The `Author::create()` method now returns an array instead of a `PostAuthor` instance. For more information, see below. - **Breaking:** The `Author::get()` method now returns `null` if an author is not found, rather than creating a new instance. For more information, see below. +- **Breaking:** The custom navigation item configuration now uses array inputs instead of the previous format. For more information, see the upgrade guide below. +- **Breaking:** Renamed the `hyde.navigation.subdirectories` configuration option to `hyde.navigation.subdirectory_display`. - Medium: The `route` function will now throw a `RouteNotFoundException` if the route does not exist in https://github.com/hydephp/develop/pull/1741 - 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.) From a313579797704cf18ed5f8cc9efccf2d368f1750 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 18:13:36 +0200 Subject: [PATCH 231/232] Update RELEASE_NOTES.md --- RELEASE_NOTES.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index ac9d8bce2e2..d090a09cdca 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -48,6 +48,8 @@ This serves two purposes: - Calling the `DataCollection` methods will no longer create the data collections directory in https://github.com/hydephp/develop/pull/1732 - Markdown includes are now converted to HTML using the custom HydePHP Markdown service, meaning they now support full GFM spec and custom Hyde features like colored blockquotes and code block filepath labels in https://github.com/hydephp/develop/pull/1738 - Markdown returned from includes are now trimmed of trailing whitespace and newlines in https://github.com/hydephp/develop/pull/1738 +- Reorganized and cleaned up the navigation and sidebar documentation for improved clarity. +- Moved the sidebar documentation to the documentation pages section for better organization. ### Deprecated - for soon-to-be removed features. From e2cdca688aebae71b89d08d5c9e2e3880c78cc07 Mon Sep 17 00:00:00 2001 From: Caen De Silva <caen@desilva.se> Date: Fri, 12 Jul 2024 18:15:54 +0200 Subject: [PATCH 232/232] Update RELEASE_NOTES.md --- RELEASE_NOTES.md | 75 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 75 insertions(+) diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index d090a09cdca..1bd2a7a4fcd 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -340,3 +340,78 @@ For example, an empty or malformed JSON file will now throw an exception like th In order to normalize the thrown exceptions, we now rethrow the `ParseException` from `Symfony/Yaml` as our custom `ParseException` to match the JSON and Markdown validation. Additionally, an exception will be thrown if a data file is empty, as this is unlikely to be intentional. Markdown files can have an empty body if front matter is present. + +## New features + +<!-- Editors note: Todo: Maybe move to the relevant docs... --> + +### Navigation configuration changes + +The custom navigation item configuration format has been updated to use array inputs. This change allows for more flexibility and consistency in defining navigation items. + +#### Old format: + +```php +'navigation' => [ + 'custom_items' => [ + 'Custom Item' => '/custom-page', + ], +], +``` + +#### New format: + +```php +'navigation' => [ + 'custom_items' => [ + ['label' => 'Custom Item', 'destination' => '/custom-page'], + ], +], +``` + +Additionally, the `hyde.navigation.subdirectories` configuration option has been renamed to `hyde.navigation.subdirectory_display`. Update your configuration files accordingly. + +### YAML configuration for navigation items + +You can now set custom navigation items directly in your YAML configuration files. This provides an alternative to defining them in the PHP configuration files. + +Example: + +```yaml +navigation: + custom_items: + - label: Custom Item + destination: /custom-page +``` + +### Extra attributes for navigation items + +Navigation items now support extra attributes, allowing you to add custom data or styling to your navigation elements. You can set these attributes in both PHP and YAML configurations. + +Example in PHP: + +```php +'navigation' => [ + 'custom_items' => [ + [ + 'label' => 'Custom Item', + 'destination' => '/custom-page', + 'attributes' => ['class' => 'special-link', 'target' => '_blank'], + ], + ], +], +``` + +Example in YAML: + +```yaml +navigation: + custom_items: + - label: Custom Item + destination: /custom-page + attributes: + class: special-link + target: _blank +``` + +These changes provide more flexibility and control over your site's navigation structure. Make sure to update your configuration files and any custom code that interacts with navigation items to align with these new formats and features.