simplec 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: cd4562c8c0bbab684b813215b25a37647dbbd134
-  data.tar.gz: 924e595fdddaf414fcbd91a33b0a5008e7913864
+  metadata.gz: 30941905c919979a56cf165241070e5da7822192
+  data.tar.gz: 48b105ceabc6246c9b3cdbcc30dcbdc1a479696d
 SHA512:
-  metadata.gz: 49b55b0d7c216b7e35a5cec8f8c2e99086077dfd43ad5f27d9da0e6de3446b62e51a06013b2fc707554a5888cfcb3b69cfa5947d51f73a9e7718775a18f9c8a5
-  data.tar.gz: 6ce855a1ca1486f9e302dab3bf1b8c69cc8137c85cefd84daf1e14794658f35bd5a41f4f427d3031820d49e205833ddeb84c0fe9335460ba202630fa5c7ca7f3
+  metadata.gz: f9b3616fc0b37ae640025027a50f55a41a52bbc6187ffc781de995717311142b922fafb1990bc98290fdbdfe6378173257842051a892a65ca3d96e3038ac8024
+  data.tar.gz: 8e1fbe53a20d80b5362d16ff6a71be9d5c62ae97a855dc97e1f753010d9e92079ddb78733bbf3f6ca23e9544a973efb91b29618bc72957e10ae0e56ac892fc6c

data/README.md

@@ -251,6 +251,8 @@ See this page for a good cheat sheet: http://markevans.github.io/dragonfly/image
 
     - Throw clear warning when creating a page without a type
 
+    - main_app document or method_missing
+
     - Document `lib/simplec/controller_extensions.rb`
 
     - Document why _subdomain in subdomain form in admin.
@@ -263,7 +265,7 @@ See this page for a good cheat sheet: http://markevans.github.io/dragonfly/image
 
     - utilize thread local variable for found subdomain in #subdomain
 
-    - simplec_path/simplec_url caching
+1. Sitemap
 
 1. Installer `rails generater simplec:install`
 

data/app/controllers/simplec/application_controller.rb

@@ -1,3 +1,4 @@
+# @!visibility private
 module Simplec
   class ApplicationController < ::ActionController::Base
     protect_from_forgery with: :exception

data/app/controllers/simplec/pages_controller.rb

@@ -1,18 +1,12 @@
 require_dependency "simplec/application_controller"
+require_dependency "simplec/page_action_helpers"
 
 module Simplec
   class PagesController < ApplicationController
+    include Simplec::PageActionHelpers
 
     def show
-      @page = page("/#{params[:path]}")
-      render layout: layout(@page)
-    end
-
-    private
-
-    def layout(page)
-      [page.layout, page.subdomain.default_layout, 'public']. # TODO allow config for public
-        reject(&:blank?).first
+      render_path params[:path] || ''
     end
 
   end

data/app/jobs/simplec/application_job.rb

@@ -1,3 +1,4 @@
+# @private
 module Simplec
   class ApplicationJob < ActiveJob::Base
   end

data/app/models/simplec/application_record.rb

@@ -1,3 +1,4 @@
+# @private
 module Simplec
   class ApplicationRecord < ActiveRecord::Base
     self.abstract_class = true

data/app/models/simplec/embedded_image.rb

@@ -1,11 +1,42 @@
 module Simplec
+
+  # An embedded image in an editor field.
+  #
+  # For the most part you don't need to utilize this record. These records are
+  # created by summernote and the administration of creating them is handled
+  # by the Simplec Engine.
+  #
+  # There is an #embedded_images association on a `Simplec::Page` record.
+  #
+  # @!visibility public
   class EmbeddedImage < ApplicationRecord
+
+    # @!attribute embeddable
+    # The object that owns the embedded image
+    # @return [Object, nil] An ActiveRecord object
     belongs_to :embeddable,
       polymorphic: true,
       optional: true
 
+    # @!attribute asset
+    #   @return [Dragonfly::Model::Attachment, nil] The embedded asset
     dragonfly_accessor :asset
 
+    # @!attribute embeddable_type
+    #   @return [String, nil] The type of the #embeddable association
+
+    # @!attribute embeddable_id
+    #   @return [String, Integer, nil] The uuid (or id) of the #embeddable association
+
+    # @!attribute asset_uid
+    #   @return [String, nil] The unique id of the Dragonfly #asset
+
+    # @!attribute asset_name
+    #   @return [String, nil] The name of the Dragonfly #asset
+
+    # Dragonfly url for the asset.
+    #
+    # @return [String] the url for the dragonfly asset
     def url
       return unless self.asset
       return self.asset.url unless persisted?

data/app/models/simplec/page.rb

@@ -1,203 +1,255 @@
-# Simplec::Page
-#
-# This class represents a page in the system.
-#
-# Each page has a class located in:
-#   app/models/page/NAME.html.erb
-#
-# Each page has a partial template in:
-#   app/views/pages/_NAME.html.erb
-#
-#   Where NAME is the demodulized, snake-case name of the Page Subclasss. For
-#   example:
-#
-#     class Page::Home < Page
-#       field :h1
-#     end
-#
-#   Would live in app/models/page/home.html.erb and have a template in
-#   app/views/pages/_home.html.erb.
-#
-#   Each page has the following attributes by default:
-#     - page.title
-#
-# Read the documentation below for the class method .field, it is the most
-# used method.
-#
-#
 module Simplec
+
+  # This class represents a page in the system.
+  #
+  # == Model and Template Relationship.
+  #
+  # Each page has a class located in:
+  #   app/models/page/NAME.rb
+  #
+  # Each page has a partial template in:
+  #   app/views/pages/_NAME.html.erb
+  #
+  #   Where NAME is the demodulized, snake-case name of the Page Subclasss. For
+  #   example:
+  #
+  #     class Page::Home < Page
+  #       field :h1
+  #     end
+  #
+  #   Would have a have a template in `app/views/pages/_home.html.erb`.
+  #
+  # @!visibility public
   class Page < ApplicationRecord
 
+    FILE_FIELDS = [:file, :image].freeze
+
+    belongs_to :subdomain,
+      optional: false
+    belongs_to :parent,
+      class_name: 'Page',
+      optional: true
+    has_many :childern,
+      class_name: 'Page',
+      foreign_key: :parent_id
+    has_many :embedded_images,
+      as: :embeddable,
+      dependent: :delete_all
+
+    validates :type,
+      presence: true
+    validates :path,
+      uniqueness: { scope: :subdomain_id }
+    validate :validate_path_not_nil!
+    validates :layout,
+      inclusion: {in: :layouts, allow_blank: true}
+    validates :title,
+      presence: true
+
+    before_validation :match_parent_subdomain
+    before_validation :build_path
+    after_save :link_embedded_images!
+
+    # @!attribute slug
+    #   The value is normalized to a string starting without a leading slash
+    #   and ending without a slash. Case is not changed.
+    #   @return [String]
+
+    # @!attribute [r] path
+    #   The the path is computed from the slug and the sum all parent pages.
+    #   @return [String]
+
+    # @!attribute title
+    #   This is the title of the page.
+    #   @return [String]
+
+    # @!attribute meta_description
+    #   This is the meta description tag for the page.
+    #   @return [String]
+
+    # @!attribute layout
+    #   This is the layout to be used when the page is rendered. This attribute
+    #   overrides the associated Subdomain's default_layout.
+    #
+    #   See Simplec::Subdomain#layouts to get a list of optional layouts.
+    #
+    #   @return [String]
+
+    # @!attribute fields
+    #   JSONB Postgres field that holds all defined fields. Use only if you
+    #   know what you are doing.
+    #   @return [JSON]
 
-    # TODO Document FILE_FIELDS constant
-    #
-		FILE_FIELDS = [:file, :image].freeze
-
-		belongs_to :subdomain,
-			optional: false
-		belongs_to :parent,
-			class_name: 'Page',
-			optional: true
-		has_many :childern,
-			class_name: 'Page',
-			foreign_key: :parent_id
-		has_many :embedded_images,
-			as: :embeddable,
-			dependent: :delete_all
-
-		validates :type,
-			presence: true
-		validates :path,
-			presence: true,
-			uniqueness: { scope: :subdomain_id }
-		validates :layout,
-			inclusion: {in: :layouts, allow_blank: true}
-		validates :title,
-			presence: true
-
-		before_validation :match_parent_subdomain
-		before_validation :build_path
-		after_save :link_embedded_images!
-
-		# Define a field on the page.
-		#
-		# - name - name of field
-		# - options[:type] - :string (default), :text, :editor, :file, :image
-		#   :string - yields a text input
-		#   :text - yields a textarea
-		#   :editor - yields a summernote editor
-		#   :file - yields a file field
-		#   :image - yields a file field with image preview
-		#
-		# There is as template for each type for customization located in:
-		#   app/views/shared/fields/_TYPE.html.erb
-		#
-		# Defines a field on a subclass. This creates a getter and setter for the
-		# name passed in. The options are used when building the administration forms.
-		#
-		# Regular dragonfly validations are available on :file and :image fields.
-		# http://markevans.github.io/dragonfly/models#validations
-		#
-		def self.field(name, options={})
-			fields[name] = {name: name, type: :string}.merge(options)
-			if FILE_FIELDS.member?(fields[name][:type])
-				dragonfly_accessor name
-				data_field :"#{name}_uid"
-				data_field :"#{name}_name"
-			else
-				data_field(name)
-			end
-		end
-
-		# List fields
-		#
-		def self.fields
-			@fields ||= Hash.new
-		end
-
-		# Return a constantized type, whitelisted by known subclasses.
-		#
-		def self.type(type)
+    # Define a field on the page
+    #
+    # There is as template for each type for customization located in:
+    #   app/views/shared/fields/_TYPE.html.erb
+    #
+    # Defines a field on a subclass. This creates a getter and setter for the
+    # name passed in. The options are used when building the administration forms.
+    #
+    # Regular dragonfly validations are available on :file and :image fields.
+    # http://markevans.github.io/dragonfly/models#validations
+    #   :string - yields a text input
+    #   :text - yields a textarea
+    #   :editor - yields a summernote editor
+    #   :file - yields a file field
+    #   :image - yields a file field with image preview
+    #
+    # @param name [String] name of field to be defined
+    # @param options [Hash] field options
+    # @option options [Symbol] :type one of :string (default), :text, :editor, :file, :image
+    def self.field(name, options={})
+      fields[name] = {name: name, type: :string}.merge(options)
+      if FILE_FIELDS.member?(fields[name][:type])
+        dragonfly_accessor name
+        data_field :"#{name}_uid"
+        data_field :"#{name}_name"
+      else
+        data_field(name)
+      end
+    end
+
+    # @return [Hash]
+    def self.fields
+      @fields ||= Hash.new
+    end
+
+    # Return a constantized type, whitelisted by known subclasses.
+    #
+    # @raise [RuntimeError] if Page subclass isn't defined.
+    # @return [Class]
+    def self.type(type)
       ::Page rescue raise '::Page not defined, define it in app/models'
-			raise 'Unsupported Page Type; define in app/models/page/' unless ::Page.subclasses.map(&:name).
-				member?(type)
-			type.constantize
-		end
-
-		# Return names of fields.
-		#
-		# type: :file, is the only option
-		#
-		def self.field_names(type=nil)
-			_fields = case type
-								when :file
-									fields.select {|k, v| FILE_FIELDS.member?(v[:type])}
-								else
-									fields
-								end
-			_fields.keys
-		end
-
-		# Return field options for building forms.
-		#
-		def field_options
-			self.class.fields.values
-		end
-
-		# List parents, closest to furthest.
-		#
-		def parents
-			page, parents = self, Array.new
-			while page.parent
-				page = page.parent
-				parents << page
-			end
-			parents
-		end
-
-		# Before validation hook.
-		#
-		# Build the path of the page to be used in routing.
-		#
-		def build_path
-			_pages = self.parents.reverse + [self]
-			self.path = "/#{_pages.map(&:slug).reject(&:blank?).join('/')}"
-		end
-
-		# Before validation hook
-		#
-		# All pages need to have a matching subdomain to parent page
-		#
-		def match_parent_subdomain
-			return unless self.parent
-			self.subdomain = self.parent.subdomain
-		end
-
-		def find_embedded_images
-			text = self.fields.values.join(' ')
-			matches = text.scan(/ei=([^&]*)/)
-			encoded_ids = matches.map(&:first)
-			ids = encoded_ids.map { |eid| Base64.urlsafe_decode64(URI.unescape(eid)) }
-			EmbeddedImage.includes(:embeddable).find(ids)
-		end
-
-		def link_embedded_images!
-			images = self.find_embedded_images
-			images.each do |image|
-				raise AlreadyLinkedEmbeddedImage if image.embeddable &&
-					image.embeddable != self
-				image.update!(embeddable: self)
-			end
-		end
-
-		def layouts
-			@layouts ||= Subdomain.new.layouts
-		end
-
-		module Normalizers
-			def slug=(val)
-				val = val ? val.to_s.split('/').reject(&:blank?).join('/') : val
-				super val
-			end
-
-			def slug
-				if self.parent_id && self.parent.nil?
-					self.path.to_s.split('/').reject(&:blank?).join('/')
-				else
-					super
-				end
-			end
-		end
-		prepend Normalizers
-
-		class AlreadyLinkedEmbeddedImage < StandardError; end
-
-		private
-
-		def self.data_field(name)
-			define_method(name) { fields[name.to_s] }
-			define_method("#{name}=") { |val| fields[name.to_s] = val }
-		end
+      raise 'Unsupported Page Type; define in app/models/page/' unless ::Page.subclasses.map(&:name).
+        member?(type)
+      type.constantize
+    end
+
+    # Return names of fields.
+    #
+    # type: :file, is the only option
+    #
+    def self.field_names(type=nil)
+      _fields = case type
+                when :file
+                  fields.select {|k, v| FILE_FIELDS.member?(v[:type])}
+                else
+                  fields
+                end
+      _fields.keys
+    end
+
+    # Return field options for building forms.
+    #
+    def field_options
+      self.class.fields.values
+    end
+
+    # List parents, closest to furthest.
+    #
+    # This is a recursive, expensive call.
+    #
+    # @return [Array] of parent Pages
+    def parents
+      page, parents = self, Array.new
+      while page.parent
+        page = page.parent
+        parents << page
+      end
+      parents
+    end
+
+    # Build the path of the page to be used in routing.
+    #
+    # Used as a before validation hook.
+    #
+    # @return [String] the computed path for the page
+    def build_path
+      _pages = self.parents.reverse + [self]
+      self.path = _pages.map(&:slug).reject(&:blank?).join('/')
+    end
+
+    # Sets the #subdomain t that of the parent.
+    #
+    # All pages need to have a matching subdomain to parent page. Does nothing
+    # if there is no parent.
+    #
+    # Used as a before validation hook.
+    #
+    # @return [Simplec::Subdomain] the parent's subdomain
+    def match_parent_subdomain
+      return unless self.parent
+      self.subdomain = self.parent.subdomain
+    end
+
+    # Search all of the fields text and create an array of all found
+    # Simplec::EmbeddedImages.
+    #
+    # @return [Array] of Simplec::EmbeddedImages
+    def find_embedded_images
+      text = self.fields.values.join(' ')
+      matches = text.scan(/ei=([^&]*)/)
+      encoded_ids = matches.map(&:first)
+      ids = encoded_ids.map { |eid| Base64.urlsafe_decode64(URI.unescape(eid)) }
+      EmbeddedImage.includes(:embeddable).find(ids)
+    end
+
+    # Set this instance as the #embeddable association on the
+    #   Simplec::EmbeddedImage
+    #
+    # Used as an after_save hook.
+    #
+    # @return [Array] of Simplec::EmbeddedImages
+    def link_embedded_images!
+      images = self.find_embedded_images
+      images.each do |image|
+        raise AlreadyLinkedEmbeddedImage if image.embeddable &&
+          image.embeddable != self
+        image.update!(embeddable: self)
+      end
+    end
+
+    # Get layout options.
+    #
+    # See Simplec::Subdomain#layouts.
+    #
+    # @return [Array] of layout String names
+    def layouts
+      @layouts ||= Subdomain.new.layouts
+    end
+
+    # @!visibility private
+    module Normalizers
+
+      def slug=(val)
+        val = val ? val.to_s.split('/').reject(&:blank?).join('/') : val
+        super val
+      end
+
+      def slug
+        if self.parent_id && self.parent.nil?
+          self.path.to_s.split('/').reject(&:blank?).join('/')
+        else
+          super
+        end
+      end
+    end
+    prepend Normalizers
+
+    class AlreadyLinkedEmbeddedImage < StandardError; end
+
+    private
+
+    def validate_path_not_nil!
+      return unless self.path.nil?
+      errors.add :path, "cannot be nil"
+    end
+
+    def self.data_field(name)
+      define_method(name) { fields[name.to_s] }
+      define_method("#{name}=") { |val| fields[name.to_s] = val }
+    end
   end
 end
 

data/config/routes.rb

@@ -3,7 +3,7 @@ Simplec::Engine.routes.draw do
   scope constraints: Simplec::Subdomains do
     resources :embedded_images, path: 'embedded-images', only: :create
     root 'pages#show'
-    get '*path', to: 'pages#show'
+    get '(*path)', to: 'pages#show', as: :page
   end
 
 end

data/lib/simplec.rb

@@ -1,6 +1,13 @@
 require "simplec/engine"
 require "simplec/embedded_image_actions"
+require 'simplec/action_controller/extensions'
+require 'simplec/action_view/helper'
+require "simplec/page_action_helpers"
 
+
+# Configuration details will go here.
+#
+# @!visibility public
 module Simplec
   # TODO configuration options
 end

data/lib/simplec/action_controller/extensions.rb

@@ -4,9 +4,11 @@ module Simplec
 
       def self.included(receiver)
         receiver.helper_method :subdomain, :page,
-          :simplec_path, :simplec_url
+          :simplec_path_for, :simplec_url_for
       end
 
+      # Get the subdomain.
+      # TODO docs
       def subdomain(name=nil)
         name          ||= request.subdomain
         @_subdomains  ||= Hash.new
@@ -14,42 +16,85 @@ module Simplec
         @_subdomains[name] = Subdomain.find_by!(name: name)
       end
 
+      # TODO docs
+      # @param path [String] path with no leading /
+      #
+      # @return [Simplec::Page]
       def page(path, options={})
         @_page ||= Hash.new
         return @_page[path] if @_page[path]
 
-        _subdomain = subdomain
-        _subdomain = Subdomain.find_by!(
-          name: options[:subdomain]
-        ) if options[:subdomain]
+        _subdomain = options[:subdomain] ?
+          Subdomain.find_by!(name: options[:subdomain]) :
+          subdomain
 
+        # TODO add raise option for find_by!
         @_page[path] = _subdomain.pages.find_by!(path: path)
       end
 
-      def simplec_path(page_or_path, options={})
-        # TODO cache page_paths
-        _page = page_or_path.is_a?(Page) ?
-          page_or_path : page(page_or_path, options)
-
-        unless _page
-          raise ActiveRecord::RecordNotFound if options[:raise]
-          return nil
-        end
+      # Get the path of a page.
+      #
+      # By default, if the Page cannot be located nil will be the result.
+      #
+      # @param page_or_path [Simplec::Page, String]
+      #   If a page it will find the page.
+      #   If a path it will find the page from the given path (no leading /).
+      #
+      # @param options [Hash] options
+      # @option options [Symbol] :raise
+      #   If :raise is true, then ActiveRecord::RecordNotFound will be raised
+      #   if the page cannot be found.
+      #
+      # @raise [ActiveRecord::RecordNotFound]
+      #   if options[:raise] is true and Page cannot be located
+      #
+      # @return [String, nil] path of page, or nil
+      def simplec_path_for(page_or_path, options={})
+        page = page_for(page_or_path, options.extract!(:raise))
+        return unless page
+        simplec.page_path options.merge(
+          path: page.path
+        )
+      end
 
-        _page.path
+      # Get the url of a page.
+      #
+      # By default, if the Page cannot be located nil will be the result.
+      #
+      # @param page_or_path [Simplec::Page, String]
+      #   If a page it will find the page.
+      #   If a path it will find the page from the given path (no leading /).
+      #
+      # @param options [Hash] options
+      # @option options [Symbol] :raise
+      #   If :raise is true, then ActiveRecord::RecordNotFound will be raised
+      #   if the page cannot be found.
+      #
+      # @raise [ActiveRecord::RecordNotFound]
+      #   if options[:raise] is true and Page cannot be located
+      #
+      # @return [String, nil] path of page, or nil
+      def simplec_url_for(page_or_path, options={})
+        page = page_for(page_or_path, options.extract!(:raise))
+        return unless page
+        simplec.page_url options.merge(
+          subdomain: page.subdomain.try(:name),
+          path: page.path
+        )
       end
 
-      def simplec_url(page_or_path, options={})
-        # TODO cache page_urls
-        _page = page_or_path.is_a?(Page) ?
+      private
+
+      def page_for(page_or_path, options={})
+        page = page_or_path.is_a?(Page) ?
           page_or_path : page(page_or_path, options)
 
-        unless _page
+        unless page
           raise ActiveRecord::RecordNotFound if options[:raise]
           return nil
         end
 
-        URI.join(root_url(subdomain: _page.subdomain.try(:name)), _page.path).to_s
+        page
       end
     end
   end

data/lib/simplec/embedded_image_actions.rb

@@ -1,5 +1,7 @@
 module Simplec
   module EmbeddedImageActions
+
+    # @private
     module ClassMethods; end
 
     module InstanceMethods

data/lib/simplec/engine.rb

@@ -1,18 +1,18 @@
-require 'simplec/action_controller/extensions'
-require 'simplec/action_view/helper'
-
 module Simplec
   class Engine < ::Rails::Engine
     isolate_namespace Simplec
 
     initializer "simplec_controller_extensions" do
       ActiveSupport.on_load(:action_controller_base) {
-        prepend Simplec::ActionController::Extensions
+        include Simplec::ActionController::Extensions
+        prepend Simplec::PageActionHelpers
         helper Simplec::ActionView::Helper
       }
-      ActiveSupport.on_load(:active_record) {
-        Dir["#{Rails.root}/app/models/page/*.rb"].each {|file| require_dependency file }
-      }
+      ActiveSupport.on_load(:active_record) { Simplec.load_pages }
     end
   end
+
+  def self.load_pages
+    Dir["#{Rails.root}/app/models/page/*.rb"].each {|file| require_dependency file }
+  end
 end

data/lib/simplec/page_action_helpers.rb

@@ -0,0 +1,29 @@
+module Simplec
+  module PageActionHelpers
+
+    # @private
+    module ClassMethods; end
+
+    module InstanceMethods
+
+      private
+
+      def render_path(path)
+        @page = page(path)
+        render template: 'simplec/pages/show', layout: layout(@page)
+      end
+
+      def layout(page)
+        # TODO allow config for public
+        [page.layout, page.subdomain.default_layout, 'public'].
+          reject(&:blank?).first
+      end
+
+    end
+
+    def self.included(receiver)
+      receiver.extend         ClassMethods
+      receiver.send :include, InstanceMethods
+    end
+  end
+end

data/lib/simplec/version.rb

@@ -1,3 +1,3 @@
 module Simplec
-  VERSION = '0.3.0'
+  VERSION = '0.4.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: simplec
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Matt Smith
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-08-15 00:00:00.000000000 Z
+date: 2017-08-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -143,6 +143,7 @@ files:
 - lib/simplec/action_view/helper.rb
 - lib/simplec/embedded_image_actions.rb
 - lib/simplec/engine.rb
+- lib/simplec/page_action_helpers.rb
 - lib/simplec/version.rb
 - lib/tasks/simplec_tasks.rake
 homepage: https://github.com/nearapogee/simplec