FEATURE: improve blank page syndrome (#79)

.discourse-compatibility

@@ -0,0 +1 @@
+2.8.0.beta9: 05678c451caf2ceb192501da91cf0d24ea44c8e8

assets/javascripts/discourse/controllers/docs-index.js.es6

@@ -4,6 +4,8 @@ import { action } from "@ember/object";
 import { alias, equal, gt, readOnly } from "@ember/object/computed";
 import Docs from "discourse/plugins/discourse-docs/discourse/models/docs";
 import { getOwner } from "@ember/application";
+import getURL from "discourse-common/lib/get-url";
+import I18n from "I18n";
 
 const SHOW_FILTER_AT = 10;
 
@@ -156,7 +158,7 @@ export default Controller.extend({
   },
 
   @discourseComputed("topics", "isSearching", "filterSolved")
-  emptyTopics(topics, isSearching, filterSolved) {
+  noContent(topics, isSearching, filterSolved) {
     const filtered = isSearching || filterSolved;
     return this.topicCount === 0 && !filtered;
   },
@@ -194,6 +196,53 @@ export default Controller.extend({
     return this.siteSettings.tagging_enabled;
   },
 
+  @discourseComputed()
+  emptyState() {
+    let body = I18n.t("docs.no_docs.body");
+    if (this.docsCategoriesAndTags.length) {
+      body += I18n.t("docs.no_docs.to_include_topic_in_docs");
+      body += ` (${this.docsCategoriesAndTags.join(", ")}).`;
+    } else if (this.currentUser.staff) {
+      const setUpPluginMessage = I18n.t("docs.no_docs.setup_the_plugin", {
+        settingsUrl: getURL(
+          "/admin/site_settings/category/plugins?filter=plugin:discourse-docs"
+        ),
+      });
+      body += ` ${setUpPluginMessage}`;
+    }
+
+    return {
+      title: I18n.t("docs.no_docs.title"),
+      body: body.htmlSafe(),
+    };
+  },
+
+  @discourseComputed("docsCategories", "docsTags")
+  docsCategoriesAndTags(docsCategories, docsTags) {
+    return docsCategories.concat(docsTags);
+  },
+
+  @discourseComputed()
+  docsCategories() {
+    if (!this.siteSettings.docs_categories) {
+      return [];
+    }
+
+    return this.siteSettings.docs_categories.split("|").map((c) => {
+      const id = parseInt(c, 10);
+      return this.site.categories.findBy("id", id).name;
+    });
+  },
+
+  @discourseComputed()
+  docsTags() {
+    if (!this.siteSettings.docs_tags) {
+      return [];
+    }
+
+    return this.siteSettings.docs_tags.split("|").map((t) => `#${t}`);
+  },
+
   @action
   toggleCategorySort(newType) {
     let { type, direction } = this.categorySort;

assets/javascripts/discourse/templates/docs-index.hbs

@@ -1,6 +1,9 @@
 {{#conditional-loading-spinner condition=isLoading}}
-  {{#if emptyTopics}}
-    <span class="no-topics-found">{{html-safe (i18n "docs.no_topics")}}</span>
+  {{#if noContent}}
+    <EmptyState
+      @title={{emptyState.title}}
+      @body={{emptyState.body}}
+    />
   {{else}}
     <div class="docs-browse">
       {{#if site.mobileView}}

config/locales/client.en.yml

@@ -8,7 +8,11 @@ en:
       column_titles:
         topic: "Topic"
         activity: "Activity"
-      no_topics: "No topics in Docs."
+      no_docs:
+        title: "No Docs topics yet"
+        body: "Docs provides a great way to maintain a collection of documentation for shared reference."
+        to_include_topic_in_docs: "To include a topic in Docs, use a special category or tag"
+        setup_the_plugin: "To start using Docs, please, <a href='%{settingsUrl}'>set up docs categories and tags</a>."
       categories: "Categories"
       categories_filter_placeholder: "Filter categories"
       tags_filter_placeholder: "Filter tags"

test/javascripts/acceptance/docs-test.js.es6

@@ -1,6 +1,7 @@
 import {
   acceptance,
   count,
+  exists,
   query,
 } from "discourse/tests/helpers/qunit-helpers";
 import { test } from "qunit";
@@ -58,3 +59,36 @@ acceptance("Docs", function (needs) {
     assert.equal(count(".docs-category.selected"), 1);
   });
 });
+
+acceptance("Docs - empty state", function (needs) {
+  needs.user();
+  needs.settings({
+    docs_enabled: true,
+  });
+
+  needs.pretender((server, helper) => {
+    server.get("/docs.json", () => {
+      const response = {
+        tags: [],
+        categories: [],
+        topics: {
+          topic_list: {
+            can_create_topic: true,
+            per_page: 30,
+            top_tags: [],
+            topics: [],
+          },
+          load_more_url: null,
+        },
+        topic_count: 0,
+      };
+
+      return helper.response(response);
+    });
+  });
+
+  test("shows the empty state panel when there are no docs", async function (assert) {
+    await visit("/docs");
+    assert.ok(exists("div.empty-state"));
+  });
+});