Merge pull request #44 from johnfmorton/customization

Fix for potential Craft 4 to Craft 5 migration issue (redux)

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Release Notes for Craft User Manual
 
+## 5.0.1 - 2024-05-15
+ - Settings model updated with types and validation rules. (This fix is to help address possible issue in Craft 4 to Craft 5 migration.)
+ - Added "enabledSideBar" config setting to enable/disable the sidebar on the manual page.
+ - Error messages moved to translations file to allow for easier translation.
+
 ## 5.0.0 - 2024-04-04
 - Craft 5 support.
 - Adjusted version number to reflect Craft 5 compatibility.

README.md

@@ -6,12 +6,12 @@ Craft User Manual allows developers (or even content editors) to provide CMS doc
 
 ## Requirements
 
-This plugin requires Craft CMS 4.0.0 or later.
+This plugin requires Craft CMS 4.0.0 or later; or Craft CMS 5.0.0 or later.
 
 ## Installation
 
 ### Craft 4 and Craft 5
-To install the plugin in your Craft 4 project, follow these instructions.
+To install the plugin in your Craft 4 or Craft 5 project, follow these instructions.
 
 1. Open your terminal and go to your Craft project:
 
@@ -51,7 +51,7 @@ To install the plugin in your Craft 3 project, follow these instructions.
 5. Click the **User Manual** link in the CP nav.
 ## Configuration
 
-* All settings may be optionally configured using a [config file](http://buildwithcraft.com/docs/plugins/plugin-settings#config-file). The values, contained in [`config.php`](https://github.com/roberskine/Craft-User-Manual/blob/master/src/config.php), are described below:
+* All settings may be optionally configured using a [config file](https://craftcms.com/docs/5.x/extend/plugin-settings.html#overriding-setting-values). The values, contained in [`config.php`](https://github.com/roberskine/Craft-User-Manual/blob/master/src/config.php), are described below:
 
 <a id="config-settings-pluginNameOverride"></a>
 ### pluginNameOverride
@@ -65,7 +65,7 @@ Path is relative to ../craft/templates/.
 
 <a id="config-settings-section"></a>
 ### section
-Entries in this section must have associated urls.
+Entries in this section must have associated urls. When this value is set from the `usermanua.php` file, it much use the section ID as the value, not the section handle.
 
 ### enabledSideBar
 Enables the sidebar on the manual page
@@ -82,7 +82,8 @@ Defaults to true.
 This plugin was inspired by the team over at [70kft](http://70kft.com/) for their work on [Craft-Help](https://github.com/70kft/craft-help). While their plugin is definitely more flexible in terms of writing custom markdown in separate files, we wanted to create something that would make it easier for anyone to edit documentation without making any changes to the server. This works particularly well for larger projects where more than one person (especially non-devs) are writing documentation for how to use the CMS.
 
 ## Releases
-* **5.0.0** - Craft 5 support! Thanks to [John Morton](https://github.com/) and [Dalton Rooney](daltonrooney) for your contributions. 
+* **5.0.1** - Required "section" config setting to be an integer. Added "enabledSideBar" config setting to enable/disable the sidebar on the manual page. This fix is to help address possible issue in Craft 4 to Craft 5 migration.
+* **5.0.0** - Craft 5 support! Thanks to [John Morton](https://github.com/johnfmorton) and [Dalton Rooney](daltonrooney) for your contributions.
 * **4.0.0** - Craft 4 support! Thanks to [Chris DuCharme](https://github.com/Chris-DuCharme) for migrating up to Craft 4.
 * **2.1.0** - Merging PRs from [JorgeAnzola](https://github.com/JorgeAnzola) and [sameerast](https://github.com/sameerast)
 * **2.0.3** - Forcing updating to plugin store

composer.json

@@ -2,7 +2,7 @@
     "name": "hillholliday/craft-user-manual",
     "description": "Craft User Manual allows developers (or even content editors) to provide CMS documentation using Craft's built-in sections (singles, channels, or structures) to create a `User Manual` or `Help` section directly in the control panel.",
     "type": "craft-plugin",
-    "version": "5.0.0",
+    "version": "5.0.1",
     "keywords": [
         "craft",
         "cms",

src/UserManual.php

@@ -1,7 +1,7 @@
 <?php
 
 /**
- * usermanual plugin for Craft CMS 3.x
+ * usermanual plugin for Craft CMS 4.x / 5.x
  *
  * Craft User Manual allows developers (or even content editors) to provide CMS
  * documentation using Craft's built-in sections (singles, channels, or structures)
@@ -118,8 +118,7 @@ public function getName(): string
         $pluginNameOverride = $this->getSettings()->pluginNameOverride;
 
         return ($pluginNameOverride)
-            ? $pluginNameOverride
-            : $pluginName;
+            ?: $pluginName;
     }
 
     public function registerCpUrlRules(RegisterUrlRulesEvent $event): void
@@ -189,21 +188,13 @@ public function getSettings(): ?Model
             $settings->$settingName = $settingValueOverride ?? $settingValue;
         }
 
-        // Allow handles from config
-        if (!is_numeric($settings->section)) {
-            // Get the Craft CMS version
-        $version = Craft::$app->getVersion();
-
-        // Check the first character to determine the major version
-        $majorVersion = $version[0];
-
-            if ($majorVersion === '4') {
-                $section = Craft::$app->getSections()->getSectionByHandle('homepage');
-            } else {
-                $section = Craft::$app->entries->getSectionByHandle('homepage');
-            }
-            if ($section) {
-                $settings->section = $section->id;
+        // if section is a string, convert to int by looking up the section ID
+        if (($settings !== null) && is_string($settings->section)) {
+            $sections = $this->getSections();
+            foreach ($sections as $section) {
+                if ($section['handle'] === $settings->section) {
+                    $settings->section = $section['id'];
+                }
             }
         }
 
@@ -276,7 +267,8 @@ private function getSections(): array
     }
 
     // Abstracted method to get site settings based on version
-    private function getSectionSiteSettings($sectionId) {
+    private function getSectionSiteSettings($sectionId): array
+    {
         $majorVersion = $this->getMajorVersion();
 
         if ($majorVersion === '4') {

src/assetbundles/usermanual/UserManualAsset.php

@@ -1,7 +1,7 @@
 <?php
 
 /**
- * usermanual plugin for Craft CMS 4.x
+ * usermanual plugin for Craft CMS 4.x / 5.x
  *
  * Craft User Manual allows developers (or even content editors) to provide CMS
  * documentation using Craft's built-in sections (singles, channels, or structures)

src/config.php

@@ -1,7 +1,7 @@
 <?php
 
 /**
- * usermanual plugin for Craft CMS 4.x
+ * usermanual plugin for Craft CMS 4.x / 5.x
  *
  * Craft User Manual allows developers (or even content editors) to provide CMS
  * documentation using Craft's built-in sections (singles, channels, or structures)
@@ -28,6 +28,6 @@
 return [
     'pluginNameOverride' => null,
     'templateOverride' => null,
-    'section' => null, // section ID (int) or handle (string)
+    'section' => null, // section ID (int) or section handle (string)
     'enabledSideBar' => true,
 ];

src/models/Settings.php

@@ -1,7 +1,7 @@
 <?php
 
 /**
- * usermanual plugin for Craft CMS 3.x
+ * usermanual plugin for Craft CMS 4.x / 5.x
  *
  * Craft User Manual allows developers (or even content editors) to provide CMS
  * documentation using Craft's built-in sections (singles, channels, or structures)
@@ -29,24 +29,24 @@ class Settings extends Model
     // =========================================================================
 
     /**
-     * @var string
+     * @var string | null
      */
-    public $pluginNameOverride;
+    public ?string $pluginNameOverride = "";
 
     /**
-     * @var string
+     * @var string | null
      */
-    public $templateOverride;
+    public ?string $templateOverride = "";
 
     /**
-     * @var integer
+     * @var int|string|null
      */
-    public $section;
+    public int|string|null $section = null;
 
     /**
      * @var boolean
      */
-    public $enabledSideBar = true;
+    public bool $enabledSideBar = true;
 
 
 

src/templates/settings.twig

@@ -1,7 +1,7 @@
 {# @var craft \craft\web\twig\variables\CraftVariable #}
 {#
 /**
- * usermanual plugin for Craft CMS 3.x
+ * usermanual plugin for Craft CMS 4.x / 5.x
  *
  * usermanual Settings.twig
  *
@@ -56,7 +56,7 @@
     readonly: configOverride,
 } %}
 
-{{ configOverride ? forms.textField(opts) : forms.selectField(opts) }}
+{{  forms.selectField(opts)  }}
 {% else %}
 <div class="warning">
   Setup is not complete. Create a section for the User Manual content and return to this page to select it.
@@ -65,8 +65,25 @@
 {% endif %}
 
 {% set instructions %}
-For more control over the output, you may optionally override the default template.<br>
-Path is relative to <code>{{ siteTemplatesPath }}</code>.
+The sidebar in the default User Manual template allows for multiple pages to make up the user manual. If you have a single page, that navigation is not needed and can be toggled off.
+{% endset %}
+{% set configOverride = 'enabledSideBar' in overrides %}
+
+{{ forms.lightSwitchField({
+    label: "Enable Sidebar"|t,
+    id: 'enabledSideBar',
+    name: 'enabledSideBar',
+    instructions: instructions|raw,
+    on: settings.enabledSideBar,
+    onLabel: "Yes"|t,
+    offLabel: "No"|t,
+    warning: configOverride ? configWarning('enabledSideBar'),
+    disabled: configOverride,
+    readonly: configOverride,
+})}}
+
+{% set instructions %}
+For more control over the output, you may optionally override the default template. Path is relative to <code>{{ siteTemplatesPath }}</code>.
 {% endset %}
 {% set configOverride = 'templateOverride' in overrides %}
 
@@ -82,3 +99,5 @@ Path is relative to <code>{{ siteTemplatesPath }}</code>.
     disabled: configOverride,
     readonly: configOverride,
 })}}
+
+

src/translations/en/usermanual.php

@@ -1,7 +1,7 @@
 <?php
 
 /**
- * usermanual plugin for Craft CMS 3.x
+ * usermanual plugin for Craft CMS 4.x / 5.x
  *
  * Craft User Manual allows developers (or even content editors) to provide CMS
  * documentation using Craft's built-in sections (singles, channels, or structures)
@@ -18,4 +18,8 @@
  */
 return [
     'usermanual plugin loaded' => 'usermanual plugin loaded',
+    'no section error' => 'There is no section selected for the User Manual plugin. Please check the settings page.',
+    'no section error for config file' => 'There is no valid section set for the User Manual plugin. Please check the config file.',
+    'no entry error' => 'There is no entry in the selected section for the User Manual plugin. Please check the settings page. Entries must be enabled and have a slug to be displayed.',
+    'config file section error' => 'Section must be either an integer or a string.',
 ];

src/twigextensions/UserManualTwigExtension.php

@@ -1,7 +1,7 @@
 <?php
 
 /**
- * usermanual plugin for Craft CMS 3.x
+ * usermanual plugin for Craft CMS 4.x / 5.x
  *
  * Craft User Manual allows developers (or even content editors) to provide CMS
  * documentation using Craft's built-in sections (singles, channels, or structures)
@@ -90,12 +90,16 @@ public function getHelpDocument(): string
 
         // If the app does not have a section selected, return an error message to let the admin know
         if (!$sectionId) {
-            return 'There is no section selected for the User Manual plugin. Please check the settings page.';
+            // check if the user is using a config file
+            if (Craft::$app->config->getConfigFromFile('usermanual')) {
+                return Craft::t('usermanual', 'no section error for config file');
+            }
+            return Craft::t('usermanual', 'no section error');
         }
 
         // If there are no entries in the selected section, return an error message to let the admin know
         if (!$entry) {
-            return 'There are no entries in the selected section for the User Manual Plugin. Entries must be enabled and have a slug to be displayed.';
+            return Craft::t('usermanual', 'no entry error');
         } else {
             if ($settings->templateOverride) {
                 // Setting the mode also sets the templatepath to the default for that mode

src/variables/UserManualVariable.php

@@ -1,7 +1,7 @@
 <?php
 
 /**
- * usermanual plugin for Craft CMS 4.x
+ * usermanual plugin for Craft CMS 4.x / 5.x
  *
  * Craft User Manual allows developers (or even content editors) to provide CMS
  * documentation using Craft's built-in sections (singles, channels, or structures)