sitepress-rails 2.0.0 → 3.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e02f24add74ef6493bdea2486f8d9e2eb4b24f6070ba72bfd3c0b15dc5ad09da
-  data.tar.gz: 149b6a137086b0c65dd5fe3c6d91bb1ff3b5c0acc6fddcf45d9a39c4583cf183
+  metadata.gz: 6c58152c6114a8b56271090b027096f9eb411e4d2e6eedb4811352b831d4be73
+  data.tar.gz: b6535af5b029475d05e4e2fc9a3354a41b6f8d33d2533eddd1119f8f080e7409
 SHA512:
-  metadata.gz: e9990fc71151cba0e82e4c9b2745dd57c91dcbd18fb42b5cd815bbd6aa852c60847fedf63bd720199e2e3ddab2f2cc77096a3b96efc4c56b40bfda41ec7193be
-  data.tar.gz: a8737c1757a5da80edcbdf2dea6cb0c48a204577c083c3bbd219124870ca69eb12d1a6fdfa79d55be12b3f1ff3dd0db18d909e6deb03727e03ae664a49192bf6
+  metadata.gz: 75ebd2f408e8510263741b33052db92da2b91510bad929cc5f1770134666dca9ee08bccf0b0ae4bad668f8683209a4ee148e5fd68ce5240c73b46ac7a8b48338
+  data.tar.gz: 9aa98bcba2c6f0332e1c5e7ef71986c40d3cb3a84cd8e97efc32fe811a6e9ff557384fe3e89fa4dbcbe4fc1852a97ad5cd26945b8178bcd4de0bba03469683ac

data/README.md

@@ -4,37 +4,27 @@ Sitepress is a file-backed website content manager that can be embedded in popul
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Add `sitepress-rails` to a Rails application by running:
 
 ```ruby
-gem 'sitepress-rails'
+bundle add sitepress-rails
 ```
 
-And then execute:
+The install content pages by running:
 
 ```bash
-$ bundle
+$ ./bin/rails generate sitepress:install
 ```
 
-Then mount the engine into your `config/routes.rb` file:
+This command creates a few content pages and adds the following to the `config/routes.rb` file:
 
 ```ruby
-mount Sitepress::Engine => "/"
+sitepress_pages
+sitepress_root # Delete if you don't want your app's root page to be a content page.
 ```
 
-Create the `app/content/pages` in your rails project:
-
-```bash
-$ mkdir -p app/content/pages
-```
-
-Then add pages to the `app/content/pages` directory:
-
-```bash
-$ echo "<h1>Hello</h1><p>It is <%= Time.now %> o'clock</p>" > app/content/pages/hello.html.erb
-```
-
-Point your browser to `http://127.0.0.1:3000/hello` and if all went well you should see the page you just created.
+Restart the Rails application server and point your browser to `http://127.0.0.1:3000/` and if all went well you should see a sitepress page.
 
 ## License
+
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/bin/rails

@@ -2,8 +2,8 @@
 # This command will automatically be run when you run "rails" with Rails gems
 # installed from the root of your application.
 
-ENGINE_ROOT = File.expand_path('../..', __FILE__)
-ENGINE_PATH = File.expand_path('../../lib/sitepress-rails/engine', __FILE__)
+ENGINE_ROOT = File.expand_path('../../rails', __FILE__)
+ENGINE_PATH = File.expand_path('../../lib/sitepress/engine', __FILE__)
 
 # Set up gems listed in the Gemfile.
 ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../../Gemfile', __FILE__)

data/lib/sitepress/engine.rb

@@ -1,4 +1,5 @@
 require "rails/engine"
+require "sitepress/routing_mapper"
 
 module Sitepress
   class Engine < ::Rails::Engine
@@ -23,6 +24,7 @@ module Sitepress
       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
+      app.paths["app/models"].push site.models_path.expand_path
     end
 
     # Configure sprockets paths for the site.

data/lib/sitepress/model.rb

@@ -0,0 +1,69 @@
+module Sitepress
+  # Wraps a page in a class, which makes it much easier to decorate and validate.
+  class Model
+    attr_reader :page
+
+    delegate \
+      :request_path,
+      :data,
+      :body,
+        to: :page
+
+    def initialize(page)
+      @page = page
+    end
+
+    # Treat as equal if the resource and model class are the same.
+    def ==(model)
+      self.page == model.page and self.class == model.class
+    end
+
+    class << self
+      delegate \
+        :first,
+          to: :all
+
+      # Defines a class method that may be called later to return a
+      # collection of objects. The default glob, for example, is named `:all`,
+      # which defines `MyModel.all` on the class.
+      def collection(name = Models::Collection::DEFAULT_NAME, glob:, **kwargs)
+        define_singleton_method name do
+          self.glob glob, **kwargs
+        end
+      end
+
+      # Adhoc querying of models via `Model.glob("foo/bar").all`
+      def glob(glob, **kwargs)
+        Models::Collection.new model: self, site: site, glob: glob, **kwargs
+      end
+
+      # Wraps a page in a class if given a string that represents the path or
+      # a page object itself.
+      def get(page)
+        case page
+        when Model
+          page
+        when String
+          new site.get page
+        when Sitepress::Resource
+          new page
+        else
+          raise ModelNotFoundError, "#{self.inspect} could not find #{page.inspect}"
+        end
+      end
+      alias :find :get
+
+      def data(*keys, default: nil)
+        keys.each do |key|
+          define_method key do
+            self.data.fetch key.to_s, default
+          end
+        end
+      end
+
+      def site
+        Sitepress.site
+      end
+    end
+  end
+end

data/lib/sitepress/models/collection.rb

@@ -0,0 +1,34 @@
+module Sitepress
+  module Models
+    # Everything needed to iterate over a set of resources from a glob and wrap
+    # them in a model so they are returned as a sensible enumerable.
+    class Collection
+      include Enumerable
+
+      # Page models will have `PageModel.all` method defined by default.
+      DEFAULT_NAME = :all
+
+      # Iterate over all resources in the site by default.
+      DEFAULT_GLOB = "**/*.*".freeze
+
+      attr_reader :model, :glob, :site
+
+      def initialize(model:, site:, glob: DEFAULT_GLOB)
+        @model = model
+        @glob = glob
+        @site = site
+      end
+
+      def resources
+        site.glob glob
+      end
+
+      # Wraps each resource in a model object.
+      def each
+        resources.each do |resource|
+          yield model.new resource
+        end
+      end
+    end
+  end
+end

data/lib/sitepress/rails.rb

@@ -2,6 +2,10 @@ require "sitepress-core"
 
 module Sitepress
   autoload :Compiler,                 "sitepress/compiler"
+  autoload :Model,                    "sitepress/model"
+  module Models
+    autoload :Collection,             "sitepress/models/collection"
+  end
   autoload :RailsConfiguration,       "sitepress/rails_configuration"
   module Renderers
     autoload :Controller,             "sitepress/renderers/controller"
@@ -15,8 +19,17 @@ module Sitepress
     autoload :DirectoryIndexPath,     "sitepress/build_paths/directory_index_path"
   end
 
+  # Base class for errors if Sitepress can't find a resource, model, etc.
+  NotFoundError = Class.new(StandardError)
+
   # Rescued by ActionController to display page not found error.
-  ResourceNotFound = Class.new(StandardError)
+  ResourceNotFoundError = Class.new(NotFoundError)
+  # Accidentally left out `Error` in the constant name, so I'm setting
+  # that up here for backwards compatability.
+  ResourceNotFound = ResourceNotFoundError
+
+  # Raised if a model isn't found.
+  ModelNotFoundError = Class.new(NotFoundError)
 
   # Raised when any of the Render subclasses can't render a page.
   RenderingError = Class.new(RuntimeError)

data/lib/sitepress/rails_configuration.rb

@@ -6,13 +6,10 @@ module Sitepress
     # Store in ./app/content by default.
     DEFAULT_SITE_ROOT = "app/content".freeze
 
-    attr_accessor :routes, :cache_resources
+    attr_accessor :cache_resources
     attr_writer :site, :parent_engine
 
     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

data/lib/sitepress/route_constraint.rb

@@ -1,12 +1,14 @@
 module Sitepress
   # Route constraint for rails routes.rb file.
   class RouteConstraint
+    attr_reader :site
+
     def initialize(site: Sitepress.site)
       @site = site
     end
 
     def matches?(request)
-      !!@site.resources.get(request.path)
+      !!site.resources.get(request.path)
     end
   end
 end

data/lib/sitepress/routing_mapper.rb

@@ -0,0 +1,31 @@
+module ActionDispatch::Routing
+  # I have no idea how or why this works this way, I lifted the pattern from Devise, which came with even
+  # more weird stuff. Rails could use an API for adding route helpers to decrease the brittleness of this
+  # approach. For now, deal with this helper.
+  class Mapper
+    DEFAULT_CONTROLLER = "sitepress/site".freeze
+    DEFAULT_ACTION = "show".freeze
+    ROUTE_GLOB_KEY = "/*resource_path".freeze
+
+    # Hook up all the Sitepress pages
+    def sitepress_pages(controller: DEFAULT_CONTROLLER, action: DEFAULT_ACTION, root: false, constraints: Sitepress::RouteConstraint.new)
+      get ROUTE_GLOB_KEY,
+        controller: controller,
+        action: action,
+        as: :page,
+        format: false,
+        constraints: constraints
+
+      sitepress_root controller: controller, action: action if root
+    end
+
+    # Hook sitepress root up to the index of rails.
+    def sitepress_root(controller: DEFAULT_CONTROLLER, action: DEFAULT_ACTION)
+      if has_named_route? :root
+        Rails.logger.warn "Sitepress tried to configured the 'root' route, but it was already defined. Check the 'routes.rb' file for a 'root' route or call 'sitepress_pages(root: false)'."
+      else
+        root controller: controller, action: action
+      end
+    end
+  end
+end

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

@@ -71,7 +71,7 @@ module Sitepress
     # 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
+      render body: rendition.output, content_type: rendition.mime_type
     end
 
     # A reference to the current resource that's being requested.
@@ -116,6 +116,7 @@ module Sitepress
       if resource.nil?
         raise Sitepress::ResourceNotFound, "No such page: #{path}"
       else
+        Rails.logger.info "Sitepress resolved asset #{resource.asset.path}"
         resource
       end
     end

data/rails/lib/generators/sitepress/controller/USAGE

@@ -0,0 +1,8 @@
+Description:
+    Installs a controller that can be used to manipulate Sitepress responses.
+
+Example:
+    bin/rails generate sitepress:controller SiteController
+
+    This will create:
+        app/controllers/site_controller.rb

data/rails/lib/generators/sitepress/controller/controller_generator.rb

@@ -0,0 +1,19 @@
+class Sitepress::ControllerGenerator < Rails::Generators::Base
+  source_root File.expand_path("templates", __dir__)
+
+  def copy_files
+    directory ".", "app"
+  end
+
+  def append_controller_to_sitepress_root_route
+    inject_into_file "config/routes.rb", after: "sitepress_root" do
+      " controller: :site"
+    end
+  end
+
+  def append_controller_to_sitepress_pages_route
+    inject_into_file "config/routes.rb", after: "sitepress_pages" do
+      " controller: :site"
+    end
+  end
+end

data/rails/lib/generators/sitepress/controller/templates/controllers/site_controller.rb

@@ -0,0 +1,17 @@
+class SiteController < Sitepress::SiteController
+  # Override this method to implement your processing logic for Sitepress pages.
+  def show
+    render_resource current_resource
+  end
+
+  protected
+
+  # 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.
+  #
+  # For example, the rendition could be modified via `Nokogiri::HTML5::DocumentFragment(rendition)`.
+  def process_rendition(rendition)
+    # Do nothing unless the user extends this method.
+  end
+end

data/rails/lib/generators/sitepress/install/USAGE

@@ -0,0 +1,10 @@
+Description:
+    Installs Sitepress in a Rails appliation
+
+Example:
+    bin/rails generate sitepress:install
+
+    This will create:
+        app/content/models/page_model.rb
+        app/content/helpers/page_helpers.rb
+        app/content/pages/index.html.erb

data/rails/lib/generators/sitepress/install/install_generator.rb

@@ -0,0 +1,14 @@
+module Sitepress
+  class InstallGenerator < Rails::Generators::Base
+    source_root File.expand_path("templates", __dir__)
+
+    def copy_files
+      directory ".", "app/content"
+    end
+
+    def add_sitepress_routes
+      route "sitepress_root"
+      route "sitepress_pages"
+    end
+  end
+end

data/rails/lib/generators/sitepress/install/templates/helpers/page_helper.rb

@@ -0,0 +1,29 @@
+module PageHelper
+  # Creates a hyperlink to a page using the `title` key. Change the default in the args
+  # below if you use a different key for page titles.
+  def link_to_page(page, title_key: "title")
+    link_to page.data.fetch(title_key, page.request_path), page.request_path
+  end
+
+  # Quick and easy way to change the class of a page if its current. Useful for
+  # navigation menus.
+  def link_to_if_current(text, page, active_class: "active")
+    if page == current_page
+      link_to text, page.request_path, class: active_class
+    else
+      link_to text, page.request_path
+    end
+  end
+
+  # Conditionally renders the block if an arg is present. If all the args are nil,
+  # the block is not rendered. Handy for laconic templating languages like slim, haml, etc.
+  def with(*args, &block)
+    block.call(*args) unless args.all?(&:nil?)
+  end
+
+  # Render a block within a layout. This is a useful, and prefered way, to handle
+  # nesting layouts, within Sitepress.
+  def render_layout(layout, **kwargs, &block)
+    render html: capture(&block), layout: "layouts/#{layout}", **kwargs
+  end
+end

data/rails/lib/generators/sitepress/install/templates/models/page_model.rb

@@ -0,0 +1,4 @@
+class PageModel < Sitepress::Model
+  collection glob: "**/*.html*"
+  data :title
+end

data/rails/lib/generators/sitepress/install/templates/pages/index.html.erb

@@ -0,0 +1,43 @@
+---
+title: Getting started with Sitepress in Rails
+---
+
+<style>
+  .sitepress {
+    max-width: 90%;
+  }
+  .sitepress h1 {
+    font-weight: bold;
+    font-size: 3rem;
+    margin-bottom: 4rem;
+  }
+  .sitepress h2 {
+    font-weight: bold;
+    font-size: 1.5rem;
+  }
+  .sitepress * {
+    margin-top: 1rem;
+  }
+  .sitepress code {
+    font-family: monospace;
+    font-size: 1rem;
+  }
+  .sitepress a {
+    text-decoration: underline;
+  }
+</style>
+
+<article class="sitepress">
+  <h1><%= current_page.data.fetch("title") %></h1>
+
+  <p>This was generated by the <code>rails generate sitepress:install</code> command.</p>
+
+  <h2>Content</h2>
+  <p>Sitepress content files are in <code><%= site.root_path.expand_path %></code>. There you can edit site content, including this file at <code><%= current_page.asset.path %></code>.
+
+  <h2>Routes</h2>
+  <p>Sitepress defined a root route in <code><%= Rails.root.join("config/routes.rb") %></code>. If that conflicts with your routes configuration, you'll want to open it and edit accordingly.</p>
+
+  <h2>Documentation</h2>
+  <p>Check out the <a href="https://sitepress.cc">Sitepress website</a> for help on getting started and documentation. Since Sitepress is also built on top of Rails, most of the <a href="https://guides.rubyonrails.org/action_view_helpers.html">Rails view helpers</a> work too.</p>
+</article>

data/rails/test/lib/generators/sitepress/controller_generator_test.rb

@@ -0,0 +1,14 @@
+require "test_helper"
+require "generators/sitepress/controller/controller_generator"
+
+class Sitepress::ControllerGeneratorTest < Rails::Generators::TestCase
+  tests Sitepress::ControllerGenerator
+  destination Rails.root.join("tmp/generators")
+  setup :prepare_destination
+
+  # test "generator runs without errors" do
+  #   assert_nothing_raised do
+  #     run_generator ["arguments"]
+  #   end
+  # end
+end

data/rails/test/lib/generators/sitepress/install_generator_test.rb

@@ -0,0 +1,14 @@
+require "test_helper"
+require "generators/sitepress/install/install_generator"
+
+class Sitepress::InstallGeneratorTest < Rails::Generators::TestCase
+  tests Sitepress::InstallGenerator
+  destination Rails.root.join("tmp/generators")
+  setup :prepare_destination
+
+  # test "generator runs without errors" do
+  #   assert_nothing_raised do
+  #     run_generator ["arguments"]
+  #   end
+  # end
+end

data/sitepress-rails.gemspec

@@ -19,14 +19,15 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
   spec.test_files = Dir["spec/**/*"]
 
+  rails_version      = ">= 6.0"
+
   spec.add_development_dependency "rspec-rails"
   spec.add_development_dependency "pry"
-  spec.add_development_dependency "rails", ">= 4.0"
+  spec.add_development_dependency "rails", rails_version
 
   spec.add_runtime_dependency "sitepress-core", spec.version
 
   # We don't need every single rals rependency, so grab the subset here.
-  rails_version      = ">= 6.0"
   spec.add_dependency "railties",       rails_version
   spec.add_dependency "actionpack",     rails_version
   spec.add_dependency "sprockets-rails", ">= 2.0.0"

data/spec/dummy/app/content/models/page_model.rb

@@ -0,0 +1,4 @@
+class PageModel < Sitepress::Model
+  collection glob: "**/*.html*"
+  data :title
+end

data/spec/dummy/config/routes.rb

@@ -1,3 +1,4 @@
 Rails.application.routes.draw do
   get "/baseline/render", to: "baseline#show"
+  sitepress_pages
 end