sitepress-rails 2.0.0.beta4 → 2.0.0.beta9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 135962bb8c744104c2119d592dc46d33d3bf86d1f0138f9cc8484416770f776d
-  data.tar.gz: f9ec3cea5fb45637deef576515ecf039f943087d29c7d6255e2bf98070f7ede5
+  metadata.gz: 51637f7a749539e6a1fc3b23d4b295a477fc36231ff0ee9ad0bdfb4c00fadc6c
+  data.tar.gz: d30e8a536f64ce2b37ce4206907b2d18c60e974d82a540f444510fc0cee1b925
 SHA512:
-  metadata.gz: 8daefdf6dde16ba78128f812aa1d8fa2e0fc5cf0feeb639844207236d9226231925b7915908d1f31895eb306eabeae54c2c37a5e3e2026cd078b4745754128f7
-  data.tar.gz: af534c613a3d31f8dd7e61a7dd131bf01b71cd5915fe9b2ae2876b184ef9f68c715075d40d450fc7e07728c5779150bbbedf5224f07403859ca9fa8a48fb70e5
+  metadata.gz: d2f9e7f4270b2182d1a5a9347d1a4b4fce7db9cd088b5d0411e7dc0d33200daca1be262ba83a320cb6ce6eec1c50fe466d72856cad6d514473bcedae39ef3d8d
+  data.tar.gz: be42b1679592c410e1b30c05ca7118d568b6d4a8c4414b91dcbf984ffe105782ea9e28a9896eee4f5d25d81fe4e0c34d00faa85058a959f0e8caf4fdd8e381e3

data/lib/sitepress/build_paths/directory_index_path.rb

@@ -4,7 +4,7 @@ module Sitepress
     # hosts like S3. To achieve this effect, we have to compile `pages/blah.html.haml`
     # to a folder with the filename `index.html`, so the final path would be `/blah/index.html`
     class DirectoryIndexPath < IndexPath
-      def path_with_default_format
+      def filename_with_default_format
         File.join(node.name, "#{node.default_name}.#{format}")
       end
     end

data/lib/sitepress/build_paths/index_path.rb

@@ -4,16 +4,16 @@ module Sitepress
     # pages too, mainly grabbing the root, which doesn't have a name in the node, to the default_name
     # of the node, which is usually `index`.
     class IndexPath < RootPath
-      def path_without_format
+      def filename_without_format
         node.name
       end
 
-      def path_with_format
+      def filename_with_format
         "#{node.name}.#{format}"
       end
 
-      def path_with_default_format
-        path_with_format
+      def filename_with_default_format
+        filename_with_format
       end
     end
   end

data/lib/sitepress/build_paths/root_path.rb

@@ -13,27 +13,31 @@ module Sitepress
         @resource = resource
       end
 
-      def path
+      def filename
         if format.nil?
-          path_without_format
+          filename_without_format
         elsif format == node.default_format
-          path_with_default_format
+          filename_with_default_format
         elsif format
-          path_with_format
+          filename_with_format
         end
       end
 
+      def path
+        File.join(*resource.lineage, filename)
+      end
+
       protected
-      def path_without_format
+      def filename_without_format
         node.default_name
       end
 
-      def path_with_format
+      def filename_with_format
         "#{node.default_name}.#{format}"
       end
 
-      def path_with_default_format
-        path_with_format
+      def filename_with_default_format
+        filename_with_format
       end
     end
   end

data/lib/sitepress/compiler.rb

@@ -6,63 +6,63 @@ module Sitepress
   class Compiler
     include FileUtils
 
-    class ResourceCompiler
-      attr_reader :resource
+    attr_reader :site, :root_path
 
-      def initialize(resource)
-        @resource = resource
-      end
-
-      def compilation_path
-        File.join(*resource.lineage, compilation_filename)
-      end
+    # If a resource can't render, it will raise an exception and stop the compiler. Sometimes
+    # its useful to turn off errors so you can get through a full compilation and see how many
+    # errors you encounter along the way. To do that, you'd set `raise_exception_on_error` to
+    # `false` and the compile will get through all the resources.
+    attr_accessor :raise_exception_on_error
 
-      # Compiled assets have a slightly different filename for assets, especially the root node.
-      def compilation_filename(path_builder: BuildPaths::DirectoryIndexPath, root_path_builder: BuildPaths::RootPath)
-        path_builder = resource.node.root? ? root_path_builder : path_builder
-        path_builder.new(resource).path
-      end
-
-      def render(page)
-        Renderers::Server.new(resource).render
-      end
-    end
-
-    attr_reader :site
-
-    def initialize(site:, stdout: $stdout)
+    def initialize(site:, root_path:, stdout: $stdout, raise_exception_on_error: true)
       @site = site
       @stdout = stdout
+      @root_path = Pathname.new(root_path)
+      @raise_exception_on_error = raise_exception_on_error
     end
 
     # Iterates through all pages and writes them to disk
-    def compile(target_path:)
-      target_path = Pathname.new(target_path)
-      mkdir_p target_path
-      cache_resources = @site.cache_resources
-      @stdout.puts "Compiling #{@site.root_path.expand_path}"
+    def compile
+      status "Building #{site.root_path.expand_path} to #{root_path.expand_path}"
+      resources.each do |resource, path|
+        if resource.renderable?
+          status "Rendering #{path}"
+          File.open(path.expand_path, "w"){ |f| f.write render resource }
+        else
+          status "Copying #{path}"
+          cp resource.asset.path, path.expand_path
+        end
+      rescue
+        status "Error building #{resource.inspect}"
+        raise if raise_exception_on_error
+      end
+      status "Successful build to #{root_path.expand_path}"
+    end
+
+    private
+      def resources
+        Enumerator.new do |y|
+          mkdir_p root_path
 
-      begin
-        @site.cache_resources = true
-        @site.resources.each do |resource|
-          compiler = ResourceCompiler.new(resource)
-          path = target_path.join(compiler.compilation_path)
-          mkdir_p path.dirname
-          if resource.renderable?
-            @stdout.puts "  Rendering #{path}"
-            File.open(path.expand_path, "w"){ |f| f.write compiler.render(resource) }
-          else
-            @stdout.puts "  Copying #{path}"
-            FileUtils.cp resource.asset.path, path.expand_path
+          site.resources.each do |resource|
+            path = build_path resource
+            mkdir_p path.dirname
+            y << [resource, path]
           end
-        rescue => e
-          @stdout.puts "Error compiling #{resource.inspect}"
-          raise
         end
-        @stdout.puts "Successful compilation to #{target_path.expand_path}"
-      ensure
-        @site.cache_resources = cache_resources
       end
-    end
+
+      def build_path(resource)
+        path_builder = resource.node.root? ? BuildPaths::RootPath : BuildPaths::DirectoryIndexPath
+        root_path.join path_builder.new(resource).path
+      end
+
+      def render(resource)
+        Renderers::Server.new(resource).render
+      end
+
+      def status(message)
+        @stdout.puts message
+      end
   end
 end

data/lib/sitepress/engine.rb

@@ -20,26 +20,24 @@ module Sitepress
     # Load paths from `Sitepress#site` into rails so it can render views, helpers, etc. properly.
     initializer :set_sitepress_paths, before: :set_autoload_paths do |app|
       app.paths["app/helpers"].push site.helpers_path.expand_path
+      app.paths["app/assets"].push site.assets_path.expand_path
       app.paths["app/views"].push site.root_path.expand_path
       app.paths["app/views"].push site.pages_path.expand_path
     end
 
     # Configure sprockets paths for the site.
-    initializer :set_asset_paths, before: :append_assets_path do |app|
+    initializer :set_manifest_file_path, before: :append_assets_path do |app|
       manifest_file = sitepress_configuration.manifest_file_path.expand_path
-
-      if manifest_file.exist?
-        app.paths["app/assets"].push site.assets_path.expand_path
-        app.config.assets.precompile << manifest_file.to_s
-      else
-        Rails.logger.warn "WARNING: Sitepress could not enable Sprockets because it could not find a manifest file at #{manifest_file.to_s.inspect}."
-      end
+      app.config.assets.precompile << manifest_file.to_s if manifest_file.exist?
     end
 
     # Configure Sitepress with Rails settings.
     initializer :configure_sitepress do |app|
       sitepress_configuration.parent_engine = app
+      # Reloads entire site between requests for development environments
       sitepress_configuration.cache_resources = app.config.cache_classes
+      # Set the templates extensions (e.g. erb, haml) so that Sitepress can better parse paths.
+      Sitepress::Path.handler_extensions = ActionView::Template::Handlers.extensions
     end
 
     private

data/lib/sitepress/rails.rb

@@ -3,11 +3,12 @@ require "sitepress-core"
 module Sitepress
   autoload :Compiler,                 "sitepress/compiler"
   autoload :RailsConfiguration,       "sitepress/rails_configuration"
-  autoload :RouteConstraint,          "sitepress/route_constraint"
   module Renderers
     autoload :Controller,             "sitepress/renderers/controller"
     autoload :Server,                 "sitepress/renderers/server"
   end
+  autoload :Rendition,                "sitepress/rendition"
+  autoload :RouteConstraint,          "sitepress/route_constraint"
   module BuildPaths
     autoload :RootPath,               "sitepress/build_paths/root_path"
     autoload :IndexPath,              "sitepress/build_paths/index_path"
@@ -15,7 +16,10 @@ module Sitepress
   end
 
   # Rescued by ActionController to display page not found error.
-  PageNotFoundError = Class.new(StandardError)
+  ResourceNotFound = Class.new(StandardError)
+
+  # Raised when any of the Render subclasses can't render a page.
+  RenderingError = Class.new(RuntimeError)
 
   # Make site available via Sitepress.site from Rails app.
   def self.site

data/lib/sitepress/rails_configuration.rb

@@ -6,15 +6,15 @@ module Sitepress
     # Store in ./app/content by default.
     DEFAULT_SITE_ROOT = "app/content".freeze
 
-    attr_accessor :routes
+    attr_accessor :routes, :cache_resources
     attr_writer :site, :parent_engine
 
-    # Delegates configuration points into the Sitepress site.
-    extend Forwardable
-    def_delegators :site, :cache_resources, :cache_resources=, :cache_resources?
-
     def initialize
+      # Injects routes into parent apps routes when set to true. Set to false
+      # to inject routes manually.
       self.routes = true
+      # Caches sites between requests. Set to `false` for development environments.
+      self.cache_resources = true
     end
 
     def parent_engine

data/lib/sitepress/renderers/controller.rb

@@ -1,18 +1,20 @@
 module Sitepress
   module Renderers
+    # This would be the ideal way to render Sitepress resources, but there's a lot
+    # of hackery involved in getting it to work properly.
     class Controller
-      attr_reader :controller, :page
+      attr_reader :controller, :resource
 
-      def initialize(page, controller = SiteController)
+      def initialize(resource, controller = SiteController)
         @controller = controller
-        @page = page
+        @resource = resource
       end
 
       def render
-        renderer.render inline: page.body,
-          type: page.asset.template_extensions.last,
+        renderer.render inline: resource.body,
+          type: resource.handler,
           layout: resolve_layout,
-          content_type: page.mime_type.to_s
+          content_type: resource.mime_type.to_s
       end
 
       private
@@ -29,15 +31,15 @@ module Sitepress
         end
 
         def renderer
-          controller.renderer.new("PATH_INFO" => page.request_path)
+          controller.renderer.new("PATH_INFO" => resource.request_path)
         end
 
         def resolve_layout
-          return page.data.fetch("layout") if page.data.key? "layout"
+          return resource.data.fetch("layout") if resource.data.key? "layout"
           return layout unless has_layout_conditions?
 
           clause, formats = layout_conditions.first
-          format = page.format.to_s
+          format = resource.format.to_s
 
           case clause
           when :only

data/lib/sitepress/renderers/server.rb

@@ -1,21 +1,29 @@
 module Sitepress
   module Renderers
+    # Renders resources by invoking a rack call to the Rails application. From my
+    # experiments rendering as of 2021, this is the most reliable way to render
+    # resources. Rendering via `Renderers::Controller` has lots of various subtle issues
+    # that are surprising. People don't like surprises, so I opted to render through a
+    # slightly heavier stack.
     class Server
-      attr_reader :rails_app, :page
+      attr_reader :rails_app, :resource
 
-      def initialize(page, rails_app = Rails.application)
+      def initialize(resource, rails_app = Rails.application)
         @rails_app = rails_app
-        @page = page
+        @resource = resource
       end
 
       def render
         code, headers, response = rails_app.routes.call env
         response.body
+      rescue => e
+        raise RenderingError.new "Error rendering #{resource.request_path.inspect} at #{resource.asset.path.expand_path.to_s.inspect}:\n#{e.message}"
       end
 
+      private
       def env
         {
-          "PATH_INFO"=> page.request_path,
+          "PATH_INFO"=> resource.request_path,
           "REQUEST_METHOD"=>"GET",
           "rack.input" => "GET"
         }

data/lib/sitepress/rendition.rb

@@ -0,0 +1,28 @@
+module Sitepress
+  # Encapsulates the data needed to render a resource from a controller. This
+  # lets us keep the functions in the controller more functional, which makes them
+  # easier to override by the end users.
+  class Rendition
+    attr_accessor :resource, :output, :controller_layout
+
+    def initialize(resource)
+      @resource = resource
+    end
+
+    def mime_type
+      resource.mime_type.to_s
+    end
+
+    def handler
+      resource.handler
+    end
+
+    def source
+      resource.body
+    end
+
+    def layout
+      resource.data.fetch("layout", controller_layout)
+    end
+  end
+end

data/rails/app/controllers/concerns/sitepress/site_pages.rb

@@ -13,49 +13,92 @@ module Sitepress
     extend ActiveSupport::Concern
 
     included do
-      rescue_from Sitepress::PageNotFoundError, with: :page_not_found
+      rescue_from Sitepress::ResourceNotFound, with: :resource_not_found
       helper Sitepress::Engine.helpers
       helper_method :current_page, :site
       before_action :append_relative_partial_path, only: :show
+      around_action :ensure_site_reload, only: :show
     end
 
+    # Public method that is primarily called by Rails to display the page. This should
+    # be hooked up to the Rails routes file.
     def show
-      render_page current_page
+      render_resource current_resource
     end
 
     protected
-    def render_page(page)
-      if page.renderable?
-        render_text_resource page
+
+    # If a resource has a handler, (e.g. erb, haml, etc.) we say its "renderable" and
+    # process it. If it doesn't have a handler, we treat it like its just a plain ol'
+    # file and serve it up.
+    def render_resource(resource)
+      if resource.renderable?
+        render_resource_with_handler resource
       else
-        send_binary_resource page
+        send_binary_resource resource
       end
     end
 
-    def current_page
-      @current_page ||= find_resource
+    # If a resource has a handler (e.g. erb, haml, etc.) we use the Rails renderer to
+    # process templates, layouts, partials, etc. To keep the whole rendering process
+    # contained in a way that the end user can override, we coupled the resource, source
+    # and output within a `Rendition` object so that it may be processed via hooks.
+    def render_resource_with_handler(resource)
+      rendition = Rendition.new(resource)
+      rendition.controller_layout = controller_layout
+
+      pre_render rendition
+      process_rendition rendition
+      post_render rendition
+    end
+
+    # This is where the actual rendering happens for the page source in Rails.
+    def pre_render(rendition)
+      rendition.output = render_to_string inline: rendition.source,
+        type: rendition.handler,
+        layout: rendition.layout
+    end
+
+    # This is to be used by end users if they need to do any post-processing on the rendering page.
+    # For example, the user may use Nokogiri to parse static HTML pages and hook it into the asset pipeline.
+    # They may also use tools like `HTMLPipeline` to process links from a markdown renderer.
+    def process_rendition(rendition)
+      # Do nothing unless the user extends this method.
     end
 
+    # Send the inline rendered, post-processed string into the Rails rendering method that actually sends
+    # the output to the end-user as a web response.
+    def post_render(rendition)
+      render inline: rendition.output, content_type: rendition.mime_type
+    end
+
+    # A reference to the current resource that's being requested.
+    def current_resource
+      @current_resource ||= find_resource
+    end
+    # In templates resources are more naturally thought of as pages, so we call it `current_page` from
+    # there and from the controller.
+    alias :current_page :current_resource
+
+    # References the singleton Site from the Sitepress::Configuration object. If you try to make this a class
+    # variable and let Rails have multiple Sitepress sites, you might run into issues with respect to the asset
+    # pipeline and various path configurations. To make this possible, a new object should be introduced to
+    # Sitepress that manages a many-sites to one-rails instance so there's no path issues.
     def site
       Sitepress.site
     end
 
-    def page_not_found(e)
+    # Raises a routing error for Rails to deal with in a more "standard" way if the user doesn't
+    # override this method.
+    def resource_not_found(e)
       raise ActionController::RoutingError, e.message
     end
 
     private
+    # This makes it possible to render partials from the current resource with relative
+    # paths. Without this the paths would have to be absolute.
     def append_relative_partial_path
-      append_view_path current_page.asset.path.dirname
-    end
-
-    def render_text_resource(resource)
-      with_sitepress_render_cache do
-        render inline: resource.body,
-          type: resource.asset.template_extensions.last,
-          layout: resource.data.fetch("layout", controller_layout),
-          content_type: resource.mime_type.to_s
-      end
+      append_view_path current_resource.asset.path.dirname
     end
 
     def send_binary_resource(resource)
@@ -64,13 +107,12 @@ module Sitepress
         type: resource.mime_type.to_s
     end
 
-    # Sitepress::PageNotFoundError is handled in the default Sitepress::SiteController
-    # with an execption that Rails can use to display a 404 error.
+    # Sitepress::ResourceNotFound is handled in the default Sitepress::SiteController
+    # with an exception that Rails can use to display a 404 error.
     def get(path)
       resource = site.resources.get(path)
       if resource.nil?
-        # TODO: Display error in context of Reources class root.
-        raise Sitepress::PageNotFoundError, "No such page: #{path}"
+        raise Sitepress::ResourceNotFound, "No such page: #{path}"
       else
         resource
       end
@@ -79,20 +121,7 @@ module Sitepress
     # Default finder of the resource for the current controller context. If the :resource_path
     # isn't present, then its probably the root path so grab that.
     def find_resource
-      get params.fetch(:resource_path, ROOT_RESOURCE_PATH)
-    end
-
-    # When development environments disable the cache, we still want to turn it
-    # on during rendering so that view doesn't rebuild the site on each call.
-    def with_sitepress_render_cache(&block)
-      cache_resources = site.cache_resources
-      begin
-        site.cache_resources = true
-        yield
-      ensure
-        site.cache_resources = cache_resources
-        site.clear_resources_cache unless site.cache_resources
-      end
+      get request.path
     end
 
     # Returns the current layout for the inline Sitepress renderer. This is
@@ -102,9 +131,9 @@ module Sitepress
       private_layout_method = self.method(:_layout)
       layout =
         if Rails.version >= "6"
-          private_layout_method.call lookup_context, current_page_rails_formats
+          private_layout_method.call lookup_context, current_resource_rails_formats
         elsif Rails.version >= "5"
-          private_layout_method.call current_page_rails_formats
+          private_layout_method.call current_resource_rails_formats
         else
           private_layout_method.call
         end
@@ -124,8 +153,8 @@ module Sitepress
     # method returns the intersection of the formats Rails supports from Mime::Types
     # and the current page's node formats. If nothing intersects, HTML is returned
     # as a default.
-    def current_page_rails_formats
-      extensions = current_page.node.formats.extensions
+    def current_resource_rails_formats
+      extensions = current_resource.node.formats.extensions
       supported_extensions = extensions & Mime::EXTENSION_LOOKUP.keys
 
       if supported_extensions.empty?
@@ -134,5 +163,24 @@ module Sitepress
         supported_extensions.map?(&:to_sym)
       end
     end
+
+    # When in development mode, the site is reloaded and rebuilt between each request so
+    # that users can see changes to content and site structure. These rebuilds are unnecessary and
+    # slow per-request in a production environment, so they should not be reloaded.
+    def ensure_site_reload
+      yield
+    ensure
+      reload_site
+    end
+
+    # Drops the website cache so that it's rebuilt when called again.
+    def reload_site
+      site.reload! if reload_site?
+    end
+
+    # Looks at the configuration to see if the site should be reloaded between requests.
+    def reload_site?
+      !Sitepress.configuration.cache_resources
+    end
   end
 end