Merge branch 'develop' into 1.2

Author: LukeTowers

architecture/maintainer-guide.md

@@ -16,6 +16,7 @@ The project is considered a flat-level of management with equal responsibility o
 - [@bennothommo](https://github.com/bennothommo) - Ben Thomson
 - [@mjauvin](https://github.com/mjauvin) - Marc Jauvin
 - [@jaxwilko](https://github.com/jaxwilko) - Jack Wilkinson
+- [@damsfx](https://github.com/damsfx) - Damien Mathieu
 
 Luke Towers has been designated the Lead Maintainer by the maintainer group, as the longest-serving maintainer of October CMS.
 

architecture/using-composer.md

@@ -185,7 +185,7 @@ Laravel packages will often provide configuration files, and they will usually c
 
 However, this can create problems with Winter's plugin oriented design, since there would now be random config files in the core `/config` directory. In order to solve this problem, it is recommended that you proxy the included package's configuration through your plugin instead.
 
-You may place this code in your Plugin registration file and call it from the  the `boot()` method.
+You may place this code in your Plugin registration file and call it from the `boot()` method.
 
 ```php
 public function bootPackages()

backend/controllers-ajax.md

@@ -4,7 +4,7 @@
 
 The Winter CMS backend implements the MVC pattern. Controllers manage backend pages and implement various features like forms and lists. This article describes how to develop backend controllers and how to configure controller behaviors.
 
-Each controller consists of a PHP file which resides in the the **/controllers** subdirectory of a Plugin directory. Controller views are `.php` files that reside in the controller view directory. The controller view directory name matches the controller class name written in lowercase. The view directory can also contain controller configuration files. An example of a controller directory structure:
+Each controller consists of a PHP file which resides in the **/controllers** subdirectory of a Plugin directory. Controller views are `.php` files that reside in the controller view directory. The controller view directory name matches the controller class name written in lowercase. The view directory can also contain controller configuration files. An example of a controller directory structure:
 
 ```treeview
 plugins/
@@ -44,7 +44,7 @@ The backend controller base class defines a number of properties that allow to c
 Property | Description
 ------------- | -------------
 `$fatalError` | allows to store a fatal exception generated in an action method in order to display it in the view.
-`$user` | contains a reference to the the backend user object.
+`$user` | contains a reference to the backend user object.
 `$suppressView` | allows to prevent the view display. Can be updated in the action method or in the controller constructor.
 `$params` | an array of the routed parameters.
 `$action` | a name of the action method being executed in the current request.

backend/forms.md

@@ -282,8 +282,10 @@ There are various native field types that can be used for the **type** setting.
 - [Range](#range)
 - [Section](#section)
 - [Switch](#switch)
+- [Tel](#tel)
 - [Text](#text)
 - [Textarea](#textarea)
+- [URL](#url)
 - [Widget](#widget)
 
 </div>
@@ -681,6 +683,34 @@ show_content:
     off: myauthor.myplugin::lang.models.mymodel.show_content.off
 ```
 
+### Tel
+
+`tel` – renders a single-line input for phone values with built-in browser validation.
+
+```yaml
+telephone:
+    label: Phone number
+    type: tel
+    pattern: "[0-9]{3}-[0-9]{3}-[0-9]{4}"
+    placeholder: xxx-xxx-xxxx
+    maxlength: 20
+    minlength: 12
+    size: 20
+    required: true
+    options:
+        514-123-4567: First Test Phone Number
+        800-111-2222: Second Test Phone Number
+```
+
+- Displays a phone icon on the left in both edit and preview modes.
+- In preview mode, renders as a clickable link that opens a phone dialing screen on mobile.
+- Supports all standard HTML5 attributes for `<input type="tel">`:
+    - `placeholder`, `maxlength`, `minlength`, `pattern`, `size`, `list`, `autocomplete`, `required`, `readonly`, `disabled`
+- `options` will be rendered in a `<datalist>` element, enabling autocomplete suggestions.
+- If an option's value and label are identical, the label is omitted for brevity.
+
+See [Defining field options](#defining-field-options) for the different methods to specify the options.
+
 ### Text
 
 `text` - renders a single line text box. This is the default type used if none is specified.
@@ -1816,7 +1846,7 @@ Sometimes you may wish to modify the default form behavior and there are several
 
 Several controller methods can called at various points during the lifecycle of the `FormController` to provide injection points for custom logic. See the [API docs](/docs/v1.2/api/Backend/Behaviors/FormController#method-formbeforesave) for a full reference of what they are. Generally speaking any method in the API docs prefixed with `form` can be overridden in your controller to change the default behaviour or act as an injection point for custom logic.
 
-> **NOTE:** It may be more desirable to use [model events](/docs/v1.2/api/events/model/beforeSave) to implement your logic instead as those are always run when applicable if the model is being affected, no matter where the interaction with the model is occuring.
+> **NOTE:** It may be more desirable to use [model events](/docs/v1.2/api/events/model/beforeSave) to implement your logic instead as those are always run when applicable if the model is being affected, no matter where the interaction with the model is occurring.
 
 ### Overriding controller action
 

backend/lists.md

@@ -76,6 +76,21 @@ Option | Description
 `showTotals` | displays the summed values for the columns in the form of `totalOnPage (totalForQuery)` in the list header and footer. Default: `true`.
 `treeExpanded` | if tree nodes should be expanded by default. Default: `false`.
 `customViewPath` | specify a custom view path to override partials used by the list, optional.
+`sortable` | enables drag-and-drop reordering of records directly in the list, see [reordering records](#reordering-records). Default: `false`.
+
+### Reordering records
+
+Set `sortable` to `true` to let backend users reorder the list with drag-and-drop. The list model must use the [`Sortable` trait](../database/traits#sortable) so it has a `sort_order` column.
+
+```yaml
+sortable: true
+```
+
+When enabled, a drag handle is shown on each row, column header sorting is disabled, the list is shown in its stored order without pagination, and dropping a row persists the new order to the model's sort order column via AJAX.
+
+Because the whole list must be visible in a single fixed order, `sortable` cannot be combined with searching, filtering, pagination, or a custom `defaultSort` — configuring any of these alongside it raises a configuration error.
+
+> **NOTE:** Reordering applies to flat lists. For reordering tree structures, or for a dedicated standalone reordering page, use the [Reorder behavior](reorder).
 
 ### Adding a toolbar
 

backend/relations.md

@@ -114,6 +114,7 @@ Option | Type | Description
 `recordUrl` | List | link each list record to another page. Eg: **users/update/:id**. The `:id` part is replaced with the record identifier.
 `customViewPath` | List | specify a custom view path to override partials used by the list.
 `recordOnClick` | List | custom JavaScript code to execute when clicking on a record.
+`sortable` | List | enables drag-and-drop reordering of the related records, see [reordering relations](#reordering-relations). Requires the parent model to use the [`HasSortableRelations` trait](../database/traits#hassortablerelations). Default: `false`.
 `toolbarPartial` | Both | a reference to a controller partial file with the toolbar buttons. Eg: **_relation_toolbar.htm**. This option overrides the *toolbarButtons* option.
 `toolbarButtons` | Both | the set of buttons to display. This can be formatted as an array or a pipe separated string, or set to `false` to show no buttons. Available options are: `create`, `update`, `delete`, `add`, `remove`, `refresh`, `link`, & `unlink`. Example: `add\|remove`. <br/> Additionally, you can customize the text inside these buttons by setting this property to an associative array, with the key being the button type and the value being the text for that button. Example: `create: 'Assign User'`. The value also supports translation.
 
@@ -289,6 +290,23 @@ phone:
         list: $/acme/user/models/phone/columns.yaml
 ```
 
+### Reordering relations
+
+Pivot-based relations (`belongsToMany`, `morphToMany`, `morphedByMany`) can be reordered with drag-and-drop directly in the relation manager. The parent model must use the [`HasSortableRelations` trait](../database/traits#hassortablerelations) and declare the relation in its `$sortableRelations` property, and the pivot table must have a sort order column. Then set `sortable: true` on the relation's `view` configuration:
+
+```yaml
+authors:
+    label: Author
+    view:
+        list: $/acme/blog/models/author/columns.yaml
+        toolbarButtons: link|unlink
+        sortable: true
+```
+
+A drag handle is shown on each related record; dropping persists the new order to the pivot's sort order column. Reordering also works while the parent record is being created, before it is saved — the order is stored against the [deferred binding](../database/relations#deferred-binding) and committed together with the record.
+
+As with sortable lists, the related records are shown as a single unpaginated set in their stored order, so `sortable` cannot be combined with searching, filtering, pagination, or a custom `defaultSort` on the relation's `view` configuration.
+
 ## Displaying a relation manager
 
 Before relations can be managed on any page, the target model must first be initialized in the controller by calling the `initRelation` method.

backend/reorder.md

@@ -4,6 +4,8 @@
 
 The **Reorder behavior** is a controller [behavior](../services/behaviors) that provides features for sorting and reordering database records. The behavior provides a page called Reorder using the controller action `reorder`. This page displays a list of records with a drag handle allowing them to be sorted and in some cases restructured.
 
+> **NOTE:** To let users reorder records inline with drag-and-drop without a dedicated page — directly in a [list](lists#reordering-records) or a [relation manager](relations#reordering-relations) — see those sections. The Reorder behavior documented here provides a dedicated standalone page, which is best suited to models with deep tree structures.
+
 The behavior depends on a [model class](../database/model) which must implement one of the following [model traits](../database/traits):
 
 1. [`Winter\Storm\Database\Traits\Sortable`](../database/traits#sortable)

database/traits.md

@@ -838,16 +838,49 @@ class ApiData extends Model
 
 ## HasSortableRelations
 
-Add this trait to your model in order to allow its relations to be sorted/reordered.
+Sorted relations store a sort order value in the pivot table of a `belongsToMany`, `morphToMany`, or `morphedByMany` relation, so the related records keep a custom order for each parent record. Apply the `Winter\Storm\Database\Traits\HasSortableRelations` trait and define a `$sortableRelations` property that maps each relation name to its pivot sort order column.
 
 ```php
-class MyModel extends model
+class Article extends \Winter\Storm\Database\Model
 {
     use \Winter\Storm\Database\Traits\HasSortableRelations;
 
     /**
-     * @var array Relations that can be sorted/reordered and the column name to use for sorting/reordering.
+     * @var array Relations that can be reordered and the pivot column used for sorting.
      */
-    public $sortableRelations = ['relation_name' => 'sort_order_column'];
-...
+    public $sortableRelations = ['authors' => 'sort_order'];
+
+    public $belongsToMany = [
+        'authors' => [
+            \Acme\Blog\Models\Author::class,
+            'table' => 'acme_blog_articles_authors',
+        ],
+    ];
 }
+```
+
+Ensure the pivot table has the sort order column, for example in a migration:
+
+```php
+$table->integer('sort_order')->default(0);
+```
+
+You must create the column yourself (as in the migration above) — the trait does not create it. When the model boots, the trait includes that column in the relation's pivot data, so its value is loaded onto each record's `pivot`, and applies an `order by {pivot_table}.{column} asc` clause so the relation is always returned in its stored order. The trait also assigns the next sort order value to newly attached records, appending them to the end of the relation.
+
+Use the `setRelationOrder` method to reorder a relation programmatically. The second argument is the related record ids in their new order; the optional third argument provides the sort order value to assign to each (when omitted, a sequential `1..N` order is assigned in the given order):
+
+```php
+// Reorder by ids only — assigns sort orders 1, 2, 3 in the given order
+$article->setRelationOrder('authors', [$author3->id, $author1->id, $author2->id]);
+
+// Reorder by ids (second argument) with explicit sort order values (third argument)
+$article->setRelationOrder('authors', [$author1->id, $author2->id, $author3->id], [3, 2, 1]);
+```
+
+You can check whether a relation is configured as sortable with `isSortableRelation`:
+
+```php
+$article->isSortableRelation('authors'); // true
+```
+
+> **NOTE:** To let backend users reorder a relation with drag-and-drop directly in a form, see [reordering relations](../backend/relations#reordering-relations) in the RelationController documentation.

snowboard/extras.md

@@ -413,7 +413,7 @@ class Gallery extends Snowboard.PluginBase {
 }
 ```
 
-In the example above, even if the gallery element defines a `data-num-images` data attribute, this will be overriden by the `userNumImages` parameter that is used in constructing the gallery. This `userNumImages` parameter could be populated by a user configuration source.
+In the example above, even if the gallery element defines a `data-num-images` data attribute, this will be overridden by the `userNumImages` parameter that is used in constructing the gallery. This `userNumImages` parameter could be populated by a user configuration source.
 
 ### Methods
 
@@ -429,7 +429,7 @@ this.config.get(); // Returns an object of all configuration options and their v
 
 #### `get(configName: string)`
 
-Gets the configuration value for the given configuration name. This will be retrieved from the local configuration first, then the data attribute of the element providing the configuration then finally from the the defaults if not specified on the element.
+Gets the configuration value for the given configuration name. This will be retrieved from the local configuration first, then the data attribute of the element providing the configuration then finally from the defaults if not specified on the element.
 
 If the configuration has been provided a local configuration value for the config name, it will be returned over all other sources.
 

snowboard/request.md

@@ -71,7 +71,7 @@ Finally, the following option parameters define override functionality for vario
 Option | Parameters | Description
 ------ | ---------- | -----------
 `handleConfirmMessage` | `(string) confirmationMessage` | Handles any confirmations requested of the user.
-`handleErrorMessage` | `(string) errorMessage` | Handles any errors occuring during the request
+`handleErrorMessage` | `(string) errorMessage` | Handles any errors occurring during the request
 `handleValidationMessage` | `(string) message, (Object) fieldMessages` | Handles validation errors occurring during the request. `fieldMessages` has field names as the key and messages as the value.
 `handleFlashMessage` | `(string) message, (string) type` | Handles flash messages.
 `handleRedirectResponse` | `(string) redirectUrl` | Handles redirect responses.