Adding ability to add custom URL segment for User Manual

CHANGELOG.md

@@ -1,5 +1,8 @@
 # Release Notes for Craft User Manual
 
+## 5.0.4 - 2025-02-05
+- Adding in ability to add a custom URL segment to the user manual documentation section.
+
 ## 5.0.3 - 2025-02-05
 - Removing requirement for documentation to have URLs. [PR #48](https://github.com/RobErskine/Craft-User-Manual/pull/48)
 

README.md

@@ -83,6 +83,8 @@ This plugin was inspired by the team over at [70kft](http://70kft.com/) for thei
 
 ## Releases
 See CHANGELOG.md for full release history.
+
+* **5.0.4** - Adding in ability to customize URL segment of the user manual documentation section
 * **5.0.3** - Merging PRs from [JorgeAnzola](https://github.com/JorgeAnzola) to remove requirement for User Manual entries to require URLs
 * **5.0.2** - Replacing `addExtension` with Craft Hook 
 * **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.

src/UserManual.php

@@ -30,7 +30,7 @@
 use roberskine\usermanual\twigextensions\UserManualTwigExtension;
 
 /**
- * Class Usermanual
+ * Class UserManual
  *
  * @author    Rob Erskine
  * @package   Usermanual
@@ -106,6 +106,16 @@ function (Event $event) {
         );
     }
 
+    /**
+     * @inheritdoc
+     */
+    public function getCpNavItem(): ?array
+    {
+        $item = parent::getCpNavItem();
+        $item['url'] = '/admin/' . $this->getSettings()->urlSegment;
+        return $item;
+    }
+
     /**
      * Returns the user-facing name of the plugin, which can override the name
      * in composer.json
@@ -123,8 +133,10 @@ public function getName(): string
 
     public function registerCpUrlRules(RegisterUrlRulesEvent $event): void
     {
+        $urlSegment = $this->getSettings()->urlSegment;
         $rules = [
-            'usermanual/<userManualPath:([a-zéñåA-Z0-9\-\_\/]+)?>' => ['template' => 'usermanual/index'],
+            $urlSegment => ['template' => 'usermanual/index'],
+            $urlSegment . '/<userManualPath:([a-zéñåA-Z0-9\-\_\/]+)?>' => ['template' => 'usermanual/index'],
         ];
 
         $event->rules = array_merge($event->rules, $rules);

src/models/Settings.php

@@ -48,7 +48,10 @@ class Settings extends Model
      */
     public bool $enabledSideBar = true;
 
-
+    /**
+     * @var string
+     */
+    public string $urlSegment = 'usermanual';
 
     // Public Methods
     // =========================================================================
@@ -59,7 +62,7 @@ class Settings extends Model
     public function rules(): array
     {
         return [
-            [['pluginNameOverride', 'templateOverride'], 'string'],
+            [['pluginNameOverride', 'templateOverride', 'urlSegment'], 'string'],
             ['section', 'number'],
             ['enabledSideBar', 'boolean']
         ];

src/templates/index.twig

@@ -1,4 +1,3 @@
-
 {% extends "_layouts/cp" %}
 {% set title = craft.userManual.name|t %}
 
@@ -21,10 +20,10 @@
       {% set help = craft.entries.sectionId(sectionSelected).all() %}
       <ul class="craft-{{ craftMajorVersion() }}">
         {% nav page in help %}
-          {% set active = page.id == craft.app.request.segments|last or loop.first and craft.app.request.segments|last == 'usermanual' %}
+          {% set active = page.id == craft.app.request.segments|last or loop.first and craft.app.request.segments|last == craft.userManual.settings.urlSegment %}
           <li id="{{ page.id }}">
             <a {% if active %}class="sel"{% endif %}
-              href="{{ url('usermanual/' ~ page.id) }}">
+              href="{{ url(craft.userManual.settings.urlSegment ~ '/' ~ page.id) }}">
               {{page.title}}
             </a>
             {% ifchildren %}

src/templates/settings.twig

@@ -39,6 +39,18 @@
     readonly: configOverride,
 })}}
 
+{{ forms.textField({
+    label: "URL Segment"|t('usermanual'),
+    instructions: "The URL segment to use after 'admin' for the user manual (e.g. /admin/usermanual)"|t('usermanual'),
+    default: 'usermanual',
+    required: true,
+    id: 'urlSegment',
+    name: 'urlSegment',
+    value: settings.urlSegment,
+    errors: settings.getErrors('urlSegment'),
+    first: true,
+}) }}
+
 {% set configOverride = 'section' in overrides %}
 {% set inputMacro = configOverride ? 'textField' : 'selectField' %}
 
@@ -99,5 +111,3 @@ For more control over the output, you may optionally override the default templa
     disabled: configOverride,
     readonly: configOverride,
 })}}
-
-

src/twigextensions/UserManualTwigExtension.php

@@ -73,18 +73,22 @@ public function getHelpDocument(): string
         $segments = Craft::$app->request->segments;
         $segment = end($segments);
         $sectionId = $settings->section;
-
-        if (count($segments) === 1 && $segment === 'usermanual') {
-            $id = null;
+        $urlSegment = $settings->urlSegment;
+
+        if (count($segments) === 1 && $segment === $urlSegment) {
+            // Get the first entry in the section when viewing the base URL
+            $criteria = [
+                'sectionId' => $sectionId,
+                'limit' => 1,
+                'orderBy' => 'dateCreated ASC'
+            ];
         } else {
-            $id = $segment;
+            $criteria = [
+                'sectionId' => $sectionId,
+                'id' => $segment,
+            ];
         }
 
-        $criteria = [
-            'sectionId' => $sectionId,
-            'id' => $id,
-        ];
-
         Craft::configure($query, $criteria);
         $entry = $query->one();