cadmus 0.5.3 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: baa8f826659300b741b1fac079ee71bb74315514
-  data.tar.gz: 1422e3236c83edcc178b76867f568e4cd4122149
+  metadata.gz: 215a6a345f843d05ef56b703311301119d8bd685
+  data.tar.gz: 171b52fb98dcd2779c8fa28f8128a8705aea3411
 SHA512:
-  metadata.gz: e8e8447ace4df8e75b8910fb9d2d6f5e50b39200fd91a264f497122326aa38c66c3c07a827085f5b0431399a45564e35a5723c1822db1f35b718141f44d34a95
-  data.tar.gz: 47f2c14c40f57c03a5b4b22284245c6f3b69c37a067fc2c78cbaaecc35aa1f47fc9ac7b2f81f8dc5ad8de383bcc98af1df33bfc1e7101deca9dc62f469385ac1
+  metadata.gz: 138d7e20134104dd9b7f1252def6317678df7038b0ff920569673878437f72f4aeffeed5abd7c980e017ecae568f72b217ea0cb13b4b4d26bb3e4f2d79f56bbe
+  data.tar.gz: 17f27f48c748c06284811f8b3e7cdcbe549986a97b2a4214146b2e5b24e6ba0e54f4edafa5970ee8c229c3e89f8cf06c942f56a755833f5e22f2b382187f3b3b

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+## cadmus 0.6.0 (04-08-2017)
+
+* Expose a `{% page_url %}` tag, which outputs the URL to a page (for easier inter-page linking)
+* Expose a Liquid register called `parent` from controllers that mix in `Cadmus::ControllerExtensions`, which contains the page parent (if present)
+* Extract a mixin module called `Cadmus::LiquidTemplateField`, which makes it easier to add Liquid templates to models
+
 ## cadmus 0.5.3 (02-04-2017)
 
 * Make it possible to make `liquid_assigns`, `liquid_filters` and `liquid_registers` private or protected methods in controllers and other Renderables.

data/README.md

@@ -14,7 +14,7 @@ ORM you want instead of ActiveRecord.
 
 One additional feature is the ability for pages to have parents.  A parent can be any model object.  Page parent objects allow
 you to create separate "sections" of your site - for example, if you have a project-hosting application that includes multiple
-projects, each of which has its own separate space of CMS pages.  (Page parents aren't intended for creating sub-pages - 
+projects, each of which has its own separate space of CMS pages.  (Page parents aren't intended for creating sub-pages -
 instead, just use forward-slash characters in the page slug to simulate folders, and Cadmus will handle it.)
 
 ## Basic Installation
@@ -30,14 +30,14 @@ The next step is to create a Page model.  Your app can have multiple Page models
 create one.
 
     rails generate model Page name:text slug:string content:text parent_id:integer parent_type:string
-	
-You'll need to tweak the generated migration and model slightly.  In the migration, after the `create_pages` block, add a 
+
+You'll need to tweak the generated migration and model slightly.  In the migration, after the `create_pages` block, add a
 unique index on the parent and slug columns:
 
 ```ruby
 add_index :pages, [:parent_type, :parent_id, :slug], :unique => true
 ```
-	
+
 And in the model, add a `cadmus_page` declaration:
 
 ```ruby
@@ -77,7 +77,7 @@ class PagesController < ApplicationController
   def page_params
     params.require(:page).permit(:name, :slug, :content)
   end
-  
+
   def page_class
     Page
   end
@@ -89,6 +89,16 @@ define a `page_class` method that returns the class for pages it's dealing with.
 classes depending on request parameters, if you need it to - or, you could also set up different controllers for different
 types of page.)
 
+You'll also want to set up an initializer (probably in `config/initializers/cadmus.rb`) that will tell Cadmus how to generate URLs for pages.  This might look like this:
+
+```ruby
+Cadmus::Tags::PageUrl.define_page_path_method do |page_name, parent|
+  page_path(page_name, parent_id: parent)
+end
+```
+
+Doing this will enable markup like this in page templates: `<a href="{% page_url my-other-page %}">My other page</a>`.  The `{% page_url my-other-page %}` will be replaced with the actual URL for the page called `my-other-page`.
+
 Finally, you'll need to create routes for this controller.  Cadmus provides a built-in helper for that:
 
 ```ruby
@@ -96,7 +106,7 @@ MyApp::Application.routes.draw do
   cadmus_pages
 end
 ```
-	
+
 This will create the following routes:
 
 * GET /pages => PagesController#index
@@ -109,15 +119,15 @@ This will create the following routes:
 
 ## Authorization Control
 
-The pages controller is where you'll need to hook into any authorization or authentication system your app might use.  
+The pages controller is where you'll need to hook into any authorization or authentication system your app might use.
 We use CanCan, so here's an example of how we do that:
 
 ```ruby
 class PagesController < ApplicationController
   include Cadmus::PagesController
-  
+
   authorize_resource :page
-  
+
   protected
   def page_class
     Page
@@ -130,7 +140,7 @@ class Ability
   def initialize(user)
     can :read, Page
       return unless user
-	
+
       # in this example, we've added an owner_id column to our Page model
       can :manage, Page, :owner_id => user.id
   end
@@ -154,7 +164,7 @@ DugoutCoach::Application.routes.draw do
     resources :players
       resources :schedule
   end
-  
+
   cadmus_pages # for global pages on your site
 end
 ```
@@ -177,20 +187,20 @@ end
 ```
 
 Now you have a way of separating team-specific pages from global pages on the site.  The URLs for these pages might be,
-for example, http://dugoutcoach.net/teams/cosmonauts/directions, or 
+for example, http://dugoutcoach.net/teams/cosmonauts/directions, or
 http://dugoutcoach.net/teams/cosmonauts/promotions/free-hat-day (remember, Cadmus slugs can contain slashes).  We'll
 now need a TeamPages controller to handle these:
 
 ```ruby
 class TeamPagesController < ApplicationController
   include Cadmus::PagesController
-  
+
   self.page_parent_class = Team   # page's parent is a Team
   self.page_parent_name = "team"  # parent ID is in params[:team_id]
   self.find_parent_by = "slug"    # parent ID is the Team's "slug" field rather than "id"
-  
+
   authorize_resource :page
-  
+
   protected
   def page_class
     Page
@@ -215,7 +225,7 @@ DugoutCoach::Application.routes.draw do
       resources :schedule
       cadmus_pages :controller => :team_pages, :shallow => true
   end
-  
+
   cadmus_pages
 end
 ```
@@ -245,7 +255,7 @@ help them by providing them with a Liquid template variable they can use like so
 
 ```html
 <h1>We're the Cosmonauts!</h1>
-   
+
 <p>Our uniform color this week is {{ team.uniform_color }}!</p>
 ```
 
@@ -254,19 +264,19 @@ To do this, you'll need to expose `team` as a Liquid assign variable:
 ```ruby
 class TeamPagesController < ApplicationController
   include Cadmus::PagesController
-  
+
   self.page_parent_class = Team   # page's parent is a Team
   self.page_parent_name = "team"  # parent ID is in params[:team_id]
   self.find_parent_by = "slug"    # parent ID is the Team's "slug" field rather than "id"
-  
+
   authorize_resource :page
-  
+
   protected
 
   def page_class
     Page
   end
-    
+
   def liquid_assigns
     { :team => @page.parent }
   end
@@ -285,10 +295,66 @@ class Team < ActiveRecord::Base
   # everything else in your model...
 end
 ```
-    
+
 You could also define a `to_liquid` method that returns a `Liquid::Drop` subclass for Teams, if you need to do things
 more complicated than just return data values.
 
+## Liquid Templates on Non-Page Models
+
+Let's say you have another model in your app that you'd like to put a Liquid template on.  For example, perhaps the baseball teams would like to send out a welcome email to their fans.  You might create a `WelcomeEmail` model with a `content` field.
+
+Cadmus provides a convenience mixin to let you make that field a Liquid template.  You can use it like so:
+
+```ruby
+class WelcomeEmail < ActiveRecord::Base
+  include Cadmus::LiquidTemplateField
+
+  liquid_template_field :content_liquid_template, :content
+
+  belongs_to :team
+end
+```
+
+Now if you call `my_welcome_email.content_liquid_template`, you'll get a parsed `Liquid::Template` generated from the value of `my_welcome_email.content`.  You could further make the WelcomeEmail into a `Cadmus::Renderable` to make it render the template:
+
+```ruby
+class WelcomeEmail < ActiveRecord::Base
+  include Cadmus::LiquidTemplateField
+  include Cadmus::Renderable
+
+  liquid_template_field :content_liquid_template, :content
+
+  belongs_to :team
+
+  def rendered_content
+    cadmus_renderer.render(content_liquid_template, :html)
+  end
+end
+```
+
+Presto!  Now you can call `my_welcome_email.rendered_content`.  Since `WelcomeEmail` includes `Cadmus::Renderable`, you can also define `liquid_assigns` to expose variables to the template, for example:
+
+```ruby
+class WelcomeEmail < ActiveRecord::Base
+  include Cadmus::LiquidTemplateField
+  include Cadmus::Renderable
+
+  liquid_template_field :content_liquid_template, :content
+
+  belongs_to :team
+
+  def rendered_content
+    cadmus_renderer.render(content_liquid_template, :html)
+  end
+
+  def liquid_assigns
+    { 'team' => team }
+  end
+end
+```
+
+And now the welcome email templates can include `{{ team.name }}` and any other things derived from the Team model they want.
+
 ## Copyright and Licensing
 
-Copyright &copy; 2011-2012 Gively, Inc.  Cadmus is released under the MIT license.  For more information, see the LICENSE file.
+Copyright &copy; Gively, Inc.  Cadmus is released under the MIT license.  For more information, see the LICENSE file.

data/lib/cadmus.rb

@@ -3,7 +3,9 @@ require "cadmus/routing"
 require "cadmus/renderers"
 require "cadmus/controller_extensions"
 require "cadmus/slugs"
+require "cadmus/liquid_template_field"
 require "cadmus/page"
+require "cadmus/tags"
 require "rails"
 
 module Cadmus

data/lib/cadmus/controller_extensions.rb

@@ -221,5 +221,15 @@ module Cadmus
         raise ActiveRecord::RecordNotFound.new("No page called #{params[:page_glob]}") unless @page
       end
     end
+
+    def liquid_registers
+      registers = { 'parent' => page_parent }
+
+      if defined?(super)
+        registers.merge(super)
+      else
+        registers
+      end
+    end
   end
 end

data/lib/cadmus/liquid_template_field.rb

@@ -0,0 +1,19 @@
+module Cadmus
+  module LiquidTemplateField
+    extend ActiveSupport::Concern
+
+    module ClassMethods
+      def liquid_template_field(method_name, field_name)
+        define_method method_name do
+          content = send(field_name)
+
+          begin
+            Liquid::Template.parse(content)
+          rescue Exception => exception
+            Liquid::Template.parse("#{exception.class.name}: #{exception.message}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/cadmus/page.rb

@@ -1,14 +1,15 @@
 require 'liquid'
 
 module Cadmus
-  
+
   # Adds a +cadmus_page+ extension method to ActiveRecord::Base that sets up a class as a page-like object for
   # Cadmus.
   module Page
     extend ActiveSupport::Concern
-    
+    include Cadmus::LiquidTemplateField
+
     module ClassMethods
-      
+
       # Sets up a model to behave as a Cadmus page.  This will add the following behaviors:
       #
       # * A slug and slug generator field using HasSlug
@@ -33,19 +34,15 @@ module Cadmus
         self.name_field = (options.delete(:name_field) || :name).to_s
 
         belongs_to :parent, :polymorphic => true
-                
+
         validates_presence_of name_field
         validates_uniqueness_of slug_field, :scope => [:parent_id, :parent_type]
         validates_exclusion_of slug_field, :in => %w(pages edit)
-  
+
         scope :global, lambda { where(:parent_id => nil, :parent_type => nil) }
-        
-        class_eval do
-          def liquid_template
-            Liquid::Template.parse(content)
-          end
-        end
-      end      
+
+        liquid_template_field :liquid_template, :content
+      end
     end
   end
 end

data/lib/cadmus/tags.rb

@@ -0,0 +1,35 @@
+module Cadmus
+  module Tags
+    class PageUrl < ::Liquid::Tag
+      class << self
+        attr_reader :page_path_method
+
+        def define_page_path_method(&page_path_method)
+          @page_path_method = page_path_method
+        end
+      end
+
+      attr_reader :page_name
+
+      def initialize(tag_name, args, tokens)
+        super
+        @page_name = args.strip
+      end
+
+      def render(context)
+        unless self.class.page_path_method
+          return "Error: #{self.class.name}.page_path_method is not defined.  Please call #{self.class.name}.define_page_path_method in an initializer."
+        end
+
+        begin
+          parent = context.registers['parent']
+          Rails.application.routes.url_helpers.instance_exec(page_name, parent, &self.class.page_path_method)
+        rescue Exception => e
+          e.message
+        end
+      end
+    end
+  end
+end
+
+Liquid::Template.register_tag('page_url', Cadmus::Tags::PageUrl)

data/lib/cadmus/version.rb

@@ -1,3 +1,3 @@
 module Cadmus
-  VERSION = "0.5.3"
+  VERSION = "0.6.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cadmus
 version: !ruby/object:Gem::Version
-  version: 0.5.3
+  version: 0.6.0
 platform: ruby
 authors:
 - Nat Budin
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-02-04 00:00:00.000000000 Z
+date: 2017-04-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -65,11 +65,13 @@ files:
 - cadmus.gemspec
 - lib/cadmus.rb
 - lib/cadmus/controller_extensions.rb
+- lib/cadmus/liquid_template_field.rb
 - lib/cadmus/markdown.rb
 - lib/cadmus/page.rb
 - lib/cadmus/renderers.rb
 - lib/cadmus/routing.rb
 - lib/cadmus/slugs.rb
+- lib/cadmus/tags.rb
 - lib/cadmus/version.rb
 - lib/generators/cadmus/views_generator.rb
 homepage: http://github.com/gively/cadmus