[ADD] Implementing sGallery::file().

docs/pages/getting-started.md

@@ -107,18 +107,60 @@ More examples in **Use in Blade** page
 
 [Use in Blade]({{site.baseurl}}/use-in-blade/){: .btn .btn-sky}
 
-## Integration into the products module
+## Integration into the Custom Module (e.g., in sCommerce)
+
+Integrate the sGallery package seamlessly into your project by following the examples below.
+These snippets demonstrate both basic and advanced usage, allowing you to customize the gallery
+according to your specific needs.
+
+### Basic Usage
+
+To display a simple gallery for products, insert the following code into your module's view:
 
-Just paste this code in your View backend
 ```php
-{!!sGallery::initialise('section', 'product', 'i')!!}
+{!!sGallery::initialiseView()->itemType('product')!!}
 ```
 
-Or if you want to use additional blocks
+**Explanation of Methods:**
+
+- initialiseView() - Initiates the gallery builder and prepares it for configuration.
+  This method sets up the default settings required to render the gallery.
+- itemType('product') - Specifies the type of items to display in the gallery.
+  In this case, it sets the gallery to showcase products. You can replace 'product' with any
+  other item type relevant to your application.
+
+### Advanced Usage with Additional Configuration
+
+For more customized galleries, you can chain additional methods to tailor the display according to your requirements:
+
 ```php
-{!!sGallery::initialise('section', 'ship', 'i', 'photo')!!}
+{!!sGallery::initialiseView()->viewType('section')->itemType('product')->idType('i')->blockName('photo')!!}
 ```
 
+**Explanation of Methods:**
+
+- initialiseView() - Starts the gallery configuration process, setting up necessary defaults and preparing
+  for further customization.
+- viewType('section') - Defines the layout or style of the gallery display. The 'section' view type organizes
+  the gallery items into distinct sections. Other possible values might include '**tab**', or '**sectionDownloads**'.
+- itemType('product') - Determines the category or type of items the gallery will present. Here, it specifies
+  that products will be displayed. Modify this parameter to display different item categories as needed.
+- idType('i') - Sets the identifier type for retrieving and managing gallery items. The identifier '**i**' or '**id**'
+  may correspond to a specific scheme or format on your system. Adjust this option according to the identifier
+  conventions used in your application. Remember that the '**id**' parameter is reserved for modules in Evolution CMS.
+- blockName('photo') - Assigns a specific block or group name to the gallery items. Using '**photo**' groups items
+  under this block, allowing for organized and targeted display. You can change this to other block names like
+  '**gallery**', '**portfolio**', or any custom groupings you utilize.
+
+### Notes
+
+- All methods are chainable, allowing for clean and readable configuration.
+- Ensure that the parameters passed to each method align with the definitions and expectations within
+  your application's context.
+- You can omit methods that utilize default settings if no customization is needed for those aspects.
+- Explore and utilize other available methods and parameters provided by sGallery to further enhance
+  and control your gallery's behavior and appearance.
+
 ## Extra
 
 If you write your own code that can integrate with the sGallery plugin, you can check the presence of this plugin in the system through a configuration variable.

plugins/sGalleryPlugin.php

@@ -1,6 +1,7 @@
 <?php
 
 use Seiger\sGallery\Facades\sGallery;
+use Seiger\sGallery\Models\sGalleryModel;
 
 Event::listen('evolution.OnDocFormRender', function($params) {
     $currentTemplate = $params['template'];
@@ -22,10 +23,10 @@
     if (in_array($currentTemplate, $templateIDs) && $params['id'] > 0) {
         if (is_array(is_array($templates[$currentTemplate])) && is_array($templates[$currentTemplate][$currentTemplate]) && count($templates[$currentTemplate][$currentTemplate]) > 0) {
             foreach ($templates[$currentTemplate][$currentTemplate] as $block) {
-                echo sGallery::initialiseView()->blockName($block);
+                echo sGallery::initialiseView()->viewType(sGalleryModel::VIEW_TAB)->idType('id')->blockName($block);
             }
         } else {
-            echo sGallery::initialiseView();
+            echo sGallery::initialiseView()->viewType(sGalleryModel::VIEW_TAB)->idType('id');
         }
     }
 });

src/Builders/sGalleryBuilder.php

@@ -2,7 +2,6 @@
 
 use Seiger\sGallery\Controllers\sGalleryController;
 use Seiger\sGallery\Models\sGalleryModel;
-use Illuminate\Support\Facades\View;
 
 /**
  * Class sGalleryBuilder
@@ -11,13 +10,12 @@
  */
 class sGalleryBuilder
 {
-    protected string $viewType = sGalleryModel::VIEW_TAB;
+    protected string $viewType = sGalleryModel::VIEW_SECTION;
     protected string $itemType = 'resource';
-    protected string $idType = 'id';
+    protected string $idType = 'i';
     protected string $blockName = '1';
-    protected int|null $documentId = null;
-    protected string|null $lang = null;
-    protected array $resizeParams = [];
+    protected ?string $file = null;
+    protected ?array $params = [];
 
     /**
      * Set the view type.
@@ -38,7 +36,7 @@ public function viewType(string $viewType): self
     }
 
     /**
-     * Set the resource type.
+     * Set the item type.
      *
      * @param string $itemType
      * @return self
@@ -74,27 +72,32 @@ public function blockName(string $blockName): self
     }
 
     /**
-     * Set the language.
+     * Set resize parameters.
      *
-     * @param string $lang
+     * @param int $width
+     * @param int $height
      * @return self
      */
-    public function language(string $lang): self
+    public function resize(int $width, int $height): self
     {
-        $this->lang = $lang;
+        $this->params['w'] = $width;
+        $this->params['h'] = $height;
         return $this;
     }
 
     /**
-     * Set parameters for resizing images.
+     * Get the URL of the file.
      *
-     * @param array $params
-     * @return self
+     * @param string $filePath
+     * @return string
      */
-    public function resizeParams(array $params): self
+    protected function getFileUrl(string $filePath): string
     {
-        $this->resizeParams = $params;
-        return $this;
+        if (file_exists($filePath)) {
+            return str_replace(MODX_BASE_PATH, MODX_SITE_URL, $filePath);
+        }
+
+        return sGalleryModel::NOIMAGE;
     }
 
     /**
@@ -108,18 +111,59 @@ public function initialise(): self
     }
 
     /**
-     * Render the view as a string when the object is treated like a string.
+     * Get the URL of the file.
+     *
+     * @return string
+     */
+    public function getFile(): string
+    {
+        if ($this->file !== null) {
+            return $this->getFileUrl($this->file);
+        }
+
+        return sGalleryModel::NOIMAGE;
+    }
+
+    /**
+     * Set the file path.
+     *
+     * @param string $input
+     * @return self
+     */
+    public function file(string $input): self
+    {
+        $this->file = $input;
+        return $this;
+    }
+
+    /**
+     * Get the URL of the file.
+     *
+     * @return string
+     */
+    public function getView(): string
+    {
+        $sGalleryController = new sGalleryController($this->viewType, $this->itemType, $this->idType, $this->blockName);
+        $view = $sGalleryController->index();
+
+        return $view instanceof View ? $view->render() : (string)$view;
+    }
+
+    /**
+     * Render the view or return the file path as a string when the object is treated like a string.
      *
      * @return string
      */
     public function __toString(): string
     {
         try {
-            $sGalleryController = new sGalleryController($this->viewType, $this->itemType, $this->idType, $this->blockName);
-            return $sGalleryController->index(); // Assuming this returns a View object
+            if ($this->file !== null) {
+                return $this->getFile();
+            }
+
+            return $this->getView();
         } catch (\Exception $e) {
-            // Handle any exceptions and return an error message as a string
-            return "Error initializing gallery: " . $e->getMessage();
+            return "Error sGallery: " . $e->getMessage();
         }
     }
 }

src/Models/sGalleryModel.php

@@ -8,12 +8,26 @@
  * Class sGalleryModel
  *
  * This class represents a gallery model for managing gallery data in the application.
- * It extends the base Model class.
+ *
+ * @property int $id
+ * @property string $resource_type
+ * @property string $parent
+ * @property string $file
+ * @property string $type
+ *
+ * @property-read string $path
+ * @property-read string $src
+ *
+ * @method static Builder|sGalleryModel lang(string $locale)
+ * @method static Builder|sGalleryModel newModelQuery()
+ * @method static Builder|sGalleryModel newQuery()
+ * @method static Builder|sGalleryModel query()
  */
 class sGalleryModel extends Model
 {
     const UPLOAD = MODX_BASE_PATH . "assets/sgallery/";
     const UPLOADED = MODX_SITE_URL . "assets/sgallery/";
+    const NOIMAGE = MODX_SITE_URL . "assets/site/noimage.png";
 
     const TYPE_IMAGE = "image";
     const TYPE_VIDEO = "video";
@@ -32,11 +46,13 @@ class sGalleryModel extends Model
     protected $table = 's_galleries';
 
     /**
-     * The accessors to append to the model's array form.
+     * The attributes that should be appended to the model's array form.
      *
      * @var array
      */
-    //protected $appends = ['src'];
+    protected $appends = ['src', 'path'];
+
+    private $cachedFilePath;
 
     /**
      * Get the file item fields with lang
@@ -68,14 +84,51 @@ public function scopeLang($query, $locale)
      *
      * @return string The source attribute value for the image.
      */
-    protected function getSrcAttribute()
+    protected function getSrcAttribute(): string
+    {
+        switch ($this->type) {
+            case self::TYPE_IMAGE:
+                $src = !empty($this->file) && is_file(self::UPLOAD.$this->resource_type.'/'.$this->parent.'/'.$this->file)
+                    ? self::UPLOADED.$this->resource_type.'/'.$this->parent.'/'.$this->file
+                    : self::NOIMAGE;
+                break;
+
+            case self::TYPE_VIDEO:
+                $src = self::UPLOADED.'video_placeholder.png';
+                break;
+
+            case self::TYPE_PDF:
+                $src = self::UPLOADED.'pdf_icon.png';
+                break;
+
+            default:
+                $src = self::NOIMAGE;
+                break;
+        }
+
+        return $src;
+    }
+
+    /**
+     * Get the full path to the file on the server.
+     *
+     * This method constructs the full file path on the server for the gallery item.
+     * If the file exists, it returns the full path; otherwise, it returns the path to a default "noimage.png" file.
+     *
+     * @return string The full path to the file on the server.
+     */
+    public function getPathAttribute(): string
     {
+        if ($this->cachedFilePath) {
+            return $this->cachedFilePath;
+        }
+
         if (!empty($this->file) && is_file(self::UPLOAD.$this->resource_type.'/'.$this->parent.'/'.$this->file)) {
-            $src = self::UPLOADED.$this->resource_type.'/'.$this->parent.'/'.$this->file;
+            $this->cachedFilePath = self::UPLOAD.$this->resource_type.'/'.$this->parent.'/'.$this->file;
         } else {
-            $src = self::UPLOADED.'noimage.png';
+            $this->cachedFilePath = self::UPLOAD.'noimage.png';
         }
 
-        return $src;
+        return $this->cachedFilePath;
     }
-}
+}