card-mod-follow 0.11.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0f81b70d3b7b7b739342e05f5bbc648ba4b7ae85c6f388f4f1cfe2065b1ef6be
+  data.tar.gz: 793b238cbd0c52ade5746a36ea734f4421de793d328ab8699aa84b25c29d2c58
+SHA512:
+  metadata.gz: 27bdb26be87cf868403b91cc332514ca043a21af76f9dd129a1fe2300f40f54a881a56dcb081693e92ca99ed939ba408a819e11b1589a85a5a35e1a7be2176b9
+  data.tar.gz: 66299e2fe971aedf324afc968b278c31845e82b95c2c3ab0fa0e0600571fac5a18d16426f7551988460bb37bf1a61dea8e3d1f84866bce664ca83e8d211bff8d

data/README.md

@@ -0,0 +1,134 @@
+<!--
+# @title README - mod: follow
+-->
+# Follow
+
+Follow sets cards, get notified when any card in the set changes.
+
+## Sets
+
+Cards ruling notifications include:
+
+### Follow preferences (or follow rules)
+
+| name | type | content |
+|:----:|:----:|:-------:|
+| [Set]+[User]+:follow | Pointer | list of follow options |
+
+Each rule determines cases in which the _User_ should be notified about changes to the _Set_.
+
+These cards have special permission handling, granting full permission to the _User_.
+
+Special views include:
+
+- *follow_item*
+- *follow_status*
+
+### Follow options
+
+| name | type | content |
+|:----:|:----:|:-------:|
+| \*_optionname_| Basic | (blank) |
+
+Each follow preference can point to one or more of the following follow options.
+
+- _always:_ notify user after every create, update, and delete 
+- _never:_ do not notify user
+- _created:_ notify user when a card is created
+- _edited:_ notify user when a card is created or updated
+
+### Follow dashboard
+
+| name | type | content |
+|:----:|:----:|:-------:|
+| [User]+:follow | Pointer(virtual) | list of sets |
+
+Core view shows Follow and Ignore tabs.  Each tab has a list of the 
+user's preferences in `follow_item` view. Navigate to this card via the
+card submenu (`account > follow`).
+
+Special views include:
+- *follow_tab*
+- *ignore_tab*
+
+### Follow suggestions
+
+| name | type | content |
+|:----:|:----:|:-------:|
+| :follow_suggestions | Pointer | list of follow settings |
+
+This advanced global setting lets sharks determine what suggestions will appear on the
+follow dashboard.  Any item not currently followed will be suggested.
+
+Each suggestion can take the form of either `[Set]` or `[Set]+[Follow Option]`.
+
+### Following status
+
+| name | type | content |
+|:----:|:----:|:-------:|
+| +:following | Pointer(virtual) | card's follow status for current user |
+
+With this card, users can see and/or edit whether they are following the 
+card in question.
+
+This view is seen via the "follow" item in the main card menu or via
+`activity > follow` in the submenu.
+
+Special views include:
+- _core_ a follow edit interface if signed in
+- _status_
+
+### Followers
+
+| name | type | content |
+|:----:|:----:|:-------:|
+| +:followers | Pointer(virtual) | list of users |
+
+User who are following the card in question.
+
+(not integrated into interface)
+
+### Email template
+
+| name | type | content |
+|:----:|:----:|:-------:|
+|follower notification email|Email Template|(nested email config)|
+
+The _to_ field is handled automatically. All other fields can be sharked.
+
+Useful views added by this mod include:
+
+- _list_of_changes_ (updates coming soon)
+- _subedits:_ (updates coming soon)
+- _followed:_ label of set followed
+- _unfollow_url:_ link to remove the following rule that led to this email
+
+### Follow fields
+
+| name | type | content |
+|:----:|:----:|:-------:|
+| [Set]+:follow_fields | Pointer (rule) | list of fields |
+
+These rules rules are advanced configuration that let sharks determine which of a card’s fields
+are automatically followed when a user follow that card.
+
+The default value is `:includes`, which means that nested cards are followed by default.
+
+## Lib
+
+### Card::FollowerStash
+
+A class for stashing followers of a given card.
+
+### Card::FollowOption
+
+A module for tracking and grouping follow options and their processing code.
+
+
+## TODO
+- review / address follow references in:
+  - rich_html/
+    - menu
+    - toolbar
+  - all/rules
+  

data/lib/card/follow_option.rb

@@ -0,0 +1,33 @@
+# -*- encoding : utf-8 -*-
+
+class Card
+  # module to be included in cards used as options for follow rules
+  module FollowOption
+    # Hash containing an applicability test for each option (block)
+    @test = {}
+    # Hash containing an id-list-generating block for each option
+    @follower_candidate_ids = {}
+    # Hash that registers / groups options
+    @options = { all: [], main: [], restrictive: [] }
+
+    class << self
+      attr_reader :test, :follower_candidate_ids, :options
+
+      def codenames type=:all
+        options[type]
+      end
+
+      def cards
+        codenames.map { |codename| Card[codename] }
+      end
+
+      def restrictive_options
+        codenames :restrictive
+      end
+
+      def main_options
+        codenames :main
+      end
+    end
+  end
+end

data/lib/card/follower_stash.rb

@@ -0,0 +1,88 @@
+class Card
+  # stash followers of a given card
+  class FollowerStash
+    def initialize card=nil
+      @stash = Hash.new { |h, v| h[v] = [] }
+      @checked = ::Set.new
+      check_card(card) if card
+    end
+
+    def check_card card
+      return if @checked.include? card.key
+
+      Auth.as_bot do
+        @checked.add card.key
+        stash_direct_followers card
+        stash_field_followers card.left
+      end
+    end
+
+    def followers
+      @stash.keys
+    end
+
+    def each_follower_with_reason
+      # "follower"(=user) is a card object, "followed"(=reasons) a card name
+      @stash.each do |follower_card, reasons|
+        yield(follower_card, reasons.first)
+      end
+    end
+
+    private
+
+    def stash_direct_followers card
+      card.each_direct_follower_id_with_reason do |user_id, reason|
+        stash Card.fetch(user_id), reason
+      end
+    end
+
+    def stash_field_followers card
+      return unless (fields = follow_fields card)
+
+      fields.each do |field|
+        break if stash_field_follower card, field
+      end
+    end
+
+    def stash_field_follower card, field
+      return false unless checked?(field.to_name) || nested?(card, field)
+
+      check_card card
+      true
+    end
+
+    def nested? card, field
+      return unless field.to_name.key == includes_card_key
+
+      @checked.intersection(nestee_set(card)).any?
+    end
+
+    def includes_card_key
+      @includes_card_key ||= :nests.cardname.key
+    end
+
+    def nestee_set card
+      @nestee_set ||= {}
+      @nestee_set[card.key] ||= nestee_search card
+    end
+
+    def nestee_search card
+      Card.search({ return: "key", included_by: card.name },
+                  "follow cards included by #{card.name}")
+    end
+
+    def checked? name
+      @checked.include? name.key
+    end
+
+    def follow_fields card
+      return unless card && !checked?(card.name)
+
+      card.rule_card(:follow_fields)&.item_names(context: card.name)
+    end
+
+    def stash follower, reason
+      @stash[follower] << reason
+    end
+  end
+end

data/set/abstract/follow_option.rb

@@ -0,0 +1,56 @@
+def restrictive_option?
+  Card::FollowOption.restrictive_options.include? codename
+end
+
+def description set_card
+  set_card.follow_label
+end
+
+# follow option methods on the Card class
+# FIXME: there's not a great reason to have these on the Card class
+module ClassMethods
+  # args:
+  # position: <Fixnum> (starting at 1, default: add to end)
+  def restrictive_follow_opts args
+    add_option args, :restrictive
+  end
+
+  # args:
+  # position: <Fixnum> (starting at 1, default: add to end)
+  def follow_opts args
+    add_option args, :main
+  end
+
+  def follow_test opts={}, &block
+    Card::FollowOption.test[get_codename(opts)] = block
+  end
+
+  def follower_candidate_ids opts={}, &block
+    Card::FollowOption.follower_candidate_ids[get_codename(opts)] = block
+  end
+
+  private
+
+  def insert_option pos, item, type
+    list = Card::FollowOption.codenames(type)
+    list[pos] ? list.insert(pos, item) : (list[pos] = item)
+    # If pos > codenames.size in a previous insert then we have a bunch
+    # of preceding nils in the array.
+    # Hence, we have to overwrite a nil value if we encounter one and
+    # can't use insert.
+  end
+
+  def add_option opts, type, &_block
+    codename = get_codename opts
+    if opts[:position]
+      insert_option opts[:position] - 1, codename, type
+    else
+      Card::FollowOption.codenames(type) << codename
+    end
+    Card::FollowOption.codenames(:all) << codename
+  end
+
+  def get_codename opts
+    opts[:codename] || name.match(/::(\w+)$/)[1].underscore.to_sym
+  end
+end

data/set/all/follow.rb

@@ -0,0 +1,33 @@
+# for override
+def followable?
+  true
+end
+
+def follow_label
+  name
+end
+
+def list_direct_followers?
+  false
+end
+
+def follow_option?
+  codename && FollowOption.codenames.include?(codename)
+end
+
+# the set card to be followed if you want to follow changes of card
+def follow_set_card
+  Card.fetch name, :self
+end
+
+def follow_rule_name user=nil
+  follow_set_card&.follow_rule_name user
+end
+
+def follow_rule_card user=nil, args={}
+  Card.fetch follow_rule_name(user), args
+end
+
+def follow_rule? user=nil
+  Card.exists? follow_rule_name(user)
+end

data/set/all/follow/follow_link.rb

@@ -0,0 +1,61 @@
+#! no set module
+class FollowLink
+  attr_reader :format, :rule_content, :link_text, :action, :css_class, :hover_text
+
+  delegate :link_to, to: :format
+
+  def initialize format
+    @format = format
+    @card = format.card
+  end
+
+  def modal_link icon=false
+    opts = link_opts.merge(
+      "data-path": link_opts[:path],
+      "data-toggle": "modal",
+      "data-target": "#modal-#{card.name.safe_key}",
+      class: css_classes("follow-link", link_opts[:class])
+    )
+    link_to render_link_text(icon), opts
+  end
+
+  def button
+    opts = link_opts(:follow_section).merge(
+      remote: true,
+      class: @format.css_classes("follow-link", link_opts[:class],
+                                 "slotter btn btn-sm btn-primary")
+    )
+    opts["data-update-foreign-slot"] = ".d0-card-body > .card-slot.RIGHT-Xfollower.content-view"
+    opts["data-hover-text"] = hover_text if hover_text
+    link_to render_link_text, opts
+  end
+
+  def link_opts success_view=:follow_status
+    { title: title,
+      path: path(success_view),
+      class: css_class }
+  end
+
+  def render_link_text icon=false
+    verb = %(<span class="follow-verb">#{link_text}</span>)
+    icon = icon ? icon_tag(:flag) : ""
+    [icon, verb].compact.join.html_safe
+  end
+
+  private
+
+  def mark
+    @card.follow_set_card.follow_rule_name Auth.current.name
+  end
+
+  def path view=:follow_status
+    @format.path mark: mark,
+                 action: :update,
+                 success: { id: @card.name, view: view },
+                 card: { content: "[[#{rule_content}]]" }
+  end
+
+  def title
+    "#{action} emails about changes to #{@card.follow_label}"
+  end
+end

data/set/all/follow/follow_link_views.rb

@@ -0,0 +1,29 @@
+format do
+  def follow_link_class
+    card.followed? ? StopFollowLink : StartFollowLink
+  end
+
+  def show_follow?
+    Auth.signed_in? && !card.new_card? && card.followable?
+  end
+end
+
+format :json do
+  view :follow_status do
+    follow_link_class.link_opts
+  end
+end
+
+format :html do
+  def follow_button
+    follow_link_class.new(self).button
+  end
+
+  def follow_modal_link
+    follow_link_class.new(self).modal_link
+  end
+
+  view :follow_button, cache: :never do
+    follow_button
+  end
+end