dokno 1.1.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: df8bbd2d17e134f0298f31fc97d049b245c4830e9d44655a8c4659507c6ebe6f
-  data.tar.gz: bdeb9513295036198a8f30a476a1ea8a4c34d35330c9e6e75e2364aadddf0b3b
+  metadata.gz: f136bc4f785f0f392e5e76d19b55d74ae59f59f96f144049cb9e288aaaaeced5
+  data.tar.gz: 117835447f5ef02db4c18de8453f7053a977cec6349528a6b3d15250da42ae0a
 SHA512:
-  metadata.gz: 97c1353f3c85e9a6e40de60a0947101978bb101b0dc85be48945ee7e54bb13596fd0f1afbd011113f538c5dfe0ed8784c09c87643b5813e5021292c49244273b
-  data.tar.gz: 1bfda031b688b21b65fc8b43fd550e006fec2d5b5f1fd50d4f536db9724ef4853ed47f49e8b2e3ed3329f9ecd6092eb2d678dc6562fa1c07d092da0412ff1e12
+  metadata.gz: a49495dd1c51f2eac0508d8df2a7bc34f97a8f7cfa2699f36a3cebfbcc3b5012c7ccf80f1bcc730815a644b08ac4021e02fa0f5fd2b39bac1c86d8c0cbbed13b
+  data.tar.gz: ebe01549788e0f4ab21eb36b1b11a0b7d21518dc4626cba64543e6c3ca66a6de8ea7bc311df6490489df22f51f239b0cb544af79bb2ce7af146a6938be829b8b

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,24 +74,9 @@ 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();
-  }
-  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();
-  }
-  sendRequest(dokno__base_path + 'article_status', { slug: slug, active: true }, callback, 'POST');
+function setArticleStatus(slug, active) {
+  const callback = function(_data) { reloadPage(); }
+  sendRequest(dokno__base_path + 'article_status', { slug: slug, active: active }, callback, 'POST');
 }
 
 function deleteArticle(id) {
@@ -123,18 +152,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);
@@ -153,3 +170,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

@@ -5,6 +5,6 @@ module Dokno
     include UserConcern
     include PaginationConcern
 
-    add_flash_types :green, :yellow, :red
+    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,7 +39,7 @@ module Dokno
       set_editor_username
 
       if @article.save
-        flash[:green] = 'Article was created'
+        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
@@ -44,12 +56,14 @@ module Dokno
       set_editor_username
 
       if @article.update(article_params)
-        flash[:green] = 'Article was updated'
+        flash[:green]       = 'Article was updated'
         @article.categories = Category.where(code: params[:category_code])
         redirect_to article_path @article.slug
       else
-        flash.now[:red] = 'Article could not be updated'
-        @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
@@ -79,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

@@ -6,11 +6,14 @@ module Dokno
     before_action :fetch_category, only: [:index, :edit, :update]
 
     def index
-      @search_term = params[:search_term]
-      @order       = params[:order]&.strip
-      @order       = 'updated' unless %w(updated newest views alpha).include?(@order)
+      @search_term        = params[:search_term]
+      @order              = params[:order]&.strip
+      @order              = 'updated' unless %w(updated newest views alpha).include?(@order)
+      @show_up_for_review = can_edit? && !request.path.include?(up_for_review_path)
 
-      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 +25,7 @@ module Dokno
     end
 
     def new
-      @category = Category.new
+      @category             = Category.new
       @parent_category_code = params[:parent_category_code]
     end
 
@@ -38,7 +41,7 @@ module Dokno
         flash[:green] = 'Category was created'
         redirect_to article_index_path(@category.code)
       else
-        flash.now[:red] = 'Category could not be created'
+        flash.now[:red]       = 'Category could not be created'
         @parent_category_code = params[:parent_category_code]
         render :new
       end
@@ -51,7 +54,7 @@ module Dokno
         flash[:green] = 'Category was updated'
         redirect_to article_index_path(@category.code)
       else
-        flash.now[:red] = 'Category could not be updated'
+        flash.now[:red]       = 'Category could not be updated'
         @parent_category_code = params[:parent_category_code]
         render :edit
       end

data/app/controllers/dokno/pagination_concern.rb

@@ -3,11 +3,11 @@ module Dokno
     extend ActiveSupport::Concern
 
     def paginate(records, max_per_page: 10)
-      @page           = params[:page].to_i
-      @total_records  = records.size
-      @total_pages    = (@total_records.to_f / max_per_page).ceil
-      @total_pages    = 1 unless @total_pages.positive?
-      @page           = 1 unless @page.positive? && @page <= @total_pages
+      @page          = params[:page].to_i
+      @total_records = records.size
+      @total_pages   = (@total_records.to_f / max_per_page).ceil
+      @total_pages   = 1 unless @total_pages.positive?
+      @page          = 1 unless @page.positive? && @page <= @total_pages
 
       records.offset((@page - 1) * max_per_page).limit(max_per_page)
     end

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,14 +17,18 @@ 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 false unless user.respond_to? Dokno.config.app_user_auth_method.to_sym
+      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)
     end

data/app/helpers/dokno/application_helper.rb

@@ -9,7 +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 class="dokno-link" href="javascript:;" onclick="doknoOpenPanel('#{j article.slug}');">#{link_text.presence || article.title}</a>).html_safe
     end
   end
 end

data/app/models/dokno/application_record.rb

@@ -1,5 +1,8 @@
 module Dokno
   class ApplicationRecord < ActiveRecord::Base
     self.abstract_class = true
+
+    include Engine.routes.url_helpers
+    include ActionView::Helpers::DateHelper
   end
 end

data/app/models/dokno/article.rb

@@ -3,9 +3,6 @@ require 'redcarpet'
 
 module Dokno
   class Article < ApplicationRecord
-    include Engine.routes.url_helpers
-    include ActionView::Helpers::DateHelper
-
     has_and_belongs_to_many :categories
     has_many :logs, dependent: :destroy
     has_many :article_slugs, dependent: :destroy
@@ -15,18 +12,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 +42,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
@@ -52,7 +73,10 @@ module Dokno
         .where(dokno_articles_categories: { article_id: id })
         .all
         .map do |category|
-          "<a class='underline' href='#{article_index_path(category.code)}?search_term=#{CGI.escape(search_term.to_s)}&order=#{CGI.escape(order.to_s)}'>#{category.name}</a>" if context_category_id != category.id
+          next if context_category_id == category.id
+
+          "<a class='underline' href='#{article_index_path(category.code)}?search_term="\
+          "#{CGI.escape(search_term.to_s)}&order=#{CGI.escape(order.to_s)}'>#{category.name}</a>"
         end.compact
 
       return '' if names.blank?
@@ -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 })
-
-      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
-    end
+        .where(active: true)
+        .where('review_due_at <= ?', Date.today + Dokno.config.article_review_prompt_days)
 
-    def self.parse_markdown(content)
-      ActionController::Base.helpers.sanitize(
-        MARKDOWN_PARSER.render(content),
-        tags:       Dokno.config.tag_whitelist,
-        attributes: Dokno.config.attr_whitelist
-      )
+      apply_sort(records, order: order)
     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