guide 0.0.1 → 0.5.0

data/app/models/guide/content.rb

@@ -0,0 +1,28 @@
+class Guide::Content < Guide::Document
+  # The content in the Living Guide for your application is organised
+  # into a tree structure. This class is the root node of that tree.
+  # To add child nodes, use the following DSL:
+  #
+  # contains :child_node_name
+  #
+  # This example declares that the tree contains a child node named:
+  #
+  # Guide::Content::ChildNodeName
+  #
+  # You will still need to create a class for it.
+  #
+  # It is highly recommended that all of your content lives in the
+  # Guide::Content namespace or Guide will have trouble finding it!
+  #
+  # To specify options such as visibility, append them to the declaration:
+  #
+  # contains :child_node_name, :visibility => :unpublished
+  #
+  # Feel free to redeclare this class in your system at the following path:
+  #
+  # app/<whatever_you_want>/guide/content.rb
+  #
+  # The convention for the subdirectory in app/ is "documentation",
+  # but if you don't like that, you can use something else (even "models"!).
+  # You probably shouldn't use any other standard rails directories though.
+end

data/app/models/guide/default_authentication_system.rb

@@ -0,0 +1,13 @@
+class Guide::DefaultAuthenticationSystem
+  def user_signed_in?
+    false
+  end
+
+  def url_for_sign_in
+    ''
+  end
+
+  def url_for_sign_out
+    ''
+  end
+end

data/app/models/guide/default_authorisation_system.rb

@@ -0,0 +1,18 @@
+class Guide::DefaultAuthorisationSystem
+  def allow?(action)
+    true
+  end
+
+  def user_is_privileged?
+    allow?(:view_guide_unpublished) ||
+      allow?(:view_guide_restricted)
+  end
+
+  def valid_visibility_options
+    [
+      nil,
+      :unpublished,
+      :restricted,
+    ]
+  end
+end

data/app/models/guide/diplomat.rb

@@ -0,0 +1,60 @@
+class Guide::Diplomat
+  def initialize(session, params, default_locale)
+    @session = session
+    @params = params
+    @default_locale = default_locale
+  end
+
+  def negotiate_locale
+    store_new_locale_in_session if supported_locales.has_value? new_locale
+
+    best_locale
+  end
+
+  def supported_locales
+    Guide.configuration.supported_locales
+  end
+
+  def multiple_supported_locales?
+    supported_locales.keys.size > 1
+  end
+
+  def current_locale
+    if supported_locales.has_value? locale_from_session
+      locale_from_session
+    else
+      clear_locale_from_session
+      @default_locale
+    end
+  end
+
+  private
+
+  def best_locale
+    if supported_locales.has_value? temporary_locale
+      temporary_locale
+    else
+      current_locale
+    end
+  end
+
+  def new_locale
+    @params[:locale]
+  end
+
+  def temporary_locale
+    @params[:temp_locale]
+  end
+
+  def locale_from_session
+    @session[:guide_locale]
+  end
+
+  def store_new_locale_in_session
+    @session[:guide_locale] = new_locale
+  end
+
+  def clear_locale_from_session
+    @session.delete(:guide_locale)
+  end
+end

data/app/models/guide/document.rb

@@ -0,0 +1,20 @@
+class Guide::Document < Guide::Node
+  def template
+    partial || self.class.name.underscore
+  end
+
+  def partial
+  end
+
+  def stylesheets
+    Guide.configuration.default_stylesheets_for_documents
+  end
+
+  def javascripts
+    Guide.configuration.default_javascripts_for_documents
+  end
+
+  def can_be_rendered?
+    true
+  end
+end

data/app/models/guide/endpoint_stocktaker.rb

@@ -0,0 +1,94 @@
+class Guide::EndpointStocktaker
+  def initialize(starting_node:)
+    @starting_node = starting_node
+    @result = {}
+  end
+
+  def to_hash
+    @result.tap do
+      add_guide_content if @result.empty?
+    end
+  end
+
+  private
+
+  def add_guide_content
+    renderable_nodes.keys.each do |node_path|
+      node = monkey.fetch_node(node_path)
+      if node.node_type == :structure
+        add_structure(node_path: node_path, structure: node)
+      else
+        add_document(node_path: node_path)
+      end
+    end
+  end
+
+  def add_structure(node_path:, structure:)
+    structure.formats.each do |format|
+      structure.scenarios.keys.each do |scenario_id|
+        @result[endpoint_key(node_path, scenario_id: scenario_id, scenario_format: format)] = {
+          "path" => url_helpers.scenario_path(
+            :scenario_id => scenario_id,
+            :scenario_format => format,
+            :node_path => node_path,
+          )
+        }
+      end
+    end
+  end
+
+  def add_document(node_path:)
+    @result[endpoint_key(node_path)] = { "path" => url_helpers.node_path(node_path) }
+  end
+
+  def endpoint_key(node_path, scenario_id: nil, scenario_format: nil)
+    [
+      formatted_node_path(node_path),
+      formatted_scenario_id(scenario_id),
+      scenario_format,
+    ].compact.join('-')
+  end
+
+  def formatted_node_path(node_path)
+    node_path.gsub('/', '.')
+  end
+
+  def formatted_scenario_id(scenario_id)
+    scenario_id = scenario_id.to_s
+
+    case scenario_id.length
+    when 0
+      nil
+    when 1..50
+      scenario_id.to_s
+    else
+      "#{scenario_id.first(24)}..#{scenario_id.last(24)}"
+    end
+  end
+
+  def bouncer
+    @bouncer ||= BribedBouncer.new
+  end
+
+  def cartographer
+    Guide::Cartographer.new(bouncer)
+  end
+
+  def monkey
+    @monkey ||= Guide::Monkey.new(@starting_node, bouncer)
+  end
+
+  def renderable_nodes
+    cartographer.draw_paths_to_visible_renderable_nodes(starting_node: @starting_node)
+  end
+
+  def url_helpers
+    Guide::Engine.routes.url_helpers
+  end
+
+  class BribedBouncer
+    def user_can_access?(_)
+      true
+    end
+  end
+end

data/app/models/guide/errors.rb

@@ -0,0 +1,2 @@
+class Guide::Errors
+end

data/app/models/guide/errors/base.rb

@@ -0,0 +1,6 @@
+class Guide::Errors::Base < StandardError
+  # This class exists so that we can tell the difference between an error
+  # that is native to Guide and an error that has occurred
+  # outside of our domain. All explictly thrown errors in Guide
+  # should inherit from this.
+end

data/app/models/guide/errors/interface_violation.rb

@@ -0,0 +1,2 @@
+class Guide::Errors::InterfaceViolation < Guide::Errors::Base
+end

data/app/models/guide/errors/invalid_node.rb

@@ -0,0 +1,2 @@
+class Guide::Errors::InvalidNode < Guide::Errors::Base
+end

data/app/models/guide/errors/invalid_scenario.rb

@@ -0,0 +1,2 @@
+class Guide::Errors::InvalidScenario < Guide::Errors::Base
+end

data/app/models/guide/errors/invalid_visibility_option.rb

@@ -0,0 +1,2 @@
+class Guide::Errors::InvalidVisibilityOption < Guide::Errors::Base
+end

data/app/models/guide/errors/permission_denied.rb

@@ -0,0 +1,2 @@
+class Guide::Errors::PermissionDenied < Guide::Errors::Base
+end

data/app/models/guide/fixture.rb

@@ -0,0 +1,15 @@
+class Guide::Fixture
+  # Fixtures are used to generate content for your Living Guide
+  # that would otherwise be repetitive, such as view models that are used
+  # from multiple components. Declaring these in a single place is useful
+  # because it helps keep a consistent interface between the fake view models
+  # in the Living Guide and the real view models in your application.
+  #
+  # Feel free to override or redeclare this class if you want.
+  # Nothing in the Guide gem depends on it.
+  private
+
+  def self.image_path(image_name, extension)
+    Guide::Photographer.new(image_name, extension).image_path
+  end
+end

data/app/models/guide/fixtures.rb

@@ -0,0 +1,3 @@
+module Guide::Fixtures
+  # This file exists to help Rails autoload the fixtures directory
+end

data/app/models/guide/form_object.rb

@@ -0,0 +1,3 @@
+class Guide::FormObject < OpenStruct
+  include ActiveModel::Validations
+end

data/app/models/guide/monkey.rb

@@ -0,0 +1,47 @@
+class Guide::Monkey
+  def initialize(starting_node, bouncer)
+    @starting_node = starting_node
+    @bouncer = bouncer
+
+    ensure_starting_node_exists
+    ensure_user_can_access(@starting_node)
+  end
+
+  def fetch_node(node_path)
+    current_node = @starting_node
+
+    node_ids_along_path(node_path).each do |node_id|
+      current_node = current_node.child_nodes[node_id]
+      ensure_node_exists(current_node, node_id)
+      ensure_user_can_access(current_node)
+    end
+
+    current_node
+  end
+
+  private
+
+  def node_ids_along_path(node_path)
+    node_path.split("/").map {|node_id| node_id.to_sym }
+  end
+
+  def ensure_node_exists(node, node_id)
+    unless node.present?
+      raise Guide::Errors::InvalidNode,
+        I18n.t('.guide.monkey.invalid_node', :node_id => node_id)
+    end
+  end
+
+  def ensure_starting_node_exists
+    unless @starting_node.present?
+      raise Guide::Errors::InvalidNode,
+        I18n.t('.guide.monkey.invalid_starting_node')
+    end
+  end
+
+  def ensure_user_can_access(node)
+    unless @bouncer.user_can_access?(node)
+      raise Guide::Errors::PermissionDenied
+    end
+  end
+end

data/app/models/guide/nobilizer.rb

@@ -0,0 +1,9 @@
+class Guide::Nobilizer
+  def bestow_title(node_path)
+    node_path.split("/").collect(&:titleize).join(" » ").html_safe
+  end
+
+  def bestow_heritage(node_path)
+    node_path.split("/")[0...-1].collect(&:titleize).join(" » ").html_safe
+  end
+end

data/app/models/guide/node.rb

@@ -0,0 +1,67 @@
+class Guide::Node
+  class_attribute :child_nodes
+
+  def self.inherited(sub_class)
+    sub_class.child_nodes = {}
+  end
+
+  def self.contains(id, options = {})
+    child_nodes[id] = child_node_class(id).new(options)
+  end
+
+  def self.child_node_class(id)
+    child_node_class_name = "#{self}::#{id.to_s.camelize}"
+    child_node_class_name.constantize
+  rescue NameError => name_error
+    raise Guide::Errors::InvalidNode,
+      "I can't build the tree that backs Guide because I could not load the class #{child_node_class_name}.",
+      name_error.backtrace
+  end
+
+  attr_reader :id, :options
+
+  def initialize(options = {})
+    @id = infer_id_from_class_name
+    @options = options
+  end
+
+  def name
+    @id.to_s.titleize
+  end
+
+  def leaf_node?
+    self.child_nodes.empty?
+  end
+
+  def child_nodes
+    self.class.child_nodes
+  end
+
+  def ==(other)
+    self.class == other.class
+  end
+
+  def node_type
+    # for direct children, this will be :node
+    self.class.superclass.name.demodulize.underscore.to_sym
+  end
+
+  def can_be_rendered?
+    false
+  end
+
+  def view_model
+    Guide::ViewModel.new
+  end
+
+  def image_path(image_name, extension = "png")
+    Guide::Photographer.new(image_name, extension).image_path
+  end
+
+  private
+
+  def infer_id_from_class_name
+    # for example, Structures::Checkout::Page becomes :page
+    self.class.name.demodulize.underscore.to_sym
+  end
+end

data/app/models/guide/photographer.rb

@@ -0,0 +1,20 @@
+class Guide::Photographer
+  def initialize(image_name, extension = 'png')
+    @image_name = image_name
+    @extension = extension
+  end
+
+  def image_path
+    "#{asset_host}#{image_with_path_and_digest}"
+  end
+
+  private
+
+  def image_with_path_and_digest
+    ActionController::Base.helpers.image_path "guide/#{@image_name}.#{@extension}"
+  end
+
+  def asset_host
+    Rails.application.config.action_controller.asset_host || ""
+  end
+end