card 1.19.6 → 1.20.0

data/lib/card/view/fetch.rb

@@ -0,0 +1,109 @@
+class Card
+  class View
+    # Support context-aware card view caching.
+    #
+    # View definitions can contain cache settings that guide whether and how
+    # the view should be cached.
+    module Fetch
+      # fetching can result in one of three things:
+      # - simply yielding the initial render call
+      # - storing or retrieving the render to/from the cache
+      # - creating a stub within another render
+      #   (so that the stub may be rendered later)
+      def fetch &block
+        case cache_level
+        when :yield       then yield
+        when :cache_yield then cache_fetch(&block)
+        when :stub        then stub
+        end
+      end
+
+      # Each of the following represents an accepted value for cache
+      # directives on view definitions.  eg:
+      #   view :myview, cache: :standard do ...
+      #
+      # * *always* - store independent cached view, even if that means double
+      #   caching. (eg view is inside another one already being cached)
+      # * *standard* (default) cache independently or dependently, but
+      #   don't double cache
+      # * *never* don't ever cache this view
+      def cache_level
+        return :yield unless Cardio.config.view_cache
+        send "#{caching? ? 'dependent' : 'independent'}_cache_level"
+      end
+
+      # INDEPENDENT CACHING
+      # takes place on its own (not within another view being cached)
+
+      def independent_cache_level
+        independent_cache_ok? ? :cache_yield : :yield
+      end
+
+      def independent_cache_ok?
+        cache_setting != :never &&
+          foreign_live_options.empty? &&
+          clean_enough_to_cache?
+      end
+
+      # The following methods are shared by independent and dependent caching
+
+      # view-specific setting as set in view definition. (always, standard, or
+      # never)
+      def cache_setting
+        format.view_cache_setting requested_view
+      end
+
+      # altered view requests and altered cards are not cacheable
+      def clean_enough_to_cache?
+        requested_view == ok_view &&
+          !card.unknown? &&
+          !card.db_content_changed?
+        # FIXME: might consider other changes as disqualifying, though
+        # we should make sure not to disallow caching of virtual cards
+      end
+
+      # DEPENDENT CACHING
+      # handling of views rendered within another cached view.
+
+      def dependent_cache_level
+        level = dependent_cache_level_unvalidated
+        validate_stub if level == :stub
+        level
+      end
+
+      def dependent_cache_level_unvalidated
+        return :yield if ok_view == :too_deep
+        dependent_cache_ok? ? dependent_cache_setting : :stub
+      end
+
+      def dependent_cache_ok?
+        return false unless parent && clean_enough_to_cache?
+        return true if normalized_options[:skip_perms]
+        dependent_cacheable_permissible?
+      end
+
+      def dependent_cacheable_permissible?
+        case permission_task
+        when :none                  then true
+        when parent.permission_task then true
+        when Symbol                 then card.anyone_can?(permission_task)
+        else                             false
+        end
+      end
+
+      # task directly associated with the view in its definition via the
+      # "perms" directive
+      def permission_task
+        @permission_task ||= Card::Format.perms[requested_view] || :read
+      end
+
+      DEPENDENT_CACHE_LEVEL =
+        { always: :cache_yield, standard: :yield, never: :stub }.freeze
+
+      def dependent_cache_setting
+        level = DEPENDENT_CACHE_LEVEL[cache_setting]
+        level || raise("unknown cache setting: #{cache_setting}")
+      end
+    end
+  end
+end

data/lib/card/view/options.rb

@@ -0,0 +1,164 @@
+class Card
+  class View
+    # normalizes and manages standard view options
+    module Options
+      # option values are strings unless otherwise noted
+      @keymap = {
+        nest: [
+          :view,          # view to render
+          :show,          # render these views when optional
+          :hide,          # do render these views when optional
+          :nest_name,     # name as used in nest
+          :nest_syntax    # full nest syntax
+        ],
+        # note: show/hide can be single view (Symbol), list of views (Array),
+        # or comma separated views (String)
+        heir: [
+          :main,          # format object is page's "main" object (Boolean)
+          :home_view,     # view for slot to return to when no view specified
+          :edit_structure # use a different structure for editing (Array)
+
+        ],
+        both: [
+          :help,          # cue text when editing
+          :structure,     # overrides the content of the card
+          :title,         # overrides the name of the card
+          :variant,       # override the canonical version of the name with
+          #                 a different variant
+          :editor,        # inline_nests makes a form within standard content
+          #                 (Symbol)
+          :type,          # set the default type of new cards
+          :size,          # set an image size
+          :params,        # parameters for add button.  deprecate?
+          :items          # options for items (Hash)
+        ],
+        none: [
+          :skip_perms,  # do not check permissions for this view (Boolean)
+          :main_view
+        ]   # this is main view of page (Boolean)
+      }
+
+      class << self
+        attr_reader :keymap
+
+        # all standard option keys
+        def all_keys
+          @all_keys ||= keymap.each_with_object([]) { |(_k, v), a| a.push(*v) }
+        end
+
+        # keys whose values can be set by Wagneers in card nests
+        def nest_keys
+          @nest_keys ||= ::Set.new(keymap[:both]) + keymap[:nest]
+        end
+
+        # keys that follow simple standard inheritance pattern from parent views
+        def heir_keys
+          @heir_keys ||= ::Set.new(keymap[:both]) + keymap[:heir]
+        end
+      end
+
+      # There are two primary options hashes:
+      # - @normalized_options are determined upon initialization and do not
+      #   change after that.
+      # - @live_options are created during the "process" phase, and they can be
+      #   altered via the "voo" API at any time
+
+      attr_reader :normalized_options
+
+      def live_options
+        @live_options ||= process_live_options
+      end
+
+      # The following methods comprise the primary voo API.  They allow
+      # developers to read and write options dynamically
+
+      def items
+        live_options[:items] ||= {}
+      end
+
+      (heir_keys + [:nest_name, :nest_syntax] - [:items]).each do |option_key|
+        define_method option_key do
+          norm_method = "normalize_#{option_key}"
+          value = live_options[option_key]
+          try(norm_method, value) || value
+        end
+
+        define_method "#{option_key}=" do |value|
+          live_options[option_key] = value
+        end
+      end
+
+      def normalize_editor value
+        value && value.to_sym
+      end
+
+      # options to be used in data attributes of card slots (normalized options
+      # with standard keys)
+      def slot_options
+        normalized_options.select { |k, _v| Options.all_keys.include? k }
+      end
+
+      private
+
+      # option normalization includes standardizing options into a hash with
+      # symbols as keys, managing standard view inheritance, and special
+      # handling for main_views.
+      def normalize_options
+        @normalized_options = opts = options_to_hash @raw_options.clone
+        opts[:view] = @raw_view
+        inherit_from_parent if parent
+        opts[:main] = true if format.main?
+        @optional = opts.delete(:optional) || false
+        opts
+      end
+
+      # typically options are already a hash.  this also handles an array of
+      # hashes and nil.
+      def options_to_hash opts
+        case opts
+        when Hash  then opts
+        when Array then opts[0].merge opts[1]
+        when nil   then {}
+        else raise Card::Error, "bad view options: #{opts}"
+        end.deep_symbolize_keys!
+      end
+
+      # standard inheritance from parent view object
+      def inherit_from_parent
+        Options.heir_keys.each do |key|
+          parent_value = parent.live_options[key]
+          normalized_options[key] ||= parent_value if parent_value
+        end
+      end
+
+      def process_live_options
+        opts = @live_options = normalized_options.clone
+        opts.merge! format.main_nest_options if opts[:main_view]
+        # main_view is a live_option because it is important that it NOT be
+        # locked in the stub.  Otherwise the main card can only show one view.
+        process_default_options
+        opts
+      end
+
+      # This method triggers the default_X_args methods which can alter the
+      # @live_options hash both directly and indirectly (via the voo API)
+      def process_default_options
+        format.view_options_with_defaults requested_view, live_options
+      end
+
+      # "foreign" options are non-standard options.  They're allowed, but they
+      # prevent independent caching (and thus stubbing)
+      def foreign_options opts
+        opts.reject { |k, _v| Options.all_keys.include? k }
+      end
+
+      def foreign_normalized_options
+        @foreign_normalize_options ||= foreign_options normalized_options
+      end
+
+      def foreign_live_options
+        foreign_options live_options
+      end
+    end
+  end
+end

data/lib/card/view/stub.rb

@@ -0,0 +1,30 @@
+class Card
+  class View
+    # A "stub" is a placeholder for a card view. It can only be used in
+    # situations where the card identifier, known options, and nest mode
+    # comprise all the info needed to reproduce the view as intended
+    module Stub
+      def stub
+        "<card-view>#{stub_json}</card-view>"
+      end
+
+      def stub_json
+        JSON.generate stub_hash
+      end
+
+      def stub_hash
+        {
+          cast: card.cast,
+          options: normalized_options,
+          mode: format.mode
+        }
+      end
+
+      def validate_stub
+        return if foreign_normalized_options.empty?
+        raise "INVALID STUB: #{card.name}/#{ok_view}" \
+              " has foreign options: #{foreign_normalized_options}"
+      end
+    end
+  end
+end

data/lib/card/view/visibility.rb

@@ -0,0 +1,95 @@
+class Card
+  class View
+    # manages showing and hiding optional view renders
+    module Visibility
+      # tracks show/hide value for each view with an explicit setting
+      # eg  { toggle: :hide }
+      def viz_hash
+        @viz_hash ||= {}
+      end
+
+      # test methods
+
+      def hide? view
+        viz_hash[view] == :hide
+      end
+
+      def show? view
+        !hide? view
+      end
+
+      # write methods
+
+      def show *views
+        viz views, :show
+      end
+
+      def hide *views
+        viz views, :hide
+      end
+
+      # force write methods
+
+      def show! *views
+        viz views, :show, true
+      end
+
+      def hide! *views
+        viz views, :hide, true
+      end
+
+      # advanced write method
+      VIZ_SETTING = { show: :show, true => :show,
+                      hide: :hide, false => :hide, nil => :hide }
+
+      def viz views, setting, force=false
+        Array.wrap(views).each do |view|
+          view = view.to_sym
+          next if !force && viz_hash[view]
+          viz_hash[view] = VIZ_SETTING[setting]
+        end
+      end
+
+      def visible? view
+        unless viz_hash[view]
+          viz view, yield
+        end
+        show? view
+      end
+
+      # test whether main_view is optional
+      # (@optional is set in normalize_options
+      def optional?
+        return @optional unless @optional.nil?
+        @optional = detect_if_optional
+      end
+
+      # translate raw hide, show options (which can be strings, symbols,
+      # arrays, etc)
+      def process_visibility_options
+        viz_hash.reverse_merge! parent.viz_hash if parent
+        process_visibility live_options
+        viz requested_view, @optional if @optional && !viz_hash[requested_view]
+      end
+
+      # takes an options_hash and processes it to update viz_hash
+      def process_visibility options_hash
+        [:hide, :show].each do |setting|
+          list = viz_view_list options_hash.delete(setting)
+          viz list, setting, true
+        end
+      end
+
+      # translated show/hide setting into an array of views
+      def viz_view_list val
+        case val
+        when NilClass then []
+        when Array    then val
+        when String   then val.split(/[\s,]+/)
+        when Symbol   then [val]
+        else raise Card::Error, "bad show/hide argument: #{val}"
+        end.map { |view| View.canonicalize view }
+      end
+    end
+  end
+end

data/lib/cardio.rb

@@ -46,10 +46,10 @@ module Cardio
         token_expiry:           2.days,
         acts_per_page:          10,
         space_last_in_multispace: true,
-        closed_search_limit:    50,
+        closed_search_limit:    10,
 
         non_createable_types:   [%w(signup setting set)],
-        view_cache:             false,
+        view_cache: false,
 
         encoding:               "utf-8",
         request_logger:         false,
@@ -144,6 +144,7 @@ module Cardio
           list += Dir.glob path
         end
       end
+
       list.flatten
     end
   end

data/lib/cardio/schema.rb

@@ -17,14 +17,27 @@ module Cardio
     end
 
     def schema_mode type
-      new_suffix = Cardio.schema_suffix type
-      original_suffix = ActiveRecord::Base.table_name_suffix
-      ActiveRecord::Base.table_name_suffix = new_suffix
-      ActiveRecord::SchemaMigration.reset_table_name
-      paths = Cardio.migration_paths(type)
-      yield(paths)
-      ActiveRecord::Base.table_name_suffix = original_suffix
-      ActiveRecord::SchemaMigration.reset_table_name
+      with_suffix type do
+        paths = Cardio.migration_paths(type)
+        yield(paths)
+      end
+    end
+
+    def with_suffix type
+      return yield unless (new_suffix = Cardio.schema_suffix type) &&
+                          new_suffix.present?
+      original_name = ActiveRecord::Base.schema_migrations_table_name
+      ActiveRecord::Base.schema_migrations_table_name =
+        "#{original_name}#{new_suffix}"
+      ActiveRecord::SchemaMigration.table_name = "#{original_name}#{new_suffix}"
+      # ActiveRecord::Base.table_name_suffix = new_suffix
+      # ActiveRecord::SchemaMigration.reset_table_name
+      # original_suffix = ActiveRecord::Base.table_name_suffix
+      yield
+      ActiveRecord::Base.schema_migrations_table_name = original_name
+      ActiveRecord::SchemaMigration.table_name = original_name
+      # ActiveRecord::Base.table_name_suffix = original_suffix
+      # ActiveRecord::SchemaMigration.reset_table_name
     end
 
     def schema type=nil