dokno 1.2.1 → 1.4.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1032443316f9af5efc5d9d858fc72977e246c3dc04bf411818b6313cd9eb274a
-  data.tar.gz: a079f1d09677c56750b2c9b0a9f438505a60d4727cfa9bc1e036b6ef94783dcc
+  metadata.gz: b7bb23e26c12040a861918b9fc7a74435f3e6e345d111b0eb457c172083f3d1f
+  data.tar.gz: 1af89eb96c33341f334a2c1cb518c1beef1ab5fc79f642dad54124e9dd2594bc
 SHA512:
-  metadata.gz: b58630386a83f001e2e3a49def7e14cb833de066724be74b44ca56b08494ff9a72994ea0c2e5f324b09832a2f8848921fd9fa1eb1a41e83f11e8aba166669438
-  data.tar.gz: 6f1cf01dcd513f4dc4ce57acc85ba7dcb42aaac06585431562bdf06c5f9c012e0ea8a0c7588974045ca1e14704e9d2630a68150c000a032e321bf0c70a61f0bd
+  metadata.gz: 45959d064c4ac8ae1c27f6bde29b270537ad239be879bb3e81be2cdcd415980c05af7a8411547726b7013167776a3e9803f1fa87eb30cbb87ffa9f3ebd05941d
+  data.tar.gz: 2d9de55b00e1bf287fdb2d456e704ae1a6b894128a351137d65b3d5b9dbd7f5f984c2fa24d58895e5c352707eb687c547e928ed5ff19ce93e79ac9d9d7fc4b70

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.
 

data/app/assets/javascripts/dokno.js

@@ -46,7 +46,7 @@ function applyCategoryCriteria(category_code, term, order) {
 
 function goToPage(url) {
   var param_join = url.indexOf('?') >= 0 ? '&' : '?';
-  location.href=url + param_join + '_=' + Math.round(new Date().getTime());
+  location.href = url + param_join + '_=' + Math.round(new Date().getTime());
 }
 
 function reloadPage() {
@@ -74,14 +74,9 @@ function sendRequest(url, data, callback, method) {
   request.send(JSON.stringify(data));
 }
 
-function deactivateArticle(slug) {
+function setArticleStatus(slug, active) {
   const callback = function(_data) { reloadPage(); }
-  sendRequest(dokno__base_path + 'article_status', { slug: slug, active: false }, callback, 'POST');
-}
-
-function activateArticle(slug) {
-  const callback = function(_data) { reloadPage(); }
-  sendRequest(dokno__base_path + 'article_status', { slug: slug, active: true }, callback, 'POST');
+  sendRequest(dokno__base_path + 'article_status', { slug: slug, active: active }, callback, 'POST');
 }
 
 function deleteArticle(id) {
@@ -175,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

@@ -14,7 +14,13 @@ module Dokno
       @category    = Category.find_by(code: params[:cat_code].to_s.strip) if params[:cat_code].present?
       @category    = @article.categories.first if @category.blank?
 
-      flash.now[:yellow] = 'This article is no longer active' unless @article.active
+      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
@@ -33,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
@@ -50,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
@@ -88,7 +96,7 @@ module Dokno
     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

@@ -28,7 +28,7 @@ module Dokno
     def can_edit?
       # Allow editing by default if host app user object is not configured
       return true  unless sanitized_user_obj_string.present?
-      return false unless user.respond_to? Dokno.config.app_user_auth_method.to_sym
+      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,19 +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 :active,        -> { where(active: true) }
-    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 :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
@@ -36,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
@@ -53,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?
@@ -112,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)
@@ -153,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?
 
@@ -170,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
@@ -189,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)
@@ -207,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