Merge pull request #704 from code16/refactor-breadcrumb

Refactor breadcrumb + "Query parent shows label" feature

Author: aguingand

docs/guide/sharp-breadcrumb.md

@@ -2,22 +2,6 @@
 
 Under the hood Sharp manages a breadcrumb to keep track of stacked pages.
 
-## Display the breadcrumb
-
-You can activate the breadcrumb display in sharp's configuration: 
-
-```php
-class SharpServiceProvider extends SharpAppServiceProvider
-{
-    protected function configureSharp(SharpConfigBuilder $config): void
-    {
-        $config
-            ->displayBreadcrumb()
-            // [...]
-    }
-}
-```
-
 ## Configure entity label
 
 In Entity classes, you can define how an entity should be labeled in the breadcrumb with the `label` attribute:
@@ -74,6 +58,72 @@ class PostShow extends \Code16\Sharp\Show\SharpShow
 In the Form, the breadcrumb label is only used in one particular case: when coming from an embedded Entity List inside a Show Page. In this case, the Show Page and the Form entity are different, and the breadcrumb helps to keep track of the current edited entity.
 :::
 
+## Configure custom labels cache
+
+Breadcrumb labels are cached for 30 minutes to reduce DB queries between each navigation. If you don't want to cache them, which means all `SharpShow` in breadcrumb are loaded on every navigation, you can update the config in the SharpServiceProvider:
+
+```php
+class SharpServiceProvider extends SharpAppServiceProvider
+{
+    protected function configureSharp(SharpConfigBuilder $config): void
+    {
+        $config
+            ->configureBreadcrumbLabelsCache(false)
+            // ...
+    }
+}
+```
+
+Alternatively, you can change the cache duration (default is 30 minutes):
+
+```php
+class SharpServiceProvider extends SharpAppServiceProvider
+{
+    protected function configureSharp(SharpConfigBuilder $config): void
+    {
+        $config
+            ->configureBreadcrumbLabelsCache(duration: 10)
+            // ...
+    }
+}
+```
+
+### Lazy loading
+
+In some cases, having the labels replaced by the default Entity label is acceptable and you want to have less DB queries, you can activate the lazy loading:
+
+```php
+class SharpServiceProvider extends SharpAppServiceProvider
+{
+    protected function configureSharp(SharpConfigBuilder $config): void
+    {
+        $config
+            ->enableBreadcrumbLabelsLazyLoading()
+    }
+}
+```
+::: warning
+Be aware that the user may see the breadcrumb with default entity labels (e.g. "Posts > Post > Category > Edit")  when :
+- a nested page is accessed directly (e.g. direct link)
+- cached labels are expired
+:::
+
+## Hide the breadcrumb
+
+If you don't want any breadcrumb, you can hide it in sharp's configuration:
+
+```php
+class SharpServiceProvider extends SharpAppServiceProvider
+{
+    protected function configureSharp(SharpConfigBuilder $config): void
+    {
+        $config
+            ->displayBreadcrumb(false)
+            // [...]
+    }
+}
+```
+
 ## Interact with Sharp's Breadcrumb
 
-Refer to [the Context documentation](context.md) to find out how to interact with Sharp's breadcrumb.
+Refer to [the Context documentation](context.md) to find out how to interact with Sharp's breadcrumb.

resources/js/Pages/Dashboard/Dashboard.vue

@@ -56,7 +56,7 @@
         <Title :entity-key="dashboardKey" />
 
         <template #breadcrumb>
-            <template v-if="config('sharp.display_breadcrumb')">
+            <template v-if="config('sharp.breadcrumb.display')">
                 <PageBreadcrumb :breadcrumb="breadcrumb" />
             </template>
         </template>

resources/js/Pages/Form/Form.vue

@@ -77,7 +77,7 @@
         <Title :breadcrumb="breadcrumb" />
 
         <template #breadcrumb>
-            <template v-if="config('sharp.display_breadcrumb')">
+            <template v-if="config('sharp.breadcrumb.display')">
                 <PageBreadcrumb :breadcrumb="breadcrumb" />
             </template>
         </template>

resources/js/Pages/Show/Show.vue

@@ -128,7 +128,7 @@
         <Title :breadcrumb="breadcrumb" />
 
         <template #breadcrumb>
-            <template v-if="config('sharp.display_breadcrumb')">
+            <template v-if="config('sharp.breadcrumb.display')">
                 <PageBreadcrumb :breadcrumb="breadcrumb" />
             </template>
         </template>

src/Config/SharpConfigBuilder.php

@@ -33,7 +33,14 @@ class SharpConfigBuilder
         'name' => 'Sharp',
         'custom_url_segment' => 'sharp',
         'display_sharp_version_in_title' => true,
-        'display_breadcrumb' => true,
+        'breadcrumb' => [
+            'display' => true,
+            'labels' => [
+                'lazy_loading' => false,
+                'cache' => true,
+                'cache_duration' => 30,
+            ],
+        ],
         'entities' => [],
         'entity_resolver' => null,
         'global_filters' => [],
@@ -132,7 +139,22 @@ public function displaySharpVersionInTitle(bool $displaySharpVersionInTitle = tr
 
     public function displayBreadcrumb(bool $displayBreadcrumb = true): self
     {
-        $this->config['display_breadcrumb'] = $displayBreadcrumb;
+        $this->config['breadcrumb']['display'] = $displayBreadcrumb;
+
+        return $this;
+    }
+
+    public function enableBreadcrumbLabelsLazyLoading(bool $lazyLoading = true): self
+    {
+        $this->config['breadcrumb']['labels']['lazy_loading'] = $lazyLoading;
+
+        return $this;
+    }
+
+    public function configureBreadcrumbLabelsCache(bool $cache = true, int $duration = 30): self
+    {
+        $this->config['breadcrumb']['labels']['cache'] = $cache;
+        $this->config['breadcrumb']['labels']['cache_duration'] = $duration;
 
         return $this;
     }

src/Config/SharpLegacyConfigBuilder.php

@@ -41,6 +41,10 @@ public function get(string $key): mixed
             return null;
         }
 
+        if ($key == 'breadcrumb.display') {
+            return config('sharp.display_breadcrumb', true);
+        }
+
         return config('sharp.'.$key);
     }
 }

src/Data/BreadcrumbItemData.php

@@ -8,7 +8,6 @@
 final class BreadcrumbItemData extends Data
 {
     public function __construct(
-        public string $type,
         public string $label,
         public ?string $documentTitleLabel,
         public string $entityKey,