From 782dc09d96a88c3a61f03d28a63b2508836c4e5b Mon Sep 17 00:00:00 2001
From: Andrei Prigorshnev <a.prigorshnev@gmail.com>
Date: Thu, 15 Apr 2021 19:17:07 +0400
Subject: [PATCH] UX: Add a help modal dialog (#109)

---
 .../controllers/admin-plugins-explorer.js.es6 |  4 ++
 .../templates/admin/plugins-explorer.hbs      | 41 +++++++++++--------
 .../discourse/templates/modal/query-help.hbs  |  6 +++
 config/locales/client.en.yml                  | 30 +++++++++++++-
 4 files changed, 63 insertions(+), 18 deletions(-)
 create mode 100644 assets/javascripts/discourse/templates/modal/query-help.hbs

diff --git a/assets/javascripts/discourse/controllers/admin-plugins-explorer.js.es6 b/assets/javascripts/discourse/controllers/admin-plugins-explorer.js.es6
index 472f9f8..900c001 100644
--- a/assets/javascripts/discourse/controllers/admin-plugins-explorer.js.es6
+++ b/assets/javascripts/discourse/controllers/admin-plugins-explorer.js.es6
@@ -159,6 +159,10 @@ export default Ember.Controller.extend({
       this.transitionToRoute("adminPlugins.explorer");
     },
 
+    showHelpModal() {
+      showModal("query-help");
+    },
+
     resetParams() {
       this.selectedItem.resetParams();
     },
diff --git a/assets/javascripts/discourse/templates/admin/plugins-explorer.hbs b/assets/javascripts/discourse/templates/admin/plugins-explorer.hbs
index 5004eda..5502716 100644
--- a/assets/javascripts/discourse/templates/admin/plugins-explorer.hbs
+++ b/assets/javascripts/discourse/templates/admin/plugins-explorer.hbs
@@ -53,25 +53,29 @@
               </div>
             {{/if}}
 
-            <div class="groups">
-              <span class="label">{{i18n "explorer.allow_groups"}}</span>
-              <span>
-                {{multi-select
-                  value=selectedItem.group_ids
-                  content=groupOptions
-                  allowAny=false
-                  onSelect=(action (mut selectedItem.group_ids))
-                }}
-              </span>
-              {{#if runDisabled}}
-                {{#unless editing}}
-                <span class='setting-controls'>
-                  {{d-button class="ok" action=(action "save") icon="check"}}
-                  {{d-button class="cancel" action=(action "discard") icon="times"}}
+            <div class="pull-left">
+              <div class="groups">
+                <span class="label">{{i18n "explorer.allow_groups"}}</span>
+                <span>
+                  {{multi-select
+                    value=selectedItem.group_ids
+                    content=groupOptions
+                    allowAny=false
+                    onSelect=(action (mut selectedItem.group_ids))
+                  }}
                 </span>
-              {{/unless}}
-              {{/if}}
+                {{#if runDisabled}}
+                  {{#unless editing}}
+                  <span class='setting-controls'>
+                    {{d-button class="ok" action=(action "save") icon="check"}}
+                    {{d-button class="cancel" action=(action "discard") icon="times"}}
+                  </span>
+                {{/unless}}
+                {{/if}}
+              </div>
             </div>
+            <div class="clear"></div>
+
             {{! the SQL editor will show the first time you }}
             {{#if everEditing}}
               <div class="query-editor {{if hideSchema "no-schema"}}">
@@ -110,6 +114,9 @@
                 {{/unless}}
               {{/if}}
               {{d-button action=(action "download") label="explorer.export" disabled=runDisabled icon="download"}}
+              {{#if everEditing}}
+                {{d-button action=(action "showHelpModal") label="explorer.help.label" icon="question-circle"}}
+              {{/if}}
             </div>
             <div class="pull-right">
               {{#if selectedItem.destroyed}}
diff --git a/assets/javascripts/discourse/templates/modal/query-help.hbs b/assets/javascripts/discourse/templates/modal/query-help.hbs
new file mode 100644
index 0000000..0286621
--- /dev/null
+++ b/assets/javascripts/discourse/templates/modal/query-help.hbs
@@ -0,0 +1,6 @@
+{{#d-modal-body title="explorer.help.modal_title"}}
+  {{html-safe (i18n "explorer.help.auto_resolution")}}
+  {{html-safe (i18n "explorer.help.custom_params")}}
+  {{html-safe (i18n "explorer.help.default_values")}}
+  {{html-safe (i18n "explorer.help.data_types")}}
+{{/d-modal-body}}
diff --git a/config/locales/client.en.yml b/config/locales/client.en.yml
index 71488c0..e85b44a 100644
--- a/config/locales/client.en.yml
+++ b/config/locales/client.en.yml
@@ -14,11 +14,39 @@ en:
       import:
         label: "Import"
         modal: "Import A Query"
+      help:
+        label: "Help"
+        modal_title: "Data Explorer Help"
+        auto_resolution: "<h2>Automatic Entity Resolution</h2>
+          <p>When your query returns an entity id, Data Explorer may automatically substitute it with
+          the entity name and other useful information in query results. Automatic resolution is available for
+          <i><b>user_id</b></i>, <i><b>group_id</b></i>, <i><b>topic_id</b></i>, <i><b>category_id</b></i>
+          and <i><b>badge_id</b></i>. To try this out run this query:</p>
+          <pre><code>SELECT user_id\nFROM posts</code></pre>"
+        custom_params: "<h2>Creating Custom Parameters</h2>
+          <p>To create custom parameters for your queries, put this at the top of your query and follow the format:</p>
+          <pre><code>-- [params]\n-- int :num = 1\n\nSELECT :num</code></pre>
+          <p><i>Note: the first line with [params] is required, along with two dashes preceding it and every
+          custom parameter you want to declare.</i></p>"
+        default_values: "<h3>Default Values</h3>
+          <p>You can declare parameters with or without default values. Default values will show up in a text field
+          below the query editor, which you can edit to your needs. Parameters declared without default values will
+          still generate a text field, but will be empty and highlighted red.</p>
+          <pre><code>-- [params]\n-- text :username = my_username\n-- int :age</code></pre>"
+        data_types: "<h3>Data Types</h3>
+          <p>Here are common data types you can use:</p>
+          <ul>
+            <li><b>integer</b> - signed four-byte Integer</li>
+            <li><b>text</b> - variable-length character string</li>
+            <li><b>boolean</b> – true/false</li>
+            <li><b>date</b> - calendar date (year, month, day)</li>
+          </ul>
+          <p>For more information on data types, visit
+          <a href='http://www.postgresql.org/docs/9.3/static/datatype.html#DATATYPE-TABLE' target='_blank'>this website</a>.</p>"
       schema:
         title: "Database Schema"
         filter: "Search..."
         sensitive: "The contents of this column may contain particularly sensitive or private information. Please exercise caution when using the contents of this column."
-        type_help: "<a href='http://www.postgresql.org/docs/9.3/static/datatype.html#DATATYPE-TABLE' target='_blank'>Types</a>"
       types:
         bool:
           yes: "Yes"