Merge branch 'wintercms:develop' into patch-1

backend/forms.md

@@ -393,6 +393,45 @@ status:
     showSearch: false
 ```
 
+Dropdowns can also allow users to provide a new value. This can be activated by setting the `allowCustom` option to `true`.
+
+```yaml
+status:
+    label: Blog Post Status
+    type: dropdown
+    allowCustom: true
+```
+
+The `allowCustom` option can be useful to provide a preset list of options without preventing the user from adding a new or custom value.
+
+When using the `get*Options` method for defining options, you would be able to take into consideration any custom options present in the data:
+
+```yaml
+status:
+    label: Blog Post Status
+    type: dropdown
+    allowCustom: true
+```
+
+```php
+public function getStatusOptions($value, $formData)
+{
+    // Prefill the dropdown with the already used statuses: [['status' => 'draft'], ['status' => 'published']]
+    $statuses = self::distinct('status')->get();
+
+    // Insert the actual form's model value to avoid it to vanish
+    // on eventual AJAX call that would refresh the field partial like dependsOn
+    if ($this->status) {
+
+        // The actual form's status could be a custom like ['status' => 'need review']
+        $statuses->add(['status' => $this->status]);
+    }
+
+    // Return a list of statuses: [['status' => 'draft'], ['status' => 'published'], ['status' => 'need review']]
+    return $statuses->pluck('status', 'status');
+}
+```
+
 ### Email
 
 `email` - renders a single line text box with the type of `email`, triggering an email-specialised keyboard in mobile browsers.
@@ -837,6 +876,9 @@ Option | Description
 
 > **NOTE:** Unlike the [Media Finder FormWidget](#media-finder), the File Upload FormWidget uses [database file attachments](../database/attachments); so the field name must match a valid `attachOne` or `attachMany` relationship on the Model associated with the Form. **IMPORTANT:** Having a database column with the name used by this field type (i.e. a database column with the name of an existing `attachOne` or `attachMany` relationship) **will** cause this FormWidget to break. Use database columns with the Media Finder FormWidget and file attachment relationships with the File Upload FormWidget.
 
+By default, the File Upload FormWidget only allows a limited set of file extensions. You can extend this list by adding a `fileDefinitions` config in `config/cms.php` file.  
+See [Allowed file types](../setup/configuration#allowed-file-types) for more information.
+
 ### Icon Picker
 
 `iconpicker` - renders an icon picker that is by default powered by the Font Awesome icons included by WinterCMS.

cms/mediamanager.md

@@ -241,6 +241,11 @@ Parameter | Value
 `videoExtensions` | file extensions corresponding to the Video document type. The default value is `['mp4', 'avi', 'mov', 'mpg']`.
 `audioExtensions` | file extensions corresponding to the Audio document type. The default value is `['mp3', 'wav', 'wma', 'm4a']`.
 
+### Allowing more specific file extensions
+
+By default, the Media Manager only allows a limited set of file extensions. You can extend this list by adding a `fileDefinitions` config in `config/cms.php` file.  
+See [Allowed file types](../setup/configuration#allowed-file-types) for more information.
+
 ## Events
 
 The Media Manager provides a few [events](../events/introduction) that you can listen for in order to improve extensibility.

console/asset-compilation.md

@@ -268,13 +268,15 @@ Please see the `mix:install` documentation for the available arguments and optio
 ### List registered Mix packages
 
 ```bash
-php artisan mix:list
+php artisan mix:list [--json]
 ```
 
 The `mix:list` command will list all registered Mix packages found in the Winter installation. This is useful for determining if your plugin or theme is correctly registered.
 
 The command will list all packages, as well as the directory for the asset and the configuration file that has been defined during registration.
 
+A json formatted list of packages can be printed by specifying the `--json` flag.
+
 ### Compile a Mix packages
 
 ```bash
@@ -285,6 +287,8 @@ The `mix:compile` command compiles all registered Mix packages, running each pac
 
 By specifying the `-p` flag, you can compile one or more selected packages. To define multiple packages, simply add more `-p` flags to the end of the command.
 
+The `--no-progress` flag can be added in order to suppress the mix progress output. Useful if you want to only view the webpack output.
+
 By default, all packages are built in "development" mode. If you wish to compile in "production" mode, which may include more optimisations for production sites, add the `-f` or `--production` flag to the command.
 
 The command will generate a report of all compiled files and their final size once complete.

database/model.md

@@ -4,18 +4,18 @@
 
 Winter provides a beautiful and simple Active Record implementation for working with your database, based on [Eloquent by Laravel](http://laravel.com/docs/eloquent). Each database table has a corresponding "Model" which is used to interact with that table. Models allow you to query for data in your tables, as well as insert new records into the table.
 
-Model classes reside in the **models** subdirectory of a plugin directory. An example of a model directory structure:
-
-```css
-📂 plugins
- ┗ 📂 acme
-   ┗ 📂 blog
-     ┣ 📂 models
-     ┃ ┣ 📂 user              <=== Model config directory
-     ┃ ┃ ┣ 📜 columns.yaml    <=== Model config files
-     ┃ ┃ ┗ 📜 fields.yaml     <==^
-     ┃ ┗ 📜 User.php          <=== Model class
-     ┗ 📜 Plugin.php
+Model classes reside in the `models` subdirectory of a plugin directory. An example of a model directory structure:
+
+```treeview
+plugins/
+`-- acme/
+    `-- blog/
+       |-- models/                 # Plugin models directory
+       |   |-- user/               # Model configuration directory
+       |   |   |-- columns.yaml    # Model list columns config file
+       |   |   `-- fields.yaml     # Model form fields config file
+       |   `-- User.php            # Model class
+       `-- Plugin.php
 ```
 
 The model configuration directory could contain the model's [list column](../backend/lists#defining-list-columns) and [form field](../backend/forms#defining-form-fields) definitions. The model configuration directory name matches the model class name written in lowercase.

database/relations.md

@@ -791,6 +791,8 @@ You may also specify an operator and count to further customize the query:
 $posts = Post::has('comments', '>=', 3)->get();
 ```
 
+> **NOTE**: MySQL strict mode can sometimes complain when using a `GROUP` column without a `GROUP BY` clause (in the above case, `COUNT()`). You can set the `strict` option to `false` in your database's connection configuration (i.e. `database.connections.mysql.strict`) to ignore this warning message.
+
 Nested `has` statements may also be constructed using "dot" notation. For example, you may retrieve all posts that have at least one comment and vote:
 
 ```php

markup/filters/str.md

@@ -0,0 +1,75 @@
+# Strings
+
+Winter CMS provides Twig filters for working with strings. These filters are identical to the global PHP helper functions that are documented in [Helpers > Strings](../../docs/services/helpers#strings) section.
+
+## camel
+
+The `camel` filter converts the given string to camelCase:
+
+```twig
+{{ 'test test'|camel }}
+
+{# testTest #}
+```
+
+## finish
+
+The `finish` filter adds a single instance of the given value to a string:
+
+```twig
+{{ 'test'|finish('/') }}
+
+{# test/ #}
+```
+
+## plural
+
+The `plural` filter converts a string to its plural form. This filter currently only supports the English language:
+
+```twig
+{{ 'test'|plural }}
+
+{# tests #}
+```
+
+## singular
+
+The `singular` filter converts a string to its singular form. This filter currently only supports the English language:
+
+```twig
+{{ 'letters'|singular }}
+
+{# letter #}
+```
+
+## slug
+
+The `slug` filter generates a URL friendly "slug" from the given string:
+
+```twig
+{{ 'test test'|slug }} {# test-test #}
+
+{{ 'test_test'|slug }} {# test-test #}
+
+{{ 'test test'|slug('+') }} {# test+test #}
+```
+
+## snake
+
+The `snake` filter converts the given string to snake_case:
+
+```twig
+{{ 'test test'|snake }}
+
+{# test_test #}
+```
+
+## studly
+
+The `studly` filter converts the given string to StudlyCase:
+
+```twig
+{{ 'test test'|studly }}
+
+{# TestTest #}
+```

markup/filters/time.md

@@ -0,0 +1,23 @@
+# time_since and time_tense
+
+The `time_since` and `time_tense` filters format time.
+
+## time_since
+
+Formats a human readable time difference from the value to the current time. Eg: **10 minutes ago**
+
+```twig
+{{ '2021-03-06 14:25:55'|time_since }}
+
+{{ 'February 14, 2024 14:30'|time_since }}
+```
+
+## time_tense
+
+Formats 24-hour time and the day using the grammatical tense of the current time. Eg: Today at 12:49, Yesterday at 4:00 or 18 Sep 2015 at 14:33.
+
+```twig
+{{ '2021-03-06 14:25:55'|time_tense }}
+```
+
+> **NOTE:** To format dates in Twig there is a [date filter](https://twig.symfony.com/doc/3.x/filters/date.html)

markup/filters/trans.md

@@ -4,10 +4,10 @@ description: "Documentation on the 'trans' Twig filter."
 ---
 # trans
 
-The `| trans` and `| trans_choice` filters translate the value passed in using the applications localization configuration. The localization strings can be loaded by passing the default translation of your string.
+The `| trans` and `| transchoice` filters translate the value passed in using the applications localization configuration. The localization strings can be loaded by passing the default translation of your string.
 
 ```twig
-{{ 'I love Winter CMS.' | trans }};
+{{ 'I love Winter CMS.' | trans }}
 ```
 
 or an example using a [language variable](../../docs/plugin/localization):
@@ -24,14 +24,14 @@ Replacing parameters in translation strings is possible by passing an array as t
 
 ## Pluralization
 
-The `trans_choice` function is used to process pluralized values.
+The `transchoice` function is used to process pluralized values.
 
 ```twig
-{{ 'There is one snowflake|There are many snowflakes' | trans_choice(7) }}
+{{ 'There is one snowflake|There are many snowflakes' | transchoice(7) }}
 ```
 
 The second argument can contain the parameters.
 
 ```twig
-{{ '{1} :value minute ago|[2,*] :value minutes ago' | trans_choice(5, { value: 5 }) }}
+{{ '{1} :value minute ago|[2,*] :value minutes ago' | transchoice(5, { value: 5 }) }}
 ```

markup/functions/url.md

@@ -0,0 +1,51 @@
+# url_*()
+
+## url()
+
+The `url()` function generates a fully qualified URL to the given path.
+
+```twig
+{{ url('blog') }}
+
+{#  https://site.com/blog #}
+```
+
+You can specify a variable as a function parameter:
+
+```twig
+{{ url(category.slug) }}
+
+{#  https://site.com/slug-value #}
+```
+
+In function parameters you can use concatenation:
+
+```twig
+{{ url('blog/post/' ~ post.id) }}
+
+{#  https://site.com/blog/post/123 #}
+```
+
+### Base URL
+
+You can get the base url like this:
+
+```twig
+{{ url('/') }}
+
+{#  https://site.com/ #}
+```
+
+## url_current()
+
+The `url_current()` function generates a fully qualified URL to the current path. Syntax:
+
+```twig
+{{ url_current() }}
+```
+
+An example of generating a canonical link using the `url_current()` function and the `|lower` Twig filter:
+
+```twig
+<link rel="canonical" href="{{ url_current()|lower }}" />
+```

markup/toc.yaml

@@ -42,7 +42,9 @@ sections:
             filters/page: "| page"
             filters/raw: "| raw"
             filters/resize: "| resize"
+            filters/str: "| str*"
             filters/theme: "| theme"
+            filters/time: "| time_[since|tense]"
             filters/trans: "| trans"
 
     Functions:
@@ -51,3 +53,4 @@ sections:
             functions/form: "form_*()"
             functions/html: "html()"
             functions/dump: "dump()"
+            functions/url: "url_*()"