From a8b51d19c79fb8131f64b083e2acb7fd535256ab Mon Sep 17 00:00:00 2001 From: Luke Towers Date: Wed, 31 Jul 2024 15:50:04 -0600 Subject: [PATCH 01/10] Remove outdated instructions on converting non-composer installs. --- architecture/using-composer.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/architecture/using-composer.md b/architecture/using-composer.md index 1271b142..3af50760 100644 --- a/architecture/using-composer.md +++ b/architecture/using-composer.md @@ -6,9 +6,11 @@ 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 +### Missing `composer.json`? -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. +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. From 424a2239b6bf54c42ac7b7fe495a9fb00337ec35 Mon Sep 17 00:00:00 2001 From: Luke Towers Date: Fri, 2 Aug 2024 22:51:11 -0600 Subject: [PATCH 02/10] Improvements --- setup/installation.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/setup/installation.md b/setup/installation.md index 83b73923..4abbc64c 100644 --- a/setup/installation.md +++ b/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 From bc484033b90ac7cb29c5a6eec1795c1f6e0e73e7 Mon Sep 17 00:00:00 2001 From: Luke Towers Date: Fri, 2 Aug 2024 23:32:52 -0600 Subject: [PATCH 03/10] Tweaks Documents partial overrides in the backend, closes #195 --- architecture/maintainer-guide.md | 2 +- backend/views-partials.md | 18 ++++++++++++++++++ setup/installation.md | 2 +- 3 files changed, 20 insertions(+), 2 deletions(-) diff --git a/architecture/maintainer-guide.md b/architecture/maintainer-guide.md index 325e7041..b273edbb 100644 --- a/architecture/maintainer-guide.md +++ b/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. diff --git a/backend/views-partials.md b/backend/views-partials.md index 71ecd732..c8e942b9 100644 --- a/backend/views-partials.md +++ b/backend/views-partials.md @@ -41,6 +41,24 @@ If you're using hints, you may find it useful to check if the user has hidden th ``` +### 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`. diff --git a/setup/installation.md b/setup/installation.md index 4abbc64c..c509368d 100644 --- a/setup/installation.md +++ b/setup/installation.md @@ -42,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. From 2b703cb316f04807126eae8ed427a31c84431507 Mon Sep 17 00:00:00 2001 From: Luke Towers Date: Tue, 6 Aug 2024 13:56:05 -0600 Subject: [PATCH 04/10] Add note about image resizer and nginx --- setup/configuration.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/setup/configuration.md b/setup/configuration.md index 5001e9eb..3265f862 100644 --- a/setup/configuration.md +++ b/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. From a5cf85174f2c1d628865e1f40d6c061eb3352495 Mon Sep 17 00:00:00 2001 From: Luke Towers Date: Tue, 6 Aug 2024 14:13:34 -0600 Subject: [PATCH 05/10] linting --- setup/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/setup/configuration.md b/setup/configuration.md index 3265f862..89e2aae1 100644 --- a/setup/configuration.md +++ b/setup/configuration.md @@ -103,7 +103,7 @@ location ~ ^/themes/.*/resources { try_files $uri 404; } 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. +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): From ab5a2a361dcdaa4971e0b864bf298f5d4fdee507 Mon Sep 17 00:00:00 2001 From: Luke Towers Date: Tue, 6 Aug 2024 14:14:09 -0600 Subject: [PATCH 06/10] linting --- backend/views-partials.md | 1 + 1 file changed, 1 insertion(+) diff --git a/backend/views-partials.md b/backend/views-partials.md index c8e942b9..89ff0495 100644 --- a/backend/views-partials.md +++ b/backend/views-partials.md @@ -48,6 +48,7 @@ The backend partial system makes use of the `System\Traits\ViewMaker` trait to f 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() { From dd1ff3ee0e2c306101b69509eb4c20815f945a3c Mon Sep 17 00:00:00 2001 From: WebVPF <61043464+WebVPF@users.noreply.github.com> Date: Sun, 25 Aug 2024 13:39:02 +0300 Subject: [PATCH 07/10] Update reorder.md (#204) --- backend/reorder.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/backend/reorder.md b/backend/reorder.md index 7f749b2b..7921f099 100644 --- a/backend/reorder.md +++ b/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 reorderRender() ?> From f686a13d4823c90e6fc86117ea4fd772283c9405 Mon Sep 17 00:00:00 2001 From: AIC BV <89913092+AIC-BV@users.noreply.github.com> Date: Mon, 26 Aug 2024 16:49:55 +0200 Subject: [PATCH 08/10] [fix] relation controller link (#206) Co-authored-by: Luke Towers --- backend/forms.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/backend/forms.md b/backend/forms.md index 94adf23a..8849d8e7 100644 --- a/backend/forms.md +++ b/backend/forms.md @@ -1028,7 +1028,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: From b65017620b33a8a9c1dc3c87a1f0505e14e94ef7 Mon Sep 17 00:00:00 2001 From: Luke Towers Date: Mon, 14 Oct 2024 23:45:00 -0600 Subject: [PATCH 09/10] Improve composer installation instructions --- architecture/using-composer.md | 96 ++++++++++++++++++++-------------- 1 file changed, 58 insertions(+), 38 deletions(-) diff --git a/architecture/using-composer.md b/architecture/using-composer.md index 3af50760..acb5032f 100644 --- a/architecture/using-composer.md +++ b/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,56 +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. -### 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", -``` - -> **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 +composer create-project wintercms/winter [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 "" +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.0.474" -``` +- [`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 @@ -88,6 +71,41 @@ composer require --dev "" # 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: @@ -137,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: From bdc7738d417bf2736d56474f94037462b5dd29b8 Mon Sep 17 00:00:00 2001 From: Ben Thomson Date: Mon, 21 Oct 2024 09:15:55 +0800 Subject: [PATCH 10/10] Add example for Snowboard flash usage, fix links on Flash page, add meta --- markup/tags/flash.md | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/markup/tags/flash.md b/markup/tags/flash.md index 36f60973..bb5e46ff 100644 --- a/markup/tags/flash.md +++ b/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 ``` -You can use the `type` variable that represents the flash message type — `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 %} +

+ {{ message }} +

+{% 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