Merge branch '1.2' into develop

architecture/maintainer-guide.md

@@ -4,7 +4,7 @@
 
 This document immortalises the processes involved with maintaining the Winter CMS repositories. This is intended to give the maintainers of the project a clear idea as to how to review and manage the inflow of code and ensure the qualities and philosophies of Winter CMS and its first-party plugins are maintained.
 
-The Winter CMS project is the result of a fork that occurred on March 5th, 2021 after it became apparent to the maintainer group of October CMS that the original founders of October CMS had no intention of working collaboratively with the maintainer group. [The announcment of the fork](https://github.com/wintercms/winter/issues/5) goes into more details on what occurred as well as the reasoning for the fork.
+The Winter CMS project is the result of a fork that occurred on March 5th, 2021 after it became apparent to the maintainer group of October CMS that the original founders of October CMS had no intention of working collaboratively with the maintainer group. [The announcement of the fork](https://github.com/wintercms/winter/issues/5) goes into more details on what occurred as well as the reasoning for the fork.
 
 This document was originally written for October CMS, but has been repurposed for Winter CMS.
 

architecture/using-composer.md

@@ -1,3 +1,8 @@
+---
+title: "Architecture Concepts: Composer"
+description: "Documentation on using Composer within Winter CMS projects."
+---
+
 # Using Composer
 
 ## Introduction
@@ -6,54 +11,34 @@ Using [Composer](https://getcomposer.org/) as an alternative package manager to
 
 Composer is the de-facto standard for package management in the PHP ecosystem, and can handle the downloading, installation and management of Winter CMS plugins and themes, as well as third-party Laravel packages and vendor libraries.
 
-### Converting from a basic installation
-
-In order to use Composer with a Winter CMS instance that has been installed using the Wizard or simple CLI installation process, simply copy the latest [`tests/` directory](https://github.com/wintercms/winter/tree/develop/tests) and [`composer.json`](https://github.com/wintercms/winter/tree/develop/composer.json) file from [GitHub](https://github.com/wintercms/winter/tree/develop) into your Winter instance and then run `composer install` within the root directory of the project.
-
-> **NOTE:** If you have made modifications to the files within the `modules` directory, these will be overwritten by Composer if an update to those modules is installed. It is recommended that you *do not* make modifications to the modules directly.
-
-### Development branch
-
-If you plan on submitting pull requests to the Winter CMS project via GitHub, or are actively developing a project based on Winter CMS and want to stay up to date with the absolute latest version, we recommend switching your composer dependencies to point to the `develop` branch where all the latest improvements and bug fixes take place. Doing this will allow you to catch any potential issues that may be introduced (as rare as they are) right when they happen and get them fixed while you're still actively working on your project instead of only discovering them several months down the road if they eventually make it into production.
-
-```json
-"winter/storm": "dev-develop as 1.2.999",
-"winter/wn-system-module": "dev-develop as 1.2.999",
-"winter/wn-backend-module": "dev-develop as 1.2.999",
-"winter/wn-cms-module": "dev-develop as 1.2.999",
-"laravel/framework": "~9.0",
-```
-
-> **NOTE:** Do not commit the changes to `composer.json`, as this file is handled by the Winter CMS maintainers.
-
-### Deployment best practices
-
-Using the following best practices with Composer and Winter CMS will make deployment of your Winter CMS installation much smoother:
-
-- Store the `composer.lock` file in your source control. This file is ignored by Git by default in the `.gitignore` file included by Winter CMS, but should be deployed with your application to speed up the install and update process.
-- Add a `.gitignore` file inside the `modules` folder to ignore all changes within this folder, as the modules will be installed and updated by Composer.
-- Add a `.gitignore` file inside the `plugins` folder to ignore all changes within this folder if you install your plugins via Composer. You can optionally allow custom plugins that are only being used for that specific project.
-- Use `composer install --no-dev` on your production instance to specifically exclude any "development" packages and libraries that won't be used in production.
-
 ## Installing Winter via Composer
 
 Installing Winter via Composer is easy. You can use the `create-project` command through Composer to quickly set up a new Winter installation.
 
 ```bash
-composer create-project wintercms/winter <your installation directory>
+composer create-project wintercms/winter <your installation directory> [version]
 
 # Example:
 #   composer create-project wintercms/winter mywinter
+# or
+#   composer create-project wintercms/winter ./ "dev-develop"
 ```
 
-If you wish to install a specific version of Winter, you can also specify the version.
+### Configuring Winter
 
-```bash
-composer create-project wintercms/winter <your installation directory> "<version>"
+If you have used `create-project` to create your Winter project it will automatically run the following commands for you:
 
-# Example:
-#   composer create-project wintercms/winter mywinter "1.2.6"
-```
+- [`winter:install`](../console/setup-maintenance#install-winter-via-command-line) (the CLI installation wizard)
+- [`winter:env`](../console/setup-maintenance#configure-winter-through-an-environment-file) (populates the `.env` file from the configuration files)
+- [`winter:mirror public --relative`](../console/setup-maintenance#mirror-public-files) (sets up the project to use a public folder, recommended for security)
+
+You can either go through this wizard to configure your project or you can cancel with (`Ctrl+C`) and manually reviewing and make changes to the configuration files located in `config/*.php`. If you take the manual approach, note that you will also need to run `php artisan migrate` to migrate the database yourself after configuring the project.
+
+> **NOTE:** When running commands on your Winter project, make sure that you are located in the project root directory first (following the previous example you can run `cd mywinter`).
+
+### Completing installation
+
+Once the above commands have been run, refer to the [Post Installation steps](../setup/installation#post-installation-steps) on the Installation page to complete the process.
 
 ## Installing a plugin or theme using Composer
 
@@ -86,6 +71,41 @@ composer require --dev <your package name> "<version constraint>"
 #   composer require --dev winter/wn-builder-plugin "^2.0.0"
 ```
 
+After installing any packages via composer it is important to ensure that any included migrations are run and if you are [using a public folder](../setup/configuration#using-a-public-folder) that the public folder is regenerated. Use the following commands to accomplish that:
+
+```bash
+php artisan migrate && php artisan winter:mirror public --relative
+```
+
+### Missing `composer.json`?
+
+If you have created your Winter CMS project recently, using either Composer or the Web Installer, then you should have a `composer.json` present in your proejct root.
+
+If you are missing your `composer.json` file, simply copy the latest [`composer.json`](https://github.com/wintercms/winter/tree/develop/composer.json) file from [GitHub](https://github.com/wintercms/winter/tree/develop) into your Winter instance and then run `composer install` within the root directory of the project.
+
+> **NOTE:** If you have made modifications to the files within the `modules` directory, these will be overwritten by Composer if an update to those modules is installed. It is recommended that you *do not* make modifications to the modules directly.
+
+### Development branch
+
+If you plan on submitting pull requests to the Winter CMS project via GitHub, or are actively developing a project based on Winter CMS and want to stay up to date with the absolute latest version, we recommend switching your composer dependencies to point to the `develop` branch where all the latest improvements and bug fixes take place. Doing this will allow you to catch any potential issues that may be introduced (as rare as they are) right when they happen and get them fixed while you're still actively working on your project instead of only discovering them several months down the road if they eventually make it into production.
+
+```json
+"winter/storm": "dev-develop as 1.2.999",
+"winter/wn-system-module": "dev-develop as 1.2.999",
+"winter/wn-backend-module": "dev-develop as 1.2.999",
+"winter/wn-cms-module": "dev-develop as 1.2.999",
+"laravel/framework": "~9.0",
+```
+
+### Deployment best practices
+
+Using the following best practices with Composer and Winter CMS will make deployment of your Winter CMS installation much smoother:
+
+- Store the `composer.lock` file in your source control. This file is ignored by Git by default in the `.gitignore` file included by Winter CMS, but should be deployed with your application to speed up the install and update process.
+- Add a `.gitignore` file inside the `modules` folder to ignore all changes within this folder, as the modules will be installed and updated by Composer.
+- Add a `.gitignore` file inside the `plugins` folder to ignore all changes within this folder if you install your plugins via Composer. You can optionally allow custom plugins that are only being used for that specific project.
+- Use `composer install --no-dev` on your production instance to specifically exclude any "development" packages and libraries that won't be used in production.
+
 ## Publishing plugins or themes
 
 When publishing your plugins or themes to the marketplace, you may wish to also make them available via Composer. An example `composer.json` file for a plugin is included below:
@@ -135,6 +155,8 @@ There are many different moving parts that come together to make the Winter CMS
 
 - **Vendor** packages are included via Composer in either the project's `/vendor` directory or can sometimes be found in plugin-specific `/vendor` directories. The project vendor directory takes priority over and plugin vendor directories that appear in the system.
 
+> **NOTE:** Refer to the [Architecture documentation](../architecture/introduction) for more detailed information on how Winter CMS is structured.
+
 ## Marketplace builds
 
 When you publish your plugin or theme to the marketplace, the server will conveniently pull in all the packages defined in your composer file. This makes the product ready for others to use, even if they don't use composer. Here's how it works:

backend/forms.md

@@ -1070,7 +1070,7 @@ Option | Description
 
 ### Relation Manager
 
-`relationmanager` - Renders the [relation controller](../relations) for this relation. This is the equivalent of using a `partial` field that renders the output of the `relationRender()` method from the controller.
+`relationmanager` - Renders the [relation controller](relations) for this relation. This is the equivalent of using a `partial` field that renders the output of the `relationRender()` method from the controller.
 
 ```yaml
 records:

backend/reorder.md

@@ -70,7 +70,7 @@ Option | Description
 
 ## Displaying the reorder page
 
-You should provide a [view file](controllers-ajax#introduction) with the name **reorder.htm**. This view represents the Reorder page that allows users to reorder records. Since reordering includes the toolbar, the view file will consist solely of the single `reorderRender` method call.
+You should provide a [view file](controllers-ajax#introduction) with the name **reorder.php**. This view represents the Reorder page that allows users to reorder records. Since reordering includes the toolbar, the view file will consist solely of the single `reorderRender` method call.
 
 ```php
 <?= $this->reorderRender() ?>

backend/views-partials.md

@@ -41,6 +41,25 @@ If you're using hints, you may find it useful to check if the user has hidden th
 <?php endif ?>
 ```
 
+### Overriding partials
+
+The backend partial system makes use of the `System\Traits\ViewMaker` trait to function, which provides the `addViewPath()` method. This method allows you to add a view path to the list of paths that the system will look in when trying to locate a partial. This allows you to override any existing partial or even provide a new partial for a widget.
+
+You can call this method on a specific instance of any class that implements the `ViewMaker` trait, or you can make use of the dynamic class extension in Winter to add an override for a specific class globally. For example, if you wanted to override the partials for the `Backend\Widgets\Filter` widget, you could do the following:
+
+`plugins/myauthor/myplugin/controllers/Posts.php`:
+
+```php
+public function index()
+{
+    \Backend\Widgets\Filter::extend(function ($widget) {
+        $widget->addViewPath(__DIR__ . '../widgets/filter/partials');
+    });
+
+    // ...
+}
+```
+
 ## Layouts and child layouts
 
 Backend layouts reside in an optional **layouts/** directory of a plugin. A custom layout is set with the `$layout` property of the controller object. It defaults to the system layout called  `default`.

markup/tags/flash.md

@@ -1,3 +1,7 @@
+---
+title: "The 'flash' markup tag"
+description: "Render flash messages stored in the user session within your theme."
+---
 # {% flash %}
 
 The `{% flash %}` and `{% endflash %}` tags will render any flash messages stored in the user session, set by the `Flash` PHP class. The `message` variable inside will contain the flash message text and the markup inside will repeat for multiple flash messages.
@@ -10,7 +14,7 @@ The `{% flash %}` and `{% endflash %}` tags will render any flash messages store
 </ul>
 ```
 
-You can use the `type` variable that represents the flash message type &mdash; `success`, `error`, `info` or `warning`.
+You can use the `type` variable that represents the flash message type - `success`, `error`, `info` or `warning`.
 
 ```twig
 {% flash %}
@@ -28,9 +32,23 @@ You can also specify the `type`  to filter flash messages of a given type. The n
 {% endflash %}
 ```
 
+If you are using the [Snowboard Flash utility](../../snowboard/extras#flash-messages) in your theme, you should use the following code to ensure that flash messages are handled correctly by this utility:
+
+```twig
+{% flash %}
+    <p
+        data-control="flash-message"
+        class="flash-message fade"
+        data-flash-type="{{ type }}"
+        data-flash-duration="5">
+        {{ message }}
+    </p>
+{% endflash %}
+```
+
 ## Setting flash messages
 
-Flash messages can be set by [Components](../../docs/cms/components) or inside the page or layout [PHP section](../../docs/cms/themes#php-code-section) with the `Flash` class.
+Flash messages can be set by [Components](../../cms/components) or inside the page or layout [PHP section](../../cms/themes#php-code-section) with the `Flash` class.
 
 ```php
 <?php

setup/configuration.md

@@ -99,6 +99,20 @@ location ~ ^/themes/.*/assets { try_files $uri 404; }
 location ~ ^/themes/.*/resources { try_files $uri 404; }
 ```
 
+#### Resizer support when using custom Nginx config
+
+When using a custom nginx config (usually provided by managed server providers or infrastructure as a service platforms), the default configuration may included blocks for static assets to be served solely by nginx instead of passing requests where the files don't exist to the application for processing.
+
+This conflicts with the [Image Resizing](../services/image-resizing) functionality which dynamically resizes images on requests to the `/resizer/` URL with the original file extensions present. This usually presents as any images loaded from the `/resizer/` URL failing to load with a 404 in the browser.
+
+To fix this, add the following location block above any location blocks that reference image file extensions (`.png`, `.jpg`, etc):
+
+```nginx
+location /resizer/ {
+  try_files $uri /index.php?$args;
+}
+```
+
 ### Lighttpd configuration
 
 If your webserver is running Lighttpd you can use the following configuration to run Winter CMS. Open your site configuration file with your favorite editor.

setup/installation.md

@@ -4,7 +4,13 @@ description: "Documentation on the different ways to install Winter CMS for your
 ---
 # Installation
 
-There are two ways you can install Winter, either using the [Web-based installer](#web-based-installation) or [Composer installation](../architecture/using-composer) instructions. Before you proceed, you should check that your server meets the minimum system requirements.
+There are three ways you can install Winter:
+
+1. Using the [Composer package manager](../architecture/using-composer#installing-winter-via-composer) (if you are comfortable using the command line)
+2. The [Web-based installer](#web-based-installation) (most similar to the WordPress web installer)
+3. Using the [Softaculous installler](https://www.softaculous.com/apps/cms/WinterCMS) (if your hosting provider supports it).
+
+Before you proceed, check that your server meets the minimum system requirements:
 
 ## Minimum system requirements
 
@@ -36,7 +42,7 @@ When using the SQL Server database engine, you will need to install the [group c
 
 The [Web Installer](https://github.com/wintercms/web-installer) is the recommended way to install Winter for **non-technical users**. It is simpler than the command-line installation and doesn't require any special skills.
 
-> **NOTE:** If you are a developer, we recommend that you [install via Composer instead](../architecture/using-composer)
+> **NOTE:** If you are a developer, we recommend that you [install via Composer instead](../architecture/using-composer#installing-winter-via-composer)
 
 1. Prepare an empty directory on the web server that will host your Winter CMS installation. It can be a main domain, sub-domain or subfolder.
 2. [Download the "install.zip" file](https://github.com/wintercms/web-installer/releases/latest/download/install.zip) from the latest release of the Winter CMS Web Installer into this folder.