dokno 1.0.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '08352501c3a71f5edef7bd7bf311d8459dc5d38adc20dff5540f755bf04033b6'
-  data.tar.gz: 19aedf91902b6fc6e30378074740578c347041702d849999a7c62c4a0fff53cd
+  metadata.gz: edd6bc7f282e312599b5d844e48382a5eff63604c13b05d41859c1beb587e878
+  data.tar.gz: b692a98a50654ae4d7d7a77b123289da686ab37131a0bbdf0f4ffc9151b5a1ab
 SHA512:
-  metadata.gz: f44728981b2004cb703d75641f72f02dc0cf4e92b697ae10d8ef69f1e1b099aa536499c139ae6931748331bbfe3c77bbcbeb3395e59b7fa99398aaeb45b25761
-  data.tar.gz: 32a8b4f6cbf26d8ef35a6894e3d668f10b81f085c47b65fa44abba17fec7fa337c7e917a532af45bf258c80ecdf869c3ec48cdd6386f96e3e029e3100ee84776
+  metadata.gz: ce6b652432db90585a4b72fe2327a5201409d9872c3408b74d7e5a52253d960b2ce1286fad4c762e09f2d4b72134d49174c4bbe3d4fc02203de1b3d95cc8077c
+  data.tar.gz: ae70e70feb6f78cc30daf751085ef58f50a26b45c9faa1276b5723fdb685c08ada77ff02ba5dee1a781a90c3852d0822702e7a410a2e952baef1545ded3408b2

data/README.md

@@ -36,11 +36,11 @@ To enable [in-context articles](#in-context-article-links) in your app, add the
 <%= render 'dokno/article_panel' %>
 ```
 
-## Screenshots
+### Configuration
 
-| Landing Page  | Article | Editing an Article  | Article Flyout |
-| ------------- | ------------- | ------------- | ------------- |
-| <img src="./README/landing_page.png" width="250"> | <img src="./README/article.png" width="250"> | <img src="./README/article_edit.png" width="250"> | <img src="./README/host_app_flyout.png" width="250"> |
+#### Dokno Settings
+
+Running `rails g dokno:install` creates `/config/initializers/dokno.rb` within your app, containing the available Dokno configuration options. Remember to restart your app whenever you make configuration changes.
 
 ### Articles
 
@@ -72,8 +72,6 @@ Clicking a link fetches the article asynchronously and reveals it to the user vi
 
     <%= dokno_article_link({link-text}, slug: {unique-article-slug}) %>
 
-<img src="./README/host_app_flyout.png" width="50%">
-
 ### Dokno Data Querying
 You typically won't need to interact with Dokno data directly, but it is stored within your database and is accessible via ActiveRecord as is any other model.
 
@@ -119,6 +117,8 @@ $ bundle exec rspec
 ```
 
 ## Hat Tips
+- [tailwindcss](https://tailwindcss.com/)
+  - CSS framework
 - [diffy](https://github.com/samg/diffy)
   - Text diffing Ruby gem
 - [Feather Icons](https://github.com/feathericons/feather)

data/app/assets/javascripts/dokno.js

@@ -1,5 +1,23 @@
+const dokno__search_hotkey_listener = function(e) {
+  if (e.key === '/') { handleSearchHotKey(); }
+}
+
+function handleSearchHotKey() {
+  const search_input = elem('input#search_term');
+  search_input.focus();
+  search_input.select();
+}
+
+function enableSearchHotkey() {
+  document.addEventListener('keyup', dokno__search_hotkey_listener, false);
+}
+
+function disableSearchHotkey() {
+  document.removeEventListener('keyup', dokno__search_hotkey_listener, false);
+}
+
 function copyToClipboard(text) {
-  window.prompt('Copy to clipboard: CTRL+C, Enter', text);
+  window.prompt('Copy to clipboard: CTRL + C, Enter', text);
 }
 
 function elem(selector) {
@@ -10,6 +28,32 @@ function elems(selector) {
   return document.getElementsByClassName(selector);
 }
 
+function selectOption(id, value) {
+  var sel = elem('#' + id);
+  var opts = sel.options;
+
+  for (var opt, j = 0; opt = opts[j]; j++) {
+    if (opt.value == value) {
+      sel.selectedIndex = j;
+      break;
+    }
+  }
+}
+
+function applyCategoryCriteria(category_code, term, order) {
+  goToPage(dokno__base_path + category_code + '?search_term=' + term + '&order=' + order);
+}
+
+function goToPage(url) {
+  var param_join = url.indexOf('?') >= 0 ? '&' : '?';
+  location.href=url + param_join + '_=' + Math.round(new Date().getTime());
+}
+
+function reloadPage() {
+  window.onbeforeunload = function () { window.scrollTo(0, 0); }
+  location.reload();
+}
+
 function sendRequest(url, data, callback, method) {
   const request = new XMLHttpRequest();
   request.open(method, url, true);
@@ -30,23 +74,13 @@ function sendRequest(url, data, callback, method) {
   request.send(JSON.stringify(data));
 }
 
-function deactiveArticle(slug) {
-  const callback = function(_data) {
-    elem('button#article-deactivate-button').classList.add('hidden');
-    elem('div#article-deprecated-alert').classList.remove('hidden');
-    elem('button#article-activate-button').classList.remove('hidden');
-    reloadLogs();
-  }
+function deactivateArticle(slug) {
+  const callback = function(_data) { reloadPage(); }
   sendRequest(dokno__base_path + 'article_status', { slug: slug, active: false }, callback, 'POST');
 }
 
-function activeArticle(slug) {
-  const callback = function(_data) {
-    elem('button#article-activate-button').classList.add('hidden');
-    elem('div#article-deprecated-alert').classList.add('hidden');
-    elem('button#article-deactivate-button').classList.remove('hidden');
-    reloadLogs();
-  }
+function activateArticle(slug) {
+  const callback = function(_data) { reloadPage(); }
   sendRequest(dokno__base_path + 'article_status', { slug: slug, active: true }, callback, 'POST');
 }
 
@@ -61,6 +95,17 @@ function deleteArticle(id) {
   sendRequest(dokno__base_path + 'articles/' + id, {}, callback, 'DELETE');
 }
 
+function deleteCategory(id) {
+  if (!confirm('Delete Category\n\nThis will remove this category. Any articles in this category will become uncategorized and appear on the home page until re-categorized.')) {
+    return true;
+  }
+
+  const callback = function(_data) {
+    location.href = dokno__base_path;
+  }
+  sendRequest(dokno__base_path + 'categories/' + id, {}, callback, 'DELETE');
+}
+
 function previewArticleToggle() {
   const markdown = elem('div#dokno-content-container textarea#markdown').value;
   const callback = function(data) {
@@ -112,18 +157,6 @@ function toggleVisibility(selector_id) {
   initIcons();
 }
 
-function reloadLogs() {
-  var $log_container = elem('div#dokno-article-log-container');
-  var category_id = $log_container.getAttribute('data-category-id');
-  var article_id = $log_container.getAttribute('data-article-id');
-
-  const callback = function(markup) {
-    elem('div#dokno-article-log-container').innerHTML = markup;
-    initIcons();
-  }
-  sendRequest(dokno__base_path + 'article_log', { category_id: category_id, article_id: article_id }, callback, 'POST');
-}
-
 // Pass containers_selector as class name (no prefix)
 function highlightTerm(terms, containers_selector) {
   var containers = elems(containers_selector);
@@ -142,3 +175,22 @@ function highlightTerm(terms, containers_selector) {
 function wrapTermWithHTML(term) {
   return `<span title="Matching search term" class="dokno-search-term bg-yellow-300 text-gray-900 p-2 rounded mx-1">${term}</span>`
 }
+
+function setReviewForm() {
+  const reset_review_date_checkbox = elem('input#reset_review_date');
+  const review_notes_textarea = elem('textarea#review_notes');
+
+  if (!reset_review_date_checkbox) {
+    return true;
+  }
+
+  if (reset_review_date_checkbox.checked) {
+    review_notes_textarea.removeAttribute('disabled');
+    review_notes_textarea.classList.remove('cursor-not-allowed');
+    review_notes_textarea.focus();
+  } else {
+    review_notes_textarea.setAttribute('disabled', 'disabled');
+    review_notes_textarea.classList.add('cursor-not-allowed');
+    reset_review_date_checkbox.focus();
+  }
+}

data/app/assets/stylesheets/dokno/application.css

@@ -16,7 +16,7 @@
 
 /* Additional knowledgebase site styles that are not in tailwind */
 
-svg.feather {
+button svg.feather {
   vertical-align: sub;
 }
 

data/app/controllers/dokno/application_controller.rb

@@ -1,7 +1,10 @@
 module Dokno
   class ApplicationController < ::ApplicationController
     protect_from_forgery with: :exception
+
     include UserConcern
     include PaginationConcern
+
+    add_flash_types :green, :yellow, :red, :gray
   end
 end

data/app/controllers/dokno/articles_controller.rb

@@ -8,7 +8,19 @@ module Dokno
 
     def show
       redirect_to root_path if @article.blank?
+
       @search_term = params[:search_term]
+      @order       = params[:order]
+      @category    = Category.find_by(code: params[:cat_code].to_s.strip) if params[:cat_code].present?
+      @category    = @article.categories.first if @category.blank?
+
+      if !@article.active
+        flash.now[:yellow] = 'This article is no longer active'
+      elsif @article.up_for_review?
+        flash_msg = @article.review_due_days_string
+        flash_msg += " - <a href='#{edit_article_path(@article.slug)}' class='font-bold'>review it now</a>" if can_edit?
+        flash.now[:gray] = flash_msg
+      end
     end
 
     def new
@@ -27,9 +39,11 @@ module Dokno
       set_editor_username
 
       if @article.save
+        flash[:green]       = 'Article was created'
         @article.categories = Category.where(code: params[:category_code]) if params[:category_code].present?
         redirect_to article_path @article.slug
       else
+        flash.now[:red] = 'Article could not be created'
         @category_codes = params[:category_code]
         render :new
       end
@@ -42,16 +56,22 @@ module Dokno
       set_editor_username
 
       if @article.update(article_params)
+        flash[:green]       = 'Article was updated'
         @article.categories = Category.where(code: params[:category_code])
         redirect_to article_path @article.slug
       else
-        @category_codes = params[:category_code]
+        flash.now[:red]    = 'Article could not be updated'
+        @category_codes    = params[:category_code]
+        @reset_review_date = params[:reset_review_date]
+        @review_notes      = params[:review_notes]
         render :edit
       end
     end
 
     def destroy
       Article.find(params[:id].to_i).destroy!
+
+      flash[:green] = 'Article was deleted'
       render json: {}, layout: false
     end
 
@@ -73,16 +93,10 @@ module Dokno
       render json: {}, layout: false
     end
 
-    # Ajax-fetched article change log
-    def article_log
-      render partial: '/partials/logs',
-        locals: { article: Article.find_by(id: params[:article_id].to_i) }, layout: false
-    end
-
     private
 
     def article_params
-      params.permit(:slug, :title, :summary, :markdown)
+      params.permit(:slug, :title, :summary, :markdown, :reset_review_date, :review_notes, :starred)
     end
 
     def fetch_article

data/app/controllers/dokno/categories_controller.rb

@@ -10,7 +10,9 @@ module Dokno
       @order       = params[:order]&.strip
       @order       = 'updated' unless %w(updated newest views alpha).include?(@order)
 
-      articles = if @search_term.present?
+      articles = if request.path.include? up_for_review_path
+                   Article.up_for_review(order: @order&.to_sym)
+                 elsif @search_term.present?
                    Article.search(term: @search_term, category_id: @category&.id, order: @order&.to_sym)
                  elsif @category.present?
                    @category.articles_in_branch(order: @order&.to_sym)
@@ -22,7 +24,7 @@ module Dokno
     end
 
     def new
-      @category = Category.new
+      @category             = Category.new
       @parent_category_code = params[:parent_category_code]
     end
 
@@ -35,8 +37,10 @@ module Dokno
       @category = Category.new(name: params[:name], parent: Category.find_by(code: params[:parent_category_code]))
 
       if @category.save
+        flash[:green] = 'Category was created'
         redirect_to article_index_path(@category.code)
       else
+        flash.now[:red]       = 'Category could not be created'
         @parent_category_code = params[:parent_category_code]
         render :new
       end
@@ -46,13 +50,22 @@ module Dokno
       return redirect_to root_path if @category.blank?
 
       if @category.update(name: params[:name], parent: Category.find_by(code: params[:parent_category_code]))
+        flash[:green] = 'Category was updated'
         redirect_to article_index_path(@category.code)
       else
+        flash.now[:red]       = 'Category could not be updated'
         @parent_category_code = params[:parent_category_code]
         render :edit
       end
     end
 
+    def destroy
+      Category.find(params[:id].to_i).destroy!
+
+      flash[:green] = 'Category was deleted'
+      render json: {}, layout: false
+    end
+
     private
 
     def fetch_category

data/app/controllers/dokno/user_concern.rb

@@ -8,8 +8,6 @@ module Dokno
 
     def user
       # Attempt to eval the currently signed in 'user' object from the host app
-      sanitized_user_obj_string = Dokno.config.app_user_object.to_s.split(/\b/).first
-
       proc {
         $safe = 1
         eval sanitized_user_obj_string
@@ -19,13 +17,17 @@ module Dokno
       nil
     end
 
+    def sanitized_user_obj_string
+      Dokno.config.app_user_object.to_s.split(/\b/).first
+    end
+
     def username
       user&.send(Dokno.config.app_user_name_method.to_sym).to_s
     end
 
     def can_edit?
       # Allow editing by default if host app user object is not configured
-      return true  unless user.present?
+      return true  unless sanitized_user_obj_string.present?
       return false unless user.respond_to? Dokno.config.app_user_auth_method.to_sym
 
       user.send(Dokno.config.app_user_auth_method.to_sym)

data/app/helpers/dokno/application_helper.rb

@@ -9,9 +9,7 @@ module Dokno
 
       return "Dokno article slug '#{slug}' not found" if article.blank?
 
-      %Q(
-        <a href="javascript:;" onclick="doknoOpenPanel('#{j article.slug}');">#{link_text.presence || article.title}</a>
-      ).html_safe
+      %Q(<a href="javascript:;" onclick="doknoOpenPanel('#{j article.slug}');">#{link_text.presence || article.title}</a>).html_safe
     end
   end
 end

data/app/models/dokno/article.rb

@@ -15,18 +15,28 @@ module Dokno
     validates :title, length: { in: 5..255 }
     validate :unique_slug_check
 
+    attr_accessor :editor_username, :reset_review_date, :review_notes
+
+    before_save :set_review_date, if: :should_set_review_date?
     before_save :log_changes
     before_save :track_slug
 
-    scope :alpha_order,   -> { order(active: :desc, title: :asc) }
-    scope :view_order,    -> { order(active: :desc, views: :desc, title: :asc) }
-    scope :newest_order,  -> { order(active: :desc, created_at: :desc, title: :asc) }
-    scope :updated_order, -> { order(active: :desc, updated_at: :desc, title: :asc) }
-
-    attr_accessor :editor_username
+    scope :active,        -> { where(active: true) }
+    scope :alpha_order,   -> { order(active: :desc, starred: :desc, title: :asc) }
+    scope :views_order,   -> { order(active: :desc, starred: :desc, views: :desc, title: :asc) }
+    scope :newest_order,  -> { order(active: :desc, starred: :desc, created_at: :desc, title: :asc) }
+    scope :updated_order, -> { order(active: :desc, starred: :desc, updated_at: :desc, title: :asc) }
 
     MARKDOWN_PARSER = Redcarpet::Markdown.new(Redcarpet::Render::HTML, autolink: true, tables: true)
 
+    def review_due_at
+      super || (Date.today + 30.years)
+    end
+
+    def markdown
+      super || ''
+    end
+
     def reading_time
       minutes_decimal = (("#{summary} #{markdown}".squish.scan(/[\w-]+/).size) / 200.0)
       approx_minutes  = minutes_decimal.ceil
@@ -35,8 +45,22 @@ module Dokno
       "~ #{approx_minutes} minutes"
     end
 
-    def markdown
-      super || ''
+    def review_due_days
+      (review_due_at.to_date - Date.today).to_i
+    end
+
+    def up_for_review?
+      active && review_due_days <= Dokno.config.article_review_prompt_days
+    end
+
+    def review_due_days_string
+      if review_due_days.positive?
+        "This article is up for an accuracy / relevance review in #{review_due_days} #{'day'.pluralize(review_due_days)}"
+      elsif review_due_days.negative?
+        "This article was up for an accuracy / relevance review #{review_due_days.abs} #{'day'.pluralize(review_due_days)} ago"
+      else
+        "This article is up for an accuracy / relevance review today"
+      end
     end
 
     def markdown_parsed
@@ -111,34 +135,24 @@ module Dokno
         .to_sentence
     end
 
-    # All uncategorized Articles
-    def self.uncategorized(order: :updated)
+    # All articles up for review
+    def self.up_for_review(order: :updated)
       records = Article
         .includes(:categories_dokno_articles, :categories)
-        .left_joins(:categories)
-        .where(active: true, dokno_categories: { id: nil })
+        .where(active: true)
+        .where('review_due_at <= ?', Date.today + Dokno.config.article_review_prompt_days)
 
-      records = records.updated_order if order == :updated
-      records = records.newest_order  if order == :newest
-      records = records.view_order    if order == :views
-      records = records.alpha_order   if order == :alpha
-
-      records
+      apply_sort(records, order: order)
     end
 
-    def self.parse_markdown(content)
-      ActionController::Base.helpers.sanitize(
-        MARKDOWN_PARSER.render(content),
-        tags:       Dokno.config.tag_whitelist,
-        attributes: Dokno.config.attr_whitelist
-      )
-    end
-
-    def self.template
-      template_file = File.join(Rails.root, 'config', 'dokno_template.md')
-      return unless File.exist?(template_file)
+    # All uncategorized Articles
+    def self.uncategorized(order: :updated)
+      records = Article
+        .includes(:categories_dokno_articles, :categories)
+        .left_joins(:categories)
+        .where(dokno_categories: { id: nil })
 
-      File.read(template_file).to_s
+      apply_sort(records, order: order)
     end
 
     def self.search(term:, category_id: nil, order: :updated)
@@ -152,10 +166,7 @@ module Dokno
       .includes(:categories_dokno_articles)
       .includes(:categories)
 
-      records = records.updated_order if order == :updated
-      records = records.newest_order  if order == :newest
-      records = records.view_order    if order == :views
-      records = records.alpha_order   if order == :alpha
+      records = apply_sort(records, order: order)
 
       return records unless category_id.present?
 
@@ -169,6 +180,28 @@ module Dokno
         )
     end
 
+    def self.parse_markdown(content)
+      ActionController::Base.helpers.sanitize(
+        MARKDOWN_PARSER.render(content),
+        tags:       Dokno.config.tag_whitelist,
+        attributes: Dokno.config.attr_whitelist
+      )
+    end
+
+    def self.template
+      template_file = File.join(Rails.root, 'config', 'dokno_template.md')
+      return unless File.exist?(template_file)
+
+      File.read(template_file).to_s
+    end
+
+    def self.apply_sort(records, order: :updated)
+      order_scope = "#{order}_order"
+      return records unless records.respond_to? order_scope
+
+      records.send(order_scope.to_sym)
+    end
+
     private
 
     # Ensure there isn't another Article with the same slug
@@ -188,7 +221,7 @@ module Dokno
     end
 
     def log_changes
-      return if changes.blank?
+      return if changes.blank? && !reset_review_date
 
       meta_changes    = changes.with_indifferent_access.slice(:slug, :title, :active)
       content_changes = changes.with_indifferent_access.slice(:summary, :markdown)
@@ -206,10 +239,26 @@ module Dokno
         content[:after]  += values.last.to_s + ' '
       end
 
-      return unless meta.present?
+      if meta.present?
+        diff = Diffy::SplitDiff.new(content[:before].squish, content[:after].squish, format: :html)
+        logs << Log.new(username: editor_username, meta: meta.to_sentence, diff_left: diff.left, diff_right: diff.right)
+      end
+
+      # Reviewed for accuracy / relevance?
+      return unless reset_review_date
+
+      review_log = "Reviewed for accuracy / relevance. Next review date reset to #{review_due_at.to_date}."
+      review_log += " Review notes: #{review_notes.squish}" if review_notes.present?
+      logs << Log.new(username: editor_username, meta: review_log)
+    end
+
+    def should_set_review_date?
+      # User requested a reset or it's a new article w/out a review due date
+      reset_review_date || (!persisted? && review_due_at.blank?)
+    end
 
-      diff = Diffy::SplitDiff.new(content[:before].squish, content[:after].squish, format: :html)
-      logs << Log.new(username: editor_username, meta: meta.to_sentence, diff_left: diff.left, diff_right: diff.right)
+    def set_review_date
+      self.review_due_at = Date.today + Dokno.config.article_review_period
     end
   end
 end