Preps configuration and upgrade guides for Craft 5

barrelstrength · Jun 30, 2024 · c8b89f4 · c8b89f4
1 parent 364e2d4
commit c8b89f4
Show file tree

Hide file tree

Showing 7 changed files with 77 additions and 377 deletions.
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
@@ -91,16 +91,16 @@ export default defineConfig({
                 //         {text: 'FAQ & Examples', link: '/examples-email/faq'},
                 //     ]
                 // },
-                // {
-                //     text: 'SEO Metadata',
-                //     collapsed: false,
-                //     items: [
-                //         {text: 'Meta Tags & Schema', link: '/meta'},
-                //         {text: 'Redirects', link: '/redirects'},
-                //         {text: 'Sitemaps', link: '/sitemaps'},
-                //         {text: 'FAQ & Examples', link: '/examples-seo/faq'},
-                //     ]
-                // },
+                {
+                    text: 'SEO Metadata',
+                    collapsed: false,
+                    items: [
+                        // {text: 'Meta Tags & Schema', link: '/meta'},
+                        {text: 'Redirects', link: '/redirects'},
+                        {text: 'Sitemaps', link: '/sitemaps'},
+                        {text: 'FAQ & Examples', link: '/examples-seo/faq'},
+                    ]
+                },
             ],
 
             '/support/': [
@@ -137,24 +137,19 @@ export default defineConfig({
                     text: 'Update Guides',
                     items: [
                         {text: 'Updating Sprout', link: '/update-guides/index'},
+                        {text: 'Upgrading from Craft 4', link: '/update-guides/sprout'},
                     ]
                 },
-                {
-                    text: 'Plugins',
-                    items: [
-                        {text: 'Data Studio', link: '/update-guides/data-studio'},
+                // {
+                //     text: 'Plugins',
+                //     items: [
+                        // {text: 'Data Studio', link: '/update-guides/data-studio'},
                         // {text: 'Email', link: '/update-guides/email'},
                         // {text: 'SEO', link: '/update-guides/seo'},
-                        {text: 'Redirects', link: '/update-guides/redirects'},
-                        {text: 'Sitemaps', link: '/update-guides/sitemaps'},
-                    ]
-                },
-                {
-                    text: 'All Plugins',
-                    items: [
-                        {text: 'Craft 5', link: '/update-guides/sprout'},
-                    ]
-                }
+                        // {text: 'Redirects', link: '/update-guides/redirects'},
+                        // {text: 'Sitemaps', link: '/update-guides/sitemaps'},
+                    // ]
+                // },
             ],
 
             '/examples-data-studio/': [
@@ -202,18 +197,18 @@ export default defineConfig({
                         {text: '← Back to SEO', link: '/meta'},
                     ]
                 },
-                {
-                    text: 'Metadata',
-                    items: [
-                        {text: 'Troubleshooting FAQ', link: '/examples-seo/faq'},
-                        {text: 'Global Metadata in Templates', link: '/examples-seo/global-metadata-in-templates'},
-                        {text: 'Element Metadata Field', link: '/examples-seo/element-metadata-field'},
-                        {text: 'Template Metadata Overrides', link: '/examples-seo/template-metadata-overrides'},
-                        {text: 'Canonical URLs', link: '/examples-seo/canonical-urls'},
-                        {text: 'Block Search Robots', link: '/examples-seo/block-robots-on-dev-site'},
-                        {text: 'Elements Without URLs', link: '/examples-seo/elements-without-urls'},
-                    ]
-                },
+                // {
+                //     text: 'Metadata',
+                //     items: [
+                //         {text: 'Troubleshooting FAQ', link: '/examples-seo/faq'},
+                //         {text: 'Global Metadata in Templates', link: '/examples-seo/global-metadata-in-templates'},
+                //         {text: 'Element Metadata Field', link: '/examples-seo/element-metadata-field'},
+                //         {text: 'Template Metadata Overrides', link: '/examples-seo/template-metadata-overrides'},
+                //         {text: 'Canonical URLs', link: '/examples-seo/canonical-urls'},
+                //         {text: 'Block Search Robots', link: '/examples-seo/block-robots-on-dev-site'},
+                //         {text: 'Elements Without URLs', link: '/examples-seo/elements-without-urls'},
+                //     ]
+                // },
                 {
                     text: 'Redirects',
                     items: [
@@ -259,14 +254,14 @@ export default defineConfig({
             port: 5173, // Use port 3000 for dev server.
             // port: 4173, // Use port 3000 for dev server.
             strictPort: true, // Don't try next available port if 3000 isn't available.
-            origin: 'http://demo.projectmothership.com.ddev.site:5174', // Rewrite asset URLs explicitly since the CMS web server is on a different host.
-            // origin: 'http://demo.projectmothership.com.ddev.site:4173', // Rewrite asset URLs explicitly since the CMS web server is on a different host.
+            origin: 'http://5.projectmothership.com.ddev.site:5174', // Rewrite asset URLs explicitly since the CMS web server is on a different host.
+            // origin: 'http://5.projectmothership.com.ddev.site:4173', // Rewrite asset URLs explicitly since the CMS web server is on a different host.
             hmr: {
                 port: 5173,
                 clientPort: 5174,
                 // port: 4173,
                 // clientPort: 4174,
-                host: 'demo.projectmothership.com.ddev.site',
+                host: '5.projectmothership.com.ddev.site',
                 protocol: 'wss',
             },
         }

diff --git a/docs/configuration/sprout-config.md b/docs/configuration/sprout-config.md
@@ -5,7 +5,7 @@ description: Configuration settings for the sprout plugins.
 
 # Config Settings
 
-Sprout settings are configured on a per-module basis and documented in the Control Panel and the [example config files](https://github.com/barrelstrength/craft-sprout/tree/v4/configs) in the root of the repository.
+Sprout settings are configured on a per-module basis and documented in the Control Panel and the [example config files](https://github.com/barrelstrength/craft-sprout/tree/v5/configs) in the root of the repository.
 
 Configuration settings are managed across five areas:
 

diff --git a/docs/update-guides/data-studio.md b/docs/update-guides/data-studio.md
@@ -5,53 +5,10 @@ description: Sprout Data Studio update guide.
 
 # Updating Data Studio
 
-## v4.44.444 - February 20, 2023
+## v5.0.0 - July 2024
 
-Sprout Reports is now Sprout Data Studio and now includes integrated Commerce Data Sets and Date Range Helper classes. Data Sets now support a custom field layout and element sources can be customized based on a Data Source condition rule or any custom fields in your field layout.
+This release adds Craft 5 support and focuses on compatibility.
 
-### Breaking Changes
+- Upgrade plugin to the latest version on Craft 4.x
+- Follow the standard Craft 
 
-::: warning
-Due to this plugin's name change (Reports => Data Studio) you will need to manually install it and manually update to your new license key after upgrading to Craft 4 to trigger its migrations. If you have any Report-related dashboard widgets you may see an error when you first login to your Craft 4 control panel. Navigate directly to the plugins page `/admin/settings/plugins` to install the plugin.
-
-Once you've updated Sprout Reports to the latest on Craft 3, you can remove it from the composer.json file. Once upgraded to Craft 4, you can install Sprout Data Studio via composer or from the plugin store.
-:::
-
-### License Migrations
-
-Existing Sprout Reports license holders have received a new Sprout Data Studio Pro license in the same Craft Console account for the old Sprout Reports license key. Once installing Data Studio, you will need to manually add your new licenses key to your Craft installation. Your new Data Studio license will have the same expiration as the old Sprout Reports license and you will need to manually re-select the auto-renew option in your Craft Console.
-
-### Data Studio
-
-- Sprout Reports has been renamed to Sprout Data Studio
-- Sprout Data Studio now has a Lite and Pro Edition.
-- Updated variable `craft.sproutReports` => `sprout.twigDataSet`
-- Twig Template Data Sources that use a Craft DateTime picker in their templates will need to update the date syntax to use Twig the [date function](https://craftcms.com/docs/4.x/upgrade.html#template-functions)
-- Twig Template Data Sources should update `{%- includejs %}` => `{%- js %}`
-- Any references to the Project Config settings key should be updated `sprout-reports` => `sprout-module-data-studio`
-- Custom DataSources should use `BarrelStrength\Sprout\datastudio\datasources\DataSource` (See `vendor/barrelstrength/sprout/src/datastudio/components/datasources` for examples)
-- Access Data Source permissions have been removed in favor of Craft User permissions. Confirm any permissions that were previously assigned to Data Sources are now assigned to the User Groups appropriately.
-- Date Sources used as email lists will need to be migrated manually to Audience Types (once the email module is released)
-
-### Framework
-
-- See the general [upgrade guide][#400-framework] for Sprout Modules to 4.0
-
-[#400-framework]: ../update-guides/sprout.md
-
-## v4.46.0 - September 5, 2023
-
-This release includes a breaking change if you are using Source Groups to group your Data Sets. Sprout provided a method to group Data Sets in Craft 3 and due to some inconsistencies with multi-site functionality we have decided to remove this from Craft 4, effective immediately, in favor of using the Data Studio Global Field Layout and Craft's native Custom Sources.
-
-As plugin migrations should only touch schema controlled by the plugin itself, you will need to manually implement this change if you desire to group your Data Sets in the sidebar of the element index page. No Data Set settings are changed in this update aside from the group metadata.
-
-### Breaking Changes
-
-To implement custom sources for your Data Set you must be an Admin:
-
-1. Add a custom Dropdown or Relation field to your Data Set field layout `Settings->Data Studio->Field Layout`
-2. Edit any Data Sets you want to group and select the appropriate value in your new field
-3. On the Data Sets Element Index page, select the gear icon and choose "Customize Sources"
-4. From the "Customize Sources" modal, select the `+` icon and choose "New custom source"
-5. Give your custom source a Label and select your Custom Field and Data Set Criteria to create a Condition Rule
-6. Repeat step 5 for each custom source you want to add
diff --git a/docs/update-guides/forms.md b/docs/update-guides/forms.md
@@ -3,19 +3,6 @@ date: 2023-09-25
 description: Sprout Forms update guide.
 ---
 
-# Upgrading to Forms v4.44.444
+# Upgrading to Forms v5
 
-Sprout Reports is now Sprout Data Studio and now includes integrated Commerce Data Sets and Date Range Helper classes. Data Sets now support a custom field layout and element sources can be customized based on a Data Source condition rule or any custom fields in your field layout.
 
-## Breaking Changes
-
-### Source Groups have been removed in favor of Custom Sources
-
-To implement custom sources for your Forms you must be an Admin:
-
-1. Add a custom Dropdown or Relation field to your Form Type field layout `Settings->Data Studio->Field Layout`
-2. Edit any Forms you want to group and select the appropriate value in your new field
-3. On the Forms Element Index page, select the gear icon and choose "Customize Sources"
-4. From the "Customize Sources" modal, select the `+` icon and choose "New custom source"
-5. Give your custom source a Label and select your Custom Field and Form Criteria to create a Condition Rule
-6. Repeat step 5 for each custom source you want to add
diff --git a/docs/update-guides/index.md b/docs/update-guides/index.md
@@ -5,22 +5,39 @@ description: Update guides for Sprout plugins.
 
 # Updating Sprout
 
-The Sprout plugins are built using the Sprout Framework – a collection of modules - so that plugins can share core functionality. Plugin changelogs reference the modules that have changed, and the [Sprout Framework Changelogs](https://github.com/barrelstrength/sprout/tree/v4/CHANGELOG) document all the updates in the underlying modules.
+The Sprout plugins are built using the Sprout Framework – a collection of modules. Plugin changelogs reference the modules that have changed, and the [Sprout Framework Changelogs](https://github.com/barrelstrength/sprout/tree/v5/CHANGELOG) document all the updates in the underlying modules.
 
-The upgrade guides are organized by plugin and releases are listed by date. Where appropriate, a plugin might link to update notes in another plugin. For example, the Sprout Forms changelog might link to the Sprout Email changelog for a particular update if notable changes have been made to email-specific features.
+[//]: # (Update guides are created for a plugin when there are notable changes. )
 
-::: warning Migrations and Craft Commands
-Sprout plugins for Craft 4 currently require that you update via the browser to trigger migrations. Running `./craft migrate/all` will not trigger the Sprout module migrations.
+[//]: # (If you don't see an update guide, follow the standard Craft update process for the plugin.)
 
-Each Sprout module has its own migration track and a single migration might get triggered by one or more modules. Sprout plugins manage the order that migrations need to run and ensure that migrations only run once, but, currently, Craft's CLI commands for migrations do not consider the scenario where a plugin runs migrations that are not using the plugin migration track. We're working on finding a Craft-friendly way to handle this scenario, but for now, to ensure all Sprout migrations run correctly you'll need to run migrations via the Update button in the browser.  
-:::
+[//]: # (The update guides are organized by plugin and releases are listed by date.)
 
 ## Update Guides
 
-The update guides are primarily for notable changes. Not all plugin versions will appear here in the update guides. See the changelogs for a given plugin for more detailed notes on every release.
+- [Upgrading from Craft 4](./sprout.md)
 
-- [Sprout Data Studio](./data-studio.md)
-- [Sprout Email](./email.md)
-- [Sprout Redirects](./redirects.md)
-- [Sprout Seo](./seo.md)
-- [Sprout Sitemaps](./sitemaps.md)
+[//]: # (## Sprout Plugin Update Guides)
+
+[//]: # (The following plugins have update guides available.)
+
+[//]: # (If you don't see an update guide for a plugin, follow the standard Craft update process for the plugin.)
+
+[//]: # (## Sprout Plugin Update Guides)
+
+[//]: # (The following plugins have update guides available.)
+
+[//]: # ()
+[//]: # (The update guides are primarily for notable changes. Not all plugin versions will appear here in the update guides. See the changelogs for a given plugin for more detailed notes on every release.)
+
+[//]: # (- [Sprout Data Studio]&#40;./data-studio.md&#41;)
+
+[//]: # (- [Sprout Forms]&#40;./forms.md&#41;)
+
+[//]: # (- [Sprout Email]&#40;./email.md&#41;)
+
+[//]: # (- [Sprout Redirects]&#40;./redirects.md&#41;)
+
+[//]: # (- [Sprout Seo]&#40;./seo.md&#41;)
+
+[//]: # (- [Sprout Sitemaps]&#40;./sitemaps.md&#41;)
diff --git a/docs/update-guides/sitemaps.md b/docs/update-guides/sitemaps.md
@@ -5,55 +5,7 @@ description: Sprout Sitemaps update guide.
 
 # Updating Sitemaps
 
-## v4.44.444 - September 25, 2023
+## v5.0.0 - July 2024
 
-This release adds Craft 4 support and a few new features such as Content Query Sitemaps and improved navigation.
-
-Sitemaps now has a Lite and Pro version. License holders can continue to use their existing license key for as a Pro license on Craft 4.
-
-### Breaking Changes
-
-- See the general [upgrade guide][#400-framework] for Sprout Modules to 4.0
-- Lite Edition allows managing up to 5 Content and Content Query Sitemaps per Site
-- Custom Sitemap Metadata integration has been updated from `barrelstrength\sproutbaseuris\services\UrlEnabledSections::EVENT_REGISTER_URL_ENABLED_SECTION_TYPES` => `BarrelStrength\Sprout\sitemaps\sitemapmetadata\SitemapMetadata::EVENT_REGISTER_ELEMENT_SITEMAP_METADATA`
-
-### Notable Changes
-
-#### Generated URLs for individual sitemaps have changed
-
-Your `/sitemap.xml` Sitemap index exists at the same URL, however, the URLs listed in the Sitemap Index have changed.
-
-In Craft 3, Content Sitemaps displayed with a 12 character key:
-
-``` xml{4,8}
-<?xml version="1.0" encoding="UTF-8"?>
-<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
-    <sitemap>
-        <loc>{{ siteUrl }}sitemap-G76D5Oizt4fH-1.xml</loc>
-        <lastmod>{{ now|date('Y-m-d') }}</lastmod>
-    </sitemap>
-    <sitemap>
-        <loc>{{ siteUrl }}sitemap-9O2U0q1gdvPM-1.xml</loc>
-        <lastmod>{{ now|date('Y-m-d') }}</lastmod>
-    </sitemap>
-</sitemapindex>
-```
-
-In Craft 4, Content Sitemaps display using the Sitemap Metadata UID key:
-
-``` xml{4,8}
-<?xml version="1.0" encoding="UTF-8"?>
-<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
-    <sitemap>
-        <loc>{{ siteUrl }}sitemap-0a0c9e98-fe8b-430a-9b47-f3e521dd048e-1.xml</loc>
-        <lastmod>{{ now|date('Y-m-d') }}</lastmod>
-    </sitemap>
-    <sitemap>
-        <loc>{{ siteUrl }}sitemap-0a0c9e98-fe8b-430a-9b47-f3e521dd048e-2.xml</loc>
-        <lastmod>{{ now|date('Y-m-d') }}</lastmod>
-    </sitemap>
-</sitemapindex>
-```
-
-[#400-framework]: /update-guides/sprout.md
+This release adds Craft 5 support and focuses on compatibility