Add README documentation to ExtensionPage (#3094)

Co-authored-by: Alexander Skvortsov <[email protected]>

js/src/admin/components/ExtensionPage.js

@@ -11,6 +11,7 @@ import LoadingModal from './LoadingModal';
 import ExtensionPermissionGrid from './ExtensionPermissionGrid';
 import isExtensionEnabled from '../utils/isExtensionEnabled';
 import AdminPage from './AdminPage';
+import ReadmeModal from './ReadmeModal';
 
 export default class ExtensionPage extends AdminPage {
   oninit(vnode) {
@@ -196,6 +197,22 @@ export default class ExtensionPage extends AdminPage {
       }
     });
 
+    const extension = this.extension;
+    items.add(
+      'readme',
+      Button.component(
+        {
+          icon: 'fab fa-readme',
+          class: 'Readme-link',
+          onclick() {
+            app.modal.show(ReadmeModal, { extension });
+          },
+        },
+        app.translator.trans('core.admin.extension.readme.button_label')
+      ),
+      10
+    );
+
     return items;
   }
 

js/src/admin/components/ReadmeModal.js

@@ -0,0 +1,50 @@
+import app from '../../admin/app';
+import Modal from '../../common/components/Modal';
+import LoadingIndicator from '../../common/components/LoadingIndicator';
+import Placeholder from '../../common/components/Placeholder';
+import ExtensionReadme from '../models/ExtensionReadme';
+
+export default class ReadmeModal extends Modal {
+  oninit(vnode) {
+    super.oninit(vnode);
+
+    app.store.models['extension-readmes'] = ExtensionReadme;
+
+    this.name = this.attrs.extension.id;
+    this.extName = this.attrs.extension.extra['flarum-extension'].title;
+
+    this.loading = true;
+
+    this.loadReadme();
+  }
+
+  className() {
+    return 'ReadmeModal Modal--large';
+  }
+
+  title() {
+    return app.translator.trans('core.admin.extension.readme.title', {
+      extName: this.extName,
+    });
+  }
+
+  content() {
+    const text = app.translator.trans('core.admin.extension.readme.no_readme');
+
+    return (
+      <div className="container">
+        {this.loading ? (
+          <div className="ReadmeModal-loading">{LoadingIndicator.component()}</div>
+        ) : (
+          <div>{this.readme.content() ? m.trust(this.readme.content()) : Placeholder.component({ text })}</div>
+        )}
+      </div>
+    );
+  }
+
+  async loadReadme() {
+    this.readme = await app.store.find('extension-readmes', this.name);
+    this.loading = false;
+    m.redraw();
+  }
+}

js/src/admin/models/ExtensionReadme.js

@@ -0,0 +1,5 @@
+import Model from '../../common/Model';
+
+export default class ExtensionReadme extends Model {
+  content = Model.attribute('content');
+}

less/admin.less

@@ -11,4 +11,5 @@
 @import "admin/AppearancePage";
 @import "admin/MailPage";
 @import "admin/NoJs";
-@import "admin/UsersListPage.less";
+@import "admin/ReadmeModal";
+@import "admin/UsersListPage";

less/admin/ExtensionPage.less

@@ -149,3 +149,20 @@
   display: inline-block;
   margin-left: 8px;
 }
+
+.Readme-link {
+  background: none;
+  border: none;
+  cursor: pointer;
+  color: @muted-color;
+}
+
+.ReadmeModal {
+  .Modal-header {
+    background: @control-bg;
+    color: @muted-color
+  }
+  img {
+      max-width: 100%;
+  }
+}

less/admin/ReadmeModal.less

@@ -0,0 +1,5 @@
+.ReadmeModal {
+    .Placeholder {
+        margin-bottom: 40px;
+    }
+}

locale/core.yml

@@ -131,6 +131,10 @@ core:
       open_modal: Open Settings
       permissions_title: Permissions
       purge_button: Purge
+      readme:
+        button_label: README
+        no_readme: This extension does not appear to have a README file
+        title: "{extName} documentation"
 
     # These translations are used in the secondary header.
     header:

src/Api/Controller/ShowExtensionReadmeController.php

@@ -0,0 +1,47 @@
+<?php
+
+/*
+ * This file is part of Flarum.
+ *
+ * For detailed copyright and license information, please view the
+ * LICENSE file that was distributed with this source code.
+ */
+
+namespace Flarum\Api\Controller;
+
+use Flarum\Api\Serializer\ExtensionReadmeSerializer;
+use Flarum\Extension\ExtensionManager;
+use Flarum\Http\RequestUtil;
+use Illuminate\Support\Arr;
+use Psr\Http\Message\ServerRequestInterface;
+use Tobscure\JsonApi\Document;
+
+class ShowExtensionReadmeController extends AbstractShowController
+{
+    /**
+     * @var ExtensionManager
+     */
+    protected $extensions;
+
+    /**
+     * {@inheritdoc}
+     */
+    public $serializer = ExtensionReadmeSerializer::class;
+
+    public function __construct(ExtensionManager $extensions)
+    {
+        $this->extensions = $extensions;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    protected function data(ServerRequestInterface $request, Document $document)
+    {
+        $extensionName = Arr::get($request->getQueryParams(), 'name');
+
+        RequestUtil::getActor($request)->assertAdmin();
+
+        return $this->extensions->getExtension($extensionName);
+    }
+}

src/Api/Serializer/ExtensionReadmeSerializer.php

@@ -0,0 +1,35 @@
+<?php
+
+/*
+ * This file is part of Flarum.
+ *
+ * For detailed copyright and license information, please view the
+ * LICENSE file that was distributed with this source code.
+ */
+
+namespace Flarum\Api\Serializer;
+
+class ExtensionReadmeSerializer extends AbstractSerializer
+{
+    /**
+     * {@inheritdoc}
+     */
+    protected function getDefaultAttributes($extension)
+    {
+        $attributes = [
+            'content' => $extension->getReadme()
+        ];
+
+        return $attributes;
+    }
+
+    public function getId($extension)
+    {
+        return $extension->getId();
+    }
+
+    public function getType($extension)
+    {
+        return 'extension-readmes';
+    }
+}

src/Api/routes.php

@@ -265,6 +265,13 @@
         $route->toController(Controller\UninstallExtensionController::class)
     );
 
+    // Get readme for an extension
+    $map->get(
+        '/extension-readmes/{name}',
+        'extension-readmes.show',
+        $route->toController(Controller\ShowExtensionReadmeController::class)
+    );
+
     // Update settings
     $map->post(
         '/settings',

src/Extension/Extension.php

@@ -19,6 +19,7 @@
 use Illuminate\Support\Arr;
 use Illuminate\Support\Collection;
 use Illuminate\Support\Str;
+use s9e\TextFormatter\Bundles\Fatdown;
 use Throwable;
 
 /**
@@ -525,4 +526,28 @@ public function toArray()
             'links'                  => $this->getLinks(),
         ], $this->composerJson);
     }
+
+    /**
+     * Gets the rendered contents of the extension README file as a HTML string.
+     *
+     * @return string|null
+     */
+    public function getReadme(): ?string
+    {
+        $content = null;
+
+        if (file_exists($file = "$this->path/README.md")) {
+            $content = file_get_contents($file);
+        } elseif (file_exists($file = "$this->path/README")) {
+            $content = file_get_contents($file);
+        }
+
+        if ($content) {
+            $xml = Fatdown::parse($content);
+
+            return Fatdown::render($xml);
+        }
+
+        return null;
+    }
 }