update Blade.md and ites functions

Author: cklei-carly

docs/frontend/Blade.md

@@ -4,7 +4,7 @@ InspireCMS leverages Laravel's powerful Blade templating engine to create dynami
 
 ## Introduction to Blade
 
-Blade is Laravel's templating engine that combines the simplicity of plain PHP with powerful features like template inheritance, components, and directives. In InspireCMS, Blade is used to build flexible and maintainable templates for your website.
+[Blade](https://laravel.com/docs/11.x/blade) is Laravel's templating engine that combines the simplicity of plain PHP with powerful features like template inheritance, components, and directives. In InspireCMS, Blade is used to build flexible and maintainable templates for your website.
 
 ### Basic Blade Syntax
 
@@ -60,7 +60,7 @@ Access array properties:
 ```php
 @propertyArray('gallery', 'images')
 @foreach($gallery_images ?? [] as $image)
-    <img src="{{ $image->getUrl() }}" alt="{{ $image->alt_text }}">
+    <img src="{{ $image->getUrl() }}" alt="{{ $image->caption }}">
 @endforeach
 ```
 
@@ -76,36 +76,6 @@ Conditionally display content when a property has a value:
 @endif
 ```
 
-### Navigation Directives
-
-Render navigation menus:
-
-```php
-@navigationMenu('main', ['class' => 'main-nav', 'id' => 'primary-menu'])
-```
-
-Customize with a callback:
-
-```php
-@navigationMenu('main', function($items) {
-    echo '<ul class="main-nav">';
-    foreach ($items as $item) {
-        echo '<li><a href="' . $item->getUrl() . '">' . $item->getTitle() . '</a>';
-        
-        if ($item->hasChildren()) {
-            echo '<ul class="sub-menu">';
-            foreach ($item->children as $child) {
-                echo '<li><a href="' . $child->getUrl() . '">' . $child->getTitle() . '</a></li>';
-            }
-            echo '</ul>';
-        }
-        
-        echo '</li>';
-    }
-    echo '</ul>';
-})
-```
-
 ### Language and Localization Directives
 
 Display content in multiple languages:
@@ -175,13 +145,13 @@ Create custom theme components:
 Use your component:
 
 ```php
-<x-inspirecms-my-theme::alert type="warning" title="Important Notice">
+<x-dynamic-component :component="inspirecms_templates()->getComponentWithTheme('alert')" type="warning" title="Important Notice">
     This is an important message for all users.
 
     <x-slot:footer>
         <button>Dismiss</button>
     </x-slot>
-</x-inspirecms-my-theme::alert>
+</x-dynamic-component>
 ```
 
 ## Blade Layouts and Template Inheritance
@@ -370,7 +340,7 @@ Work with collections and arrays:
 
 ```php
 @propertyArray('blog', 'related_posts')
-@forelse($blog_related_posts as $post)
+@forelse($blog_related_posts ?? [] as $post)
     <div class="related-post">
         <h3><a href="{{ $post->getUrl() }}">{{ $post->getTitle() }}</a></h3>
         <p>{{ Str::limit($post->getPropertyValue('blog', 'excerpt'), 100) }}</p>
@@ -385,7 +355,7 @@ Use the `@foreach` directive with loop variable:
 ```php
 @foreach($gallery_images as $image)
     <div class="gallery-item {{ $loop->first ? 'first' : '' }} {{ $loop->last ? 'last' : '' }}">
-        <img src="{{ $image->getUrl() }}" alt="{{ $image->alt_text }}">
+        <img src="{{ $image->getUrl() }}" alt="{{ $image->caption }}">
         <span class="number">{{ $loop->iteration }}/{{ $loop->count }}</span>
     </div>
 @endforeach
@@ -418,9 +388,9 @@ class BladeServiceProvider extends ServiceProvider
         Blade::directive('contentLink', function ($expression) {
             $params = explode(',', $expression);
             $id = trim($params[0]);
-            $text = isset($params[1]) ? trim($params[1]) : 'null';
-            
-            return "<?php echo inspirecms_content_link($id, $text); ?>";
+            $locale = isset($params[1]) ? trim($params[1]) : 'null';
+
+            return "<?php echo inspirecms_content()->findByIds(ids: $id, limit: 1)?->getUrl($locale); ?>";
         });
     }
 }
@@ -431,7 +401,7 @@ Use custom directives:
 ```php
 <p>Posted on @formatDate($content->published_at)</p>
 
-<a href="@contentLink('550e8400-e29b-41d4-a716-446655440000', 'Read our about page')">
+<a href="@contentLink('550e8400-e29b-41d4-a716-446655440000', 'en')">
     <!-- Link content -->
 </a>
 ```
@@ -474,42 +444,6 @@ $cacheTtl = 60 * 24; // 24 hours in minutes
 @endcache
 ```
 
-## Testing Templates
-
-Test your Blade templates to ensure they render correctly:
-
-```php
-namespace Tests\Feature;
-
-use Tests\TestCase;
-use SolutionForest\InspireCms\Models\Content;
-
-class PageTemplateTest extends TestCase
-{
-    /** @test */
-    public function it_renders_page_template_correctly()
-    {
-        // Create a test content record
-        $content = Content::factory()->create([
-            'title' => json_encode(['en' => 'Test Page']),
-            'slug' => 'test-page',
-            'status' => 1, // Published
-        ]);
-        
-        // Add content properties
-        $content->setPropertyValue('hero', 'title', 'Test Hero Title');
-        
-        // Visit the page
-        $response = $this->get($content->getUrl());
-        
-        // Assert response and content
-        $response->assertStatus(200);
-        $response->assertSee('Test Hero Title');
-        $response->assertSee('Test Page');
-    }
-}
-```
-
 ## Common Blade Patterns in InspireCMS
 
 ### SEO Meta Tags
@@ -592,13 +526,8 @@ Implement breadcrumb navigation:
 
 ```php
 @php
-    $breadcrumbs = [];
-    $current = $content;
-    
-    while ($current) {
-        array_unshift($breadcrumbs, $current);
-        $current = $current->parent;
-    }
+    $breadcrumbs = $content->getAncestors()->toArray();
+    $breadcrumbs[] = $content;
 @endphp
 
 <nav aria-label="Breadcrumb">
@@ -698,8 +627,7 @@ $locale = app()->getLocale();
 $fallbackLocale = config('app.fallback_locale');
 
 // Get title in current language or fallback to default language
-$title = $content->getPropertyValue('hero', 'title', null, $locale) 
-    ?? $content->getPropertyValue('hero', 'title', null, $fallbackLocale) 
+$title = $content->getPropertyValue('hero', 'title', $locale, $fallbackLocale) 
     ?? 'Default Title';
 @endphp
 
@@ -850,7 +778,7 @@ Use helpers in templates:
 ```php
 <p class="post-meta">
     Published on 
-    <time datetime="{{ $content->published_at->format('Y-m-d') }}">
+    <time datetime="{{ $content->published_at?->format('Y-m-d') }}">
         {{ format_content_date($content->published_at) }}
     </time>
     &bull; {{ get_reading_time($content->getPropertyValue('blog', 'body')) }} min read

src/Base/Dtos/Concerns/HasPropertyGroup.php

@@ -0,0 +1,38 @@
+<?php
+
+namespace SolutionForest\InspireCms\Base\Dtos\Concerns;
+
+use SolutionForest\InspireCms\Dtos\Collection\PropertyGroupCollection;
+use SolutionForest\InspireCms\Dtos\PropertyDataGroupDto;
+
+trait HasPropertyGroup
+{
+    /**
+     * @var PropertyGroupCollection
+     */
+    public $propertyData;
+
+    /**
+     * Retrieves a property group by its key.
+     *
+     * @param string $key The unique identifier for the property group
+     * @return ?PropertyDataGroupDto
+     */
+    public function getPropertyGroup(string $key)
+    {
+        if (! $this->propertyData instanceof PropertyGroupCollection) {
+            $this->propertyData = PropertyGroupCollection::make($this->propertyData);
+        }
+
+        $result = $this->propertyData->get($key, null);
+        if ($result && $result instanceof PropertyGroupCollection) {
+            $result->setFallbackLocale($this->getFallbackLocale());
+        }
+        return $result;
+    }
+
+    public function hasPropertyGroup(string $key): bool
+    {
+        return $this->propertyData->has($key);
+    }
+}

src/Dtos/ContentDto.php

@@ -4,6 +4,8 @@
 
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Support\Collection as SupportCollection;
+use SolutionForest\InspireCms\Base\Dtos\Concerns\HasPropertyGroup;
+use SolutionForest\InspireCms\Collection\ContentCollection;
 use SolutionForest\InspireCms\Dtos\Collection\PropertyGroupCollection;
 use SolutionForest\InspireCms\Helpers\ContentHelper;
 use SolutionForest\InspireCms\Helpers\SeoHelper;
@@ -15,6 +17,8 @@
  */
 class ContentDto extends BaseTranslatableModelDto
 {
+    use HasPropertyGroup;
+
     /**
      * @var array<string,string>
      */
@@ -45,11 +49,6 @@ class ContentDto extends BaseTranslatableModelDto
      */
     public $propertyTypes;
 
-    /**
-     * @var PropertyGroupCollection
-     */
-    public $propertyData;
-
     /**
      * @var SupportCollection<string,SeoDto>
      */
@@ -70,6 +69,11 @@ class ContentDto extends BaseTranslatableModelDto
      */
     protected $children = null;
 
+    /**
+     * @var null|SupportCollection<ContentDto>
+     */
+    protected $ancestors = null;
+
     protected array $translatableAttributes = ['title'];
 
     /**
@@ -144,18 +148,13 @@ public function getChildren()
 
         $model = $this->getModel();
 
-        if (is_null($model)) {
-            $children = collect();
-        } elseif (! $model->relationLoaded('children')) {
-            $children = $model->children()->with(static::getNecessaryRelationships())->get() ?? collect();
-        } else {
-            $children = $model->children ?? collect();
-        }
+        $children = $model?->children ?? collect();
+        $children->map->loadMissing(static::getNecessaryRelationships());
 
         $currLocale = $this->getLocale();
-        $result = $children instanceof \SolutionForest\InspireCms\Collection\ContentCollection
+        $result = $children instanceof ContentCollection
             ? $children->toDto($currLocale)
-            : (new \SolutionForest\InspireCms\Collection\ContentCollection($children))->toDto($currLocale);
+            : ContentCollection::make($children)->toDto($currLocale);
 
         return $this->children = $result;
     }
@@ -166,6 +165,30 @@ public function getPaginatedChildren($perPage = 10, $pageName = 'page', $page =
         return $this->getChildren()->paginate($perPage, $pageName, $page);
     }
 
+    public function getParent()
+    {
+        return $this->getAncestors()->first();
+    }
+
+    public function getAncestors()
+    {
+        if ($this->ancestors != null) {
+            return $this->ancestors;
+        }
+
+        $model = $this->getModel();
+
+        $ancestors = $model->ancestors->reverse() ?? collect();
+        $ancestors->map->loadMissing(static::getNecessaryRelationships());
+
+        $currLocale = $this->getLocale();
+        $result = $ancestors instanceof ContentCollection
+            ? $ancestors->toDto($currLocale)
+            : ContentCollection::make($ancestors)->toDto($currLocale);
+
+        return $this->ancestors = $result;
+    }
+
     public function getTemplate($slug)
     {
         // todo: improve this
@@ -176,43 +199,31 @@ public function getTemplate($slug)
     }
 
     /**
-     * Retrieves the property group associated with the given key.
+     * Checks if a specific property exists for the given group and field.
      *
-     * @param  string  $key  The key identifying the property group.
-     * @return ?PropertyDataGroupDto
+     * @param string $group The property group to check
+     * @param string $field The specific field name to check within the group
+     * @return bool Returns true if the property exists, false otherwise
      */
-    public function getPropertyGroup(string $key)
+    public function hasProperty(string $group, string $field): bool
     {
-        if (! $this->propertyData instanceof PropertyGroupCollection) {
-            $this->propertyData = new PropertyGroupCollection($this->propertyData);
-        }
-
-        $target = $this->propertyData->get($key);
-        if ($target && ($locale = $this->getLocale() ?? $this->getFallbackLocale()) != null) {
-            $target->setFallbackLocale($locale);
-        }
-
-        return $target;
+        return $this->getPropertyGroup($group)?->hasProperty($field) ?? false;
     }
 
     /**
-     * Retrieve the property data associated with a specific property key.
+     * Gets the value of a specific property within a group.
      *
-     * @param  string  $key  The key of the property to retrieve data for.
-     * @return SupportCollection<string,PropertyDataDto>
+     * @param string $group The property group identifier
+     * @param string $field The field identifier within the group
+     * @param string|null $locale Optional locale code to get localized value, defaults to current locale if null
+     * @return mixed 
      */
-    public function getPropertyData(string $key)
+    public function getPropertyValue(string $group, string $field, ?string $locale = null, ?string $fallbackLocale = null)
     {
-        if (! $this->propertyData instanceof PropertyGroupCollection) {
-            $this->propertyData = new PropertyGroupCollection($this->propertyData);
-        }
-
-        $groups = clone $this->propertyData;
-        if (($locale = $this->getLocale() ?? $this->getFallbackLocale()) != null) {
-            $groups->setFallbackLocale($locale);
-        }
+        $locale ??= $this->getLocale() ?? $this->getFallbackLocale();
+        $fallbackLocale ??= $this->getFallbackLocale();
 
-        return $groups->getPropertyData($key);
+        return $this->getPropertyGroup($group)?->getPropertyData($field, $fallbackLocale)?->getValue($locale) ?? null;
     }
 
     /**

src/Dtos/PropertyDataDto.php

@@ -85,7 +85,6 @@ public static function fakeValueForPropertyType($propertyType, $availableLocales
 
     /**
      * @param  \SolutionForest\FilamentFieldGroup\FieldTypes\Configs\Contracts\FieldTypeConfig  $fieldType
-     * @param  string[]  $availableLocales
      */
     protected static function getFakeValueForBasicFieldType($fieldType)
     {