Merge pull request #225 from hydephp/add-a-link-component

Add a link component to resolve routes automatically

Author: caendesilva

docs/architecture-concepts.md

@@ -92,3 +92,54 @@ author:
 
 Lorem ipsum dolor sit amet, etc.
 ```
+
+
+## Automatic Routing
+
+>info This covers an intermediate topic which is not required for basic usage, but is useful if you want to use the framework to design custom Blade templates.
+
+### High-level overview
+
+If you've ever worked in a MVC framework, you are probably familiar with the concept of routing. And you are probably also familiar with how boring and tedious it can be. Hyde takes the pain out of routing through the Hyde Autodiscovery process.
+
+Internally, when booting the Hyde application, Hyde will automatically discover all of the content files in the source directory and create a routing index for them. This index works as a two-way link between source files and compiled files.
+
+Don't worry if this sounds complex, as the key takeaway is that the index is created and maintained automatically. There is currently no way to manually add or remove files from the index. Making it function more like a source map than a proper router. Nevertheless, the routing system provides several helpers that you can optionally use in your Blade views to automatically resolve relative links and other useful features.
+
+### Accessing routes
+
+Each route in your site is represented by a Route object. It's very easy to get a Route object instance from the Router's index. There are a few ways to do this, but most commonly you'll use the Route facade's `get()` method where you provide a route key, and it will return the Route object. The route key is generally `<output-directory/slug>`. Here are some examples:
+
+```php
+// Source file: _pages/index.md/index.blade.php
+// Compiled file: _site/index.html
+Route::get('index') 
+
+// Source file: _posts/my-post.md
+// Compiled file: _site/posts/my-post.html
+Route::get('posts.my-post')
+
+// Source file: _docs/readme.md
+// Compiled file: _site/docs/readme.html
+Route::get('docs.readme')
+```
+
+### Using the `x-link` component
+
+When designing Blade layouts it can be useful to use the `x-link` component to automatically resolve relative links.
+
+You can of course, use it just like a normal anchor tag like so:
+```blade
+<x-link href="index.html">Home</x-link>
+```
+
+But where it really shines is when you supply a route. This will then resolve the proper relative link, and format it to use pretty URLs if your site is configured to use them.
+
+```blade
+<x-link href="Route::get('index')">Home</x-link>
+```
+
+You can of course, also supply extra attributes like classes:
+```blade
+<x-link href="Route::get('index')" class="btn btn-primary">Home</x-link>
+```

packages/framework/resources/views/components/link.blade.php

@@ -0,0 +1 @@
+<a {{ $attributes->merge(['href' => $href]) }}>{!! $slot !!}</a>

packages/framework/src/HydeServiceProvider.php

@@ -9,6 +9,8 @@
 use Hyde\Framework\Models\Pages\MarkdownPage;
 use Hyde\Framework\Models\Pages\MarkdownPost;
 use Hyde\Framework\Services\AssetService;
+use Hyde\Framework\Views\Components\LinkComponent;
+use Illuminate\Support\Facades\Blade;
 use Illuminate\Support\ServiceProvider;
 
 /**
@@ -79,6 +81,8 @@ public function boot(): void
         $this->publishes([
             Hyde::vendorPath('resources/views/homepages/welcome.blade.php') => Hyde::path('_pages/index.blade.php'),
         ], 'hyde-welcome-page');
+
+        Blade::component('link', LinkComponent::class);
     }
 
     /**

packages/framework/src/Views/Components/LinkComponent.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace Hyde\Framework\Views\Components;
+
+use Hyde\Framework\Hyde;
+use Illuminate\Support\Facades\View;
+use Illuminate\View\Component;
+
+class LinkComponent extends Component
+{
+    public string $href;
+
+    public function __construct(string $href)
+    {
+        $this->href = Hyde::relativeLink($href, View::shared('currentPage') ?? '');
+    }
+
+    public function render(): \Illuminate\Contracts\View\View
+    {
+        return view('hyde::components.link');
+    }
+}

packages/framework/tests/Unit/Views/Components/LinkComponentTest.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace Hyde\Framework\Testing\Unit\Views\Components;
+
+use Hyde\Testing\TestCase;
+use Illuminate\Support\Facades\Blade;
+use Illuminate\Support\Facades\View;
+
+/**
+ * @covers \Hyde\Framework\Views\Components\LinkComponent
+ */
+class LinkComponentTest extends TestCase
+{
+    public function test_link_component_can_be_rendered()
+    {
+        $this->assertEquals('<a href="foo">bar</a>', rtrim(Blade::render('<x-link href="foo">bar</x-link>')));
+    }
+
+    public function test_link_component_can_be_rendered_with_route()
+    {
+        $route = \Hyde\Framework\Facades\Route::get('index');
+        $this->assertEquals('<a href="index.html">bar</a>', rtrim(
+            Blade::render('<x-link href="'.$route.'">bar</x-link>')));
+    }
+
+    public function test_link_component_can_be_rendered_with_route_for_nested_pages()
+    {
+        View::share('currentPage', 'foo/bar');
+        $route = \Hyde\Framework\Facades\Route::get('index');
+        $this->assertEquals('<a href="../index.html">bar</a>', rtrim(
+            Blade::render('<x-link href="'.$route.'">bar</x-link>')));
+    }
+}