WIP datasource interface

modules/backend/formwidgets/DataTable.php

@@ -30,6 +30,18 @@ class DataTable extends FormWidgetBase
      */
     public $rowSorting = false;
 
+    /**
+     * @var boolean Flag for using the name of the field as a relation name to interact with directly on the parent model. This will make the
+     *   underlying table widget use a server datasource (`Backend\FormWidgets\Table\ModelDatasource`).
+     */
+    public $useRelation = false;
+
+    /**
+     * @var string Class of the model to use for the table records. This will make the underlying table widget use a server datasource
+     *   (`Backend\FormWidgets\Table\ModelDatasource`). This overrides the `useRelation` property if specified.
+     */
+    public $modelClass;
+
     //
     // Object properties
     //
@@ -52,6 +64,8 @@ public function init()
         $this->fillFromConfig([
             'size',
             'rowSorting',
+            'useRelation',
+            'modelClass',
         ]);
 
         $this->table = $this->makeTableWidget();
@@ -148,7 +162,12 @@ protected function makeTableWidget()
     {
         $config = $this->makeConfig((array) $this->config);
 
-        $config->dataSource = 'client';
+        if ($this->modelClass || $this->useRelation) {
+            $config->dataSource = 'Backend\FormWidgets\Table\ModelDatasource';
+        } else {
+            $config->dataSource = 'client';
+        }
+
         if (isset($this->getParentForm()->arrayName)) {
             $config->alias = studly_case(HtmlHelper::nameToId($this->getParentForm()->arrayName . '[' . $this->fieldName . ']')) . 'datatable';
             $config->fieldName = $this->getParentForm()->arrayName . '[' . $this->fieldName . ']';

modules/backend/widgets/Table.php

@@ -85,7 +85,7 @@ public function init()
         }
 
         if (!class_exists($dataSourceClass)) {
-            throw new SystemException(sprintf('The Table widget data source class "%s" is could not be found.', $dataSourceClass));
+            throw new SystemException(sprintf('The Table widget data source class "%s" could not be found.', $dataSourceClass));
         }
 
         $this->dataSource = new $dataSourceClass($this->recordsKeyFrom);

modules/backend/widgets/table/DataSource.php

@@ -0,0 +1,50 @@
+<?php
+
+namespace Backend\Widgets\Table;
+
+/**
+ * Table widget data source.
+ *
+ * A table data source provides the remote listing and management of records for the Table widget.
+ *
+ * @author Alexey Bobkov, Samuel Georges (original implementation)
+ * @author Ben Thomson <[email protected]> (interface implementation)
+ * @copyright 2023 Winter CMS
+ */
+interface DataSource
+{
+    /**
+     * Initializes records in the data source.
+     *
+     * This is called on widget initialization as a constructor for the datasource. The method doesn't replace existing
+     * records and could be called multiple times in order to fill the data source.
+     */
+    public function initRecords(array $records): void;
+
+    /**
+     * Return records from the data source.
+     *
+     * The results can be paginated using the `$offset` and `$count` parameters. This method will return an array of
+     * records to display within the table. If there are no more records, an empty array should be returned.
+     *
+     * @param int $offset Specifies the offset of the first record to return, zero-based.
+     * @param int $count Specifies the number of records to return. If 0, all records should be returned.
+     */
+    public function getRecords(int $offset = 0, int $count = 0): array;
+
+    /**
+     * Returns the total number of records in the data source.
+     */
+    public function getCount(): int;
+
+    /**
+     * Searches records in the data source.
+     *
+     * This functions similar to the `getRecords` method, except that records should be filtered using the given query.
+     *
+     * @param string $query The search query to filter records by.
+     * @param int $offset Specifies the offset of the first record to return, zero-based.
+     * @param int $count Specifies the number of records to return. If 0, all records should be returned.
+     */
+    public function searchRecords(string $query, int $offset = 0, int $count = 0): array;
+}

modules/backend/widgets/table/DataSourceBase.php

@@ -1,4 +1,6 @@
-<?php namespace Backend\Widgets\Table;
+<?php
+
+namespace Backend\Widgets\Table;
 
 /**
  * Base class for the Table widget data sources.