cadmus 0.4.1

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.yardopts

@@ -0,0 +1,3 @@
+--protected
+--markup-provider=redcarpet
+--markup=markdown

data/Gemfile

@@ -0,0 +1,8 @@
+source 'http://rubygems.org'
+
+# Specify your gem's dependencies in cadmus.gemspec
+gemspec
+
+gem 'yard'
+gem 'redcarpet', '~> 1.0'
+gem 'github-markup'

data/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2011-2012 Gively, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,241 @@
+# Cadmus: an embeddable CMS for Rails
+
+Cadmus is an embeddable content management system for Rails 3 applications.  It's based on [Liquid](http://liquidmarkup.org)
+and is designed to be small and unobtrusive.
+
+Cadmus doesn't define controllers or models itself, but rather, provides mixins to add CMS-like functionality to controllers
+and models you create.  This allows a great deal of customization.  For example, Cadmus doesn't provide any user authentication
+or authorization functionality, but because it hooks into controllers in your app, you can add virtually any authorization
+system you want.
+
+Similarly, Cadmus doesn't provide a Page model, but rather, a mixin for creating page-like models.  This theoretically allows
+you to add functionality to your Page objects, include multiple different page-like models, or use any ActiveModel-compatible
+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 - 
+instead, just use forward-slash characters in the page slug to simulate folders, and Cadmus will handle it.)
+
+## Basic Installation
+
+First, add Cadmus to your Gemfile:
+
+    gem 'cadmus'
+    gem 'redcarpet'   # (required only if you intend to use Cadmus' Markdown support)
+
+The next step is to create a Page model.  Your app can have multiple Page models if you like, but for this example, we'll just
+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 
+unique index on the parent and slug columns:
+
+    add_index :pages, [:parent_type, :parent_id, :slug], :unique => true
+	
+And in the model, add a `cadmus_page` declaration:
+
+    class Page < ActiveRecord::Base
+	  cadmus_page
+	end
+
+You'll need a controller to deal with your pages.  Here's a minimal example of one:
+
+    class PagesController < ApplicationController
+	  include Cadmus::PagesController
+	  
+	  protected
+	  def page_class
+	    Page
+	  end
+	end
+
+`Cadmus::PagesController` automatically adds the seven RESTful resource methods to your controller.  It requires that you
+define a `page_class` method that returns the class for pages it's dealing with.  (This could potentially return different
+classes depending on request parameters, if you need it to - or, you could also set up different controllers for different
+types of page.)
+
+Finally, you'll need to create routes for this controller.  Cadmus provides a built-in helper for that:
+
+    MyApp::Application.routes.draw do
+	  cadmus_pages
+	end
+	
+This will create the following routes:
+
+* GET /pages => PagesController#index
+* GET /pages/new => PagesController#new
+* POST /pages => PagesController#create
+* GET /pages/slug => PagesController#show
+* PUT /pages/slug => PagesController#update
+* DELETE /pages/slug => PagesController#destroy
+
+## Authorization Control
+
+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:
+
+    class PagesController < ApplicationController
+	  include Cadmus::PagesController
+	  
+	  authorize_resource :page
+	  
+	  protected
+	  def page_class
+	    Page
+	  end
+	end
+	
+	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
+	end
+
+Easy-peasy.  You can use other authorization plugins in a similar way - with Cadmus, you control the CMS models,
+controllers and routes, so you can add whatever code is appropriate for your app.
+
+## Pages With Parents
+
+Suppose you've got an app that hosts web sites for local baseball teams.  Your app lets the teams manage their own
+sites, and do stuff like add their team logo, uniform colors, roster, etc.  Now you'd like to let them add custom
+content pages as well.
+
+You already have the following routes set up in your routes.rb file:
+
+    DugoutCoach::Application.routes.draw do
+	  resources :teams do
+	    resources :players
+        resources :schedule
+	  end
+	  
+	  cadmus_pages # for global pages on your site
+	end
+
+So, for example, the URL for the Cambridge Cosmonauts might be http://dugoutcoach.net/teams/cosmonauts.  They also
+have http://dugoutcoach.net/teams/cosmonauts/players and http://dugoutcoach.net/teams/cosmonauts/schedule.
+
+You can add a "pages" namespace pretty easily:
+
+    DugoutCoach::Application.routes.draw do
+	  resources :teams do
+	    resources :players
+        resources :schedule
+        cadmus_pages :controller => :team_pages
+	  end
+	  
+	  cadmus_pages
+	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 
+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:
+
+    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
+	end
+
+Note that for this example, we've kept the same `Page` class for both controllers.  We could have also created a
+separate `TeamPage` model, but that's not required.
+
+### Shallow Page URLs
+
+The Cambridge Cosmonauts are unhappy!  Their URLs are too long.  Why should the pages in their team site have a "/pages/"
+in them just because they created them themselves?
+
+Chill out, Cosmonauts.  Cadmus makes it easy:
+
+    DugoutCoach::Application.routes.draw do
+	  resources :teams do
+	    resources :players
+        resources :schedule
+        cadmus_pages :controller => :team_pages, :shallow => true
+	  end
+	  
+	  cadmus_pages
+	end
+
+Now the PagesController's `show`, `edit`, `update`, and `destroy` actions don't use the "/pages/" part of the URL.  The
+URLs now look like this:
+
+* GET /teams/cosmonauts/pages => PagesController#index
+* GET /teams/cosmonauts/pages/new => PagesController#new
+* POST /teams/cosmonauts/pages => PagesController#create
+* GET /teams/cosmonauts/page-slug => PagesController#show
+* GET /teams/cosmonauts/page-slug/edit => PagesController#edit
+* PUT /teams/cosmonauts/page-slug => PagesController#update
+* DELETE /teams/cosmonauts/page-slug => PagesController#destroy
+
+When you use shallow page URLs, it's important to put the `cadmus_pages` declaration as the last one in the block,
+because it's going to put a path-globbing wildcard in the scope from which it's called.  Thus, it should be the
+lowest-priority route in its context.
+
+## Liquid Variables
+
+The Cambridge Cosmonauts have a policy of changing their uniform color on a weekly basis.  Why?  I don't know.  Go
+Cosmonauts!
+
+Needless to say, they don't want to go editing every single page where they mention that.  Fortunately, you can
+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>
+```
+
+To do this, you'll need to expose `team` as a Liquid assign variable:
+
+    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
+	end
+
+Defining a `liquid_assigns` method will cause Cadmus to use the return value of that method as the Liquid assigns hash.
+(Similarly, you can define `liquid_filters` and `liquid_registers` methods that do what they say on the tin.)
+
+You'll also need to make your Team model usable from Liquid.  The simplest way to do that is using `liquid_methods`:
+
+    class Team < ActiveRecord::Base
+      liquid_methods :name, :uniform_color
+      
+      # 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.
+
+## Copyright and Licensing
+
+Copyright &copy; 2011-2012 Gively, Inc.  Cadmus is released under the MIT license.  For more information, see the LICENSE file.

data/Rakefile

@@ -0,0 +1,2 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"

data/app/assets/javascripts/cadmus.previewablehtml.js

@@ -0,0 +1,22 @@
+(function($) {
+	$.fn.cadmusPreviewableHtml = function() {
+		this.each(function() {
+			var textarea = this;
+			var $this = $(this);
+			var $previewIn = $("#" + $this.attr('data-preview-in'));
+			
+			$this.on('cadmus.htmlChange', function(){
+				$previewIn.html($this.val());
+			});
+			
+			textarea.cadmusTextValue = "";
+			setInterval(function() {
+			  var newCadmusTextValue = $this.val();
+			  if (textarea.cadmusTextValue != newCadmusTextValue) {
+				textarea.cadmusTextValue = newCadmusTextValue;
+				$this.trigger('cadmus.htmlChange');
+			  }
+			}, 100);
+		});
+	};
+})(jQuery);

data/app/views/cadmus/pages/_form.html.erb

@@ -0,0 +1,44 @@
+<% if @page.errors.any? %>
+	<div id="error_explanation">
+		<h2><%= pluralize(@page.errors.count, "error") %> prohibited this page from being saved:</h2>
+
+		<ul>
+		<% @page.errors.full_messages.each do |msg| %>
+			<li><%= msg %></li>
+		<% end %>
+		</ul>
+	</div>
+<% end %>
+
+<div class="field">
+	<%= f.label :name %>
+	<%= f.text_field :name %>
+</div>
+<div class="field">
+	<%= f.label :slug, "URL" %>
+	<p>
+		<%= url_for(:action => 'index', :only_path => false).sub(/pages$/, '') %>
+		<%= f.text_field :slug %>
+	</p>
+</div>
+<p>Type html in the box below and see a preview right under it</p>
+<div class="field">
+	<%= f.label :content %>
+	<%= f.text_area :content, :style => "font-family: monospace; width: 60em;", 
+		:class => "cadmus-previewable-html", :"data-preview-in" => "html-preview" %>
+</div>
+<div class="actions">
+	<%= f.submit %>
+</div>
+
+<%= javascript_include_tag "cadmus.previewablehtml.js" %>
+<script type="text/javascript">
+$(document).ready(function(){		
+  $('.cadmus-previewable-html').cadmusPreviewableHtml();
+});
+</script>
+<p><b>Rendered html preview</b></p>
+<div id="html-preview" style="border:1px solid;">
+</div>
+<br/><br/>
+

data/app/views/cadmus/pages/edit.html.erb

@@ -0,0 +1,8 @@
+<h1>Editing page "<%= @page.name %>"</h1>
+
+<%= form_for(@page, :url => { :action => :update, :page_glob => @page.slug }, :class => "edit_cadmus_page") do |f| %>
+	<%= render :partial => 'cadmus/pages/form', :locals => { :f => f } %>
+<% end -%>
+
+<%= link_to 'Show', { :action => 'show', :page_glob => @page.slug } %> |
+<%= link_to 'Back', { :action => 'index' } %>

data/app/views/cadmus/pages/index.html.erb

@@ -0,0 +1,17 @@
+<h1>
+	<% if @page_parent && @page_parent.respond_to?(:name) -%>
+		<%= @page_parent.name %>
+	<% else -%>
+		Pages
+	<% end -%>
+</h1>
+
+<ul class="cadmus_page_list">
+<% @pages.each do |page| %>
+  <li><%= link_to page.name, { :action => 'show', :page_glob => page.slug } %></li>
+<% end %>
+</ul>
+
+<br />
+
+<%= link_to 'New Page', :action => 'new' %>

data/app/views/cadmus/pages/new.html.erb

@@ -0,0 +1,7 @@
+<h1>New page</h1>
+
+<%= form_for(@page, :url => { :action => :create }, :class => "new_cadmus_page") do |f| %>
+	<%= render :partial => 'cadmus/pages/form', :locals => { :f => f } %>
+<% end -%>
+
+<%= link_to 'Back', { :action => 'index' } %>

data/app/views/cadmus/pages/show.html.erb

@@ -0,0 +1 @@
+<%= cadmus_renderer.render(@page.liquid_template, :html) %>

data/cadmus.gemspec

@@ -0,0 +1,20 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/cadmus/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Nat Budin", "Aziz Khoury"]
+  gem.email         = ["natbudin@gmail.com", "bentael@gmail.com"]
+  gem.description   = %q{Why deal with setting up a separate CMS?  Cadmus is just a little bit of CMS and fits nicely into your existing app.  It can be used for allowing users to customize areas of the site, for creating editable "about us" pages, and more.}
+  gem.summary       = %q{Embeddable CMS for Rails 3 apps}
+  gem.homepage      = "http://github.com/gively/cadmus"
+
+  gem.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  gem.files         = `git ls-files`.split("\n")
+  gem.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  gem.name          = "cadmus"
+  gem.require_paths = ["lib"]
+  gem.version       = Cadmus::VERSION
+
+  gem.add_dependency("rails", ">= 3.0.0")
+  gem.add_dependency("liquid")
+end

data/lib/cadmus/controller_extensions.rb

@@ -0,0 +1,221 @@
+module Cadmus
+  
+  # A controller mixin that includes all the RESTful resource actions for viewing and administering Cadmus
+  # pages.  This mixin provides a great deal of flexibility for customizing the behavior of the resulting
+  # controller.
+  #
+  # Controllers that include this mixin are expected to define at least a page_class method, which returns
+  # the class to be used for pages in this context.
+  #
+  # == Examples
+  #
+  # A basic PagesController for a site:
+  #
+  #    class PagesController < ApplicationController
+  #      include Cadmus::PagesController
+  #
+  #      # no action methods are necessary because PagesController defines them for us
+  #
+  #      protected
+  #      def page_class
+  #        Page
+  #      end
+  #      # Page must be defined as a model that includes Cadmus::Page
+  #
+  #    end
+  #
+  # A PagesController using CanCan for authorization control:
+  #
+  #    class PagesController < ApplicationController
+  #      include Cadmus::PagesController
+  #
+  #      # no need for load_resource because PagesController does that for us
+  #      authorize_resource :page
+  #
+  #      protected
+  #      def page_class
+  #        Page
+  #      end
+  #    end
+  #
+  # A controller for pages inside a Book object.  This controller uses URLs of the form 
+  # +/books/:book_id/pages/...+  The book_id parameter is a slug, not an ID.  First, here's
+  # the Book model:
+  #
+  #    class Book < ActiveRecord::Base
+  #      # This association has to be called "pages" because that's what BookPagesController
+  #      # will expect to use to find them.
+  #      has_many :pages, :class_name => "BookPage"
+  #      
+  #      validates_uniqueness_of :slug
+  #    end
+  #
+  #    class BookPagesController < ApplicationController
+  #      include Cadmus::PagesController
+  #      
+  #      self.page_parent_class = Book   # pages must have a Book as their parent
+  #      self.page_parent_name = "book"  # use params[:book_id] for finding Books
+  #      self.find_parent_by = "slug"    # use the Book's slug field for finding Books
+  #
+  #      protected
+  #      def page_class
+  #        BookPage
+  #      end
+  #    end
+	module PagesController
+		extend ActiveSupport::Concern
+		include Cadmus::Renderable
+		
+		included do
+			class << self
+				attr_accessor :page_parent_name, :page_parent_class, :find_parent_by
+			end
+			
+			before_filter :load_parent_and_page
+		  helper_method :cadmus_renderer
+		end
+	
+		def index
+			@pages = page_scope.order(:name).all
+			
+			respond_to do |format|
+				format.html { render 'cadmus/pages/index' }
+				format.xml  { render :xml => @pages }
+        format.json { render :json => @pages }
+			end
+		end
+		
+		def show
+			respond_to do |format|
+				format.html { render 'cadmus/pages/show' }
+				format.xml  { render :xml => @page }
+        format.json { render :json => @page }
+			end
+		end
+		
+		def new
+			@page = page_scope.new(params[:page])
+			
+			respond_to do |format|
+				format.html { render 'cadmus/pages/new' }
+				format.xml  { render :xml => @page }
+        format.json { render :json => @page }
+			end
+		end
+		
+		def edit			
+			render 'cadmus/pages/edit'
+		end
+		
+		def create
+			@page = page_scope.new(params[:page])
+			
+			respond_to do |format|
+				if @page.save
+					dest = { :action => 'show', :page_glob => @page.slug }
+					format.html { redirect_to(dest, :notice => 'Page was successfully created.') }
+					format.xml  { render :xml => @page, :status => :created, :location => dest }
+          format.json { render :json => @page, :status => :created, :location => dest }
+				else
+					format.html { render 'cadmus/pages/new' }
+					format.xml  { render :xml => @page.errors, :status => :unprocessable_entity }
+          format.json { render :json => @page.errors, :status => :unprocessable_entity }
+				end
+			end
+		end
+		
+		def update
+			respond_to do |format|
+				if @page.update_attributes(params[:page])
+					dest = { :action => 'show', :page_glob => @page.slug }
+					format.html { redirect_to(dest, :notice => 'Page was successfully updated.') }
+					format.xml  { head :ok }
+          format.json { head :ok }
+				else
+					format.html { render 'cadmus/pages/edit' }
+					format.xml  { render :xml => @page.errors, :status => :unprocessable_entity }
+					format.json { render :json => @page.errors, :status => :unprocessable_entity }
+				end
+			end
+		end
+		
+		def destroy
+			@page.destroy
+		
+			respond_to do |format|
+				format.html { redirect_to(:action => :index) }
+				format.xml  { head :ok }
+        format.json { head :ok }
+			end
+		end
+			
+		protected
+      
+    # This gets kind of meta.
+    #
+    # If page_parent_name and page_parent_class are both defined for this class, this method uses it to find
+    # the parent object in which pages live.  For example, if page_parent_class is Blog and page_parent_name
+    # is "blog", then this is equivalent to calling:
+    #
+    #     @page_parent = Blog.where(:id => params["blog_id"]).first
+    #
+    # If you don't want to use :id to find the parent object, then redefine the find_parent_by method to return
+    # what you want to use.
+		def page_parent
+			return @page_parent if @page_parent
+			
+			if page_parent_name && page_parent_class
+				parent_id_param = "#{page_parent_name}_id"
+				if params[parent_id_param]	
+					@page_parent = page_parent_class.where(find_parent_by => params[parent_id_param]).first
+				end
+			end
+				
+			@page_parent
+		end
+		
+    # Returns the name of the page parent object.  This will be used for determining the parameter name for
+    # finding the parent object.  For example, if the page parent name is "wiki", the finder will look in
+    # params["wiki_id"] to determine the object ID.
+    #
+    # By default, this will return the value of page_parent_name set at the controller class level, but can 
+    # be overridden for cases where the page parent name must be determined on a per-request basis.
+		def page_parent_name
+      self.class.page_parent_name
+		end
+		
+    # Returns the class of the page parent object.  For example, if the pages used by this controller are
+    # children of a Section object, this method should return the Section class.
+    #
+    # By default, this will return the value of page_parent_class set at the controller class level, but can
+    # be overridden for cases where the page parent class must be determined on a per-request basis.
+		def page_parent_class
+		  self.class.page_parent_class
+		end
+		
+    # Returns the field used to find the page parent object.  By default this is :id, but if you need to
+    # find the page parent object using a different parameter (for example, if you use a "slug" field for
+    # part of the URL), this can be changed.
+    #
+    # By default this method takes its value from the "find_parent_by" accessor set at the controller class
+    # level, but it can be overridden for cases where the finder field name should be determined on a
+    # per-request basis.
+		def find_parent_by
+			self.class.find_parent_by || :id
+		end
+		
+    # Returns the ActiveRecord::Relation that will be used for finding pages.  If there is a page parent
+    # for this request, this will be the "pages" scope defined by the parent object.  If there isn't,
+    # this will be the "global" scope of the page class (i.e. pages with no parent object).
+		def page_scope
+			@page_scope ||= page_parent ? page_parent.pages : page_class.global
+		end
+		
+		def load_parent_and_page
+			if params[:page_glob]
+				@page = page_scope.find_by_slug(params[:page_glob])
+				raise ActiveRecord::RecordNotFound.new("No page called #{params[:page_glob]}") unless @page
+			end
+		end
+	end
+end

data/lib/cadmus/markdown.rb

@@ -0,0 +1,124 @@
+require 'redcarpet'
+require 'cadmus/renderers'
+
+module Cadmus
+  module Markdown
+    # A Redcarpet renderer that outputs HTML and uses SmartyPants smart
+    # quotes.
+    class HtmlRenderer < Redcarpet::Render::HTML
+      include Redcarpet::Render::SmartyPants
+    end
+    
+    # A Redcarpet renderer that outputs formatted plain text (that looks quite similar to
+    # the Markdown input sent to it).
+    class TextRenderer < Redcarpet::Render::Base
+      def normal_text(text)
+        text
+      end
+      
+      def block_code(text, language)
+        normal_text(text)
+      end
+      
+      def codespan(text)
+        normal_text(text)
+      end
+      
+      def header(title, level)
+        case level
+        when 1
+          "#{title.upcase}\n#{'=' * title.length}\n\n"
+        when 2
+          "#{title}\n#{'-' * title.length}\n\n"
+        when 3
+          "#{title.upcase}\n\n"
+        end
+      end
+      
+      def double_emphasis(text)
+        "**#{text}**"
+      end
+      
+      def emphasis(text)
+        "*#{text}*"
+      end
+      
+      def linebreak
+        "\n"
+      end
+      
+      def paragraph(text)
+        "#{text}\n\n"
+      end
+      
+      def list(content, list_type)
+        "#{content}\n"
+      end
+      
+      def list_item(content, list_type)
+        "  * #{content}"
+      end
+    end
+  end
+  
+  module Renderers
+    
+    # A Cadmus renderer that handles Markdown input using the Redcarpet rendering engine.
+    # It can produce +:html+ and +:text+ formats, using Cadmus::Markdown::HtmlRenderer
+    # and Cadmus::Markdown::TextRenderer.
+    #
+    # Liquid is rendered first, then the result is processed as Markdown.
+    class Markdown < Base
+      
+      # Additional options to be passed as the second argument to the Redcarpet::Markdown
+      # constructor.
+      attr_accessor :markdown_options
+      
+      def initialize
+        super
+        @markdown_options = {}
+      end
+      
+      def markdown_options=(opts)
+        @markdown_options = opts
+        @redcarpet_instance = nil
+      end
+      
+      def preprocess(template, format, options={})
+        redcarpet_instance.render(super)
+      end
+      
+      private
+      def markdown_renderer(format)
+        case format.to_sym
+        when :html
+          Cadmus::Markdown.HtmlRenderer
+        when :text
+          Cadmus::Markdown.TextRenderer
+        else
+          raise "Format #{format.inspect} is not supported by #{self.class.name}"
+        end
+      end
+      
+      def redcarpet_instance(format)
+        Redcarpet::Markdown.new(markdown_renderer(format), markdown_options)
+      end
+    end
+  end
+  
+  # An alternative to Cadmus::Renderable that will use Cadmus::Renderers::Markdown as the
+  # renderer class.  Additionally, it will set the renderer's +markdown_options+ to the
+  # return value of the +markdown_options+ method, if that method is defined.
+  module MarkdownRenderable
+    include Renderable
+    
+    def setup_renderer
+      super
+      renderer.markdown_options = markdown_options if respond_to?(:markdown_options)
+    end
+    
+    def cadmus_renderer_class
+      Cadmus::Renderers::Markdown
+    end
+  end
+end

data/lib/cadmus/page.rb

@@ -0,0 +1,53 @@
+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
+    
+    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
+      # * A name field that determines the name of the page for administrative UI
+      # * An optional, polymorphic +parent+ field
+      # * A scope called +global+ that returns instances of this class that have no parent
+      # * A +liquid_template+ method that parses the value of this model's +content+ field as a Liquid
+      #   template
+      # * Validators that ensure that this page has a name, that this page's slug is unique within the
+      #   parent object, and that the slug isn't "pages" or "edit" (which are used for admin UI)
+      #
+      # @param options [Hash] options to modify the default behavior
+      # @option options :name_field the name of the field to be used as the page name.  Defaults to +:name+.
+      # @option options :slug_field the name of the field to be used as the page slug.  Defaults to +:slug+.
+      # @option options :slug_generator_field the name of the field to be used as the slug generator.
+      #   Defaults to the value of +name_field+ if unspecified.
+      def cadmus_page(options={})
+        options[:slug_generator_field] = options[:name_field] unless options.has_key?(:slug_generator_field)
+        has_slug(options)
+
+        cattr_accessor :name_field
+        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, :conditions => { :parent_id => nil, :parent_type => nil }
+        
+        class_eval do
+          def liquid_template
+            Liquid::Template.parse(content)
+          end
+        end
+      end      
+    end
+  end
+end
+
+ActiveRecord::Base.send :include, Cadmus::Page

data/lib/cadmus/renderers.rb

@@ -0,0 +1,122 @@
+module Cadmus
+  
+  # A Cadmus renderer is an object that handles the rendering of +Liquid::Template+s to output formats
+  # such as HTML or plain text.  A renderer provides several features over and above what plain
+  # Liquid does:
+  #
+  # * Automatic removal of HTML tags for plain text output
+  # * Integration with Rails 3's HTML escaping functionality
+  # * Ability to specify default assigns, filters, and registers and augment them on a per-call basis
+  # * Ability to render to multiple output formats from a single renderer
+  module Renderers
+    
+    # The simplest Cadmus renderer.  It will render Liquid templates to HTML and plain text (removing the
+    # HTML tags from the plain text output).
+    class Base
+      attr_accessor :default_assigns, :default_filters, :default_registers, :html_sanitizer
+      
+      def initialize
+        self.default_registers = {}
+        self.default_filters = []
+        self.default_assigns = {}
+        
+        self.html_sanitizer = Rails.application.config.action_view.full_sanitizer || HTML::FullSanitizer.new
+      end
+      
+      # The preprocess method performs the initial rendering of the Liquid template using the a combination
+      # of the default_filters, default_assigns, default_registers, and any :assigns, :filters, and :registers
+      # options passed in as options.
+      #
+      # @param [Liquid::Template] template the Liquid template to render.
+      # @param [Symbol] format the format being used for rendering.  (This is ignored in the Base implementation
+      #   of +preprocess+ and is only used in Base's +render+ method, but is passed here in case subclasses wish to
+      #   make use of the format information when overriding preprocess.)
+      # @param [Hash] options additional options that can be passed to override default rendering behavior.
+      # @option options [Hash] :assigns additional assign variables that will be made available to the template.
+      # @option options [Hash] :registers additional register variables that will be made available to the template.
+      # @option options [Hash] :filters additional filters to be made available to the template.
+      # @return [String] the raw results of rendering the Liquid template.
+      def preprocess(template, format, options={}) 
+        render_args = [
+          default_assigns.merge(options[:assigns] || {}), 
+          { 
+            :filters   => default_filters + (options[:filters] || []),
+            :registers => default_registers.merge(options[:registers] || {})
+          }
+        ]  
+        
+        template.render(*render_args)
+      end
+      
+      # Render a given Liquid template to the specified format.  This renderer implementation supports +:html+ and
+      # +:text+ formats, but other implementations may support other formats.
+      #
+      # @param [Liquid::Template] template the Liquid template to render.
+      # @param [Symbol] format the format being used for rendering.  +:html+ will result in a string that's marked
+      #   as safe for HTML rendering (and thus won't be escaped by Rails).  +:text+ will strip all HTML tags out
+      #   of the template result.
+      # @param [Hash] options additional rendering options.  See the +preprocess+ method for a description of
+      #   available options.
+      def render(template, format, options={})
+        content = preprocess(template, format, options)
+        
+        case format.to_sym
+        when :html
+          content.html_safe
+        when :text
+          html_sanitizer.sanitize content
+        else
+          raise "Format #{format.inspect} unsupported by #{self.class.name}"
+        end
+      end
+    end
+  end
+  
+  # A helper module that can be included in classes that wish to provide a Cadmus renderer.  For
+  # example, an Email class might want to provide a renderer so that it can be easily transformed
+  # into HTML or text formats.
+  #
+  # This will expose a +cadmus_renderer+ method that constructs a new renderer.  Optionally, you
+  # can implement methods called +liquid_assigns+, +liquid_registers+, and +liquid_filters+, which
+  # will specify the default assigns, registers, and filters for the renderer.  You can also
+  # override the +cadmus_renderer_class+ method if you want to use a renderer class aside from
+  # Cadmus::Renderers::Base.
+  #
+  # == Example
+  #
+  #     class Email < ActiveRecord::Base
+  #       include Cadmus::Renderable
+  #
+  #       def liquid_template
+  #         Liquid::Template.new(self.content)
+  #       end
+  #
+  #       def liquid_assigns
+  #         { recipient: self.recipient, sender: self.sender, sent_at: self.sent_at }
+  #       end
+  #     end
+  module Renderable
+    
+    # @return a new Cadmus renderer set up using the +default_assigns+, +default_registers+
+    #   and +default_filters+ methods, if they exist.
+    def cadmus_renderer
+      cadmus_renderer_class.new.tap { |renderer| setup_renderer(renderer) }
+    end
+    
+    # @return the Cadmus renderer class to instanciate in the +cadmus_renderer+ method.  By
+    #   default, Cadmus::Renderers::Base.
+    def cadmus_renderer_class
+      Cadmus::Renderers::Base
+    end
+    
+    protected
+    # Sets the values of +default_assigns+, +default_registers+ and +default_filters+ on a given
+    # renderer using the +liquid_assigns+, +liquid_registers+ and +liquid_filters+ methods, if
+    # they're defined.
+    def setup_renderer(renderer)
+      renderer.default_assigns = liquid_assigns if respond_to?(:liquid_assigns)
+      renderer.default_registers = liquid_registers if respond_to?(:liquid_registers)
+      renderer.default_filters = liquid_filters if respond_to?(:liquid_filters)
+    end
+  end
+end

data/lib/cadmus/routing.rb

@@ -0,0 +1,69 @@
+module Cadmus
+  # A routing constraint that determines whether a request has a valid Cadmus page glob.  A
+  # page glob consists of one or more valid slug parts separated by forward slashes.  A valid
+  # slug part consists of a lower-case letter followed by any combination of lower-case letters,
+  # digits, and hyphens.
+	class SlugConstraint
+    # @param request an HTTP request object.
+    # @return [Boolean] true if this request's +:page_glob+ parameter is a valid Cadmus page
+    #   glob, false if it's not.  Allows +:page_glob+ to be nil only if the Rails environment
+    #   is +test+, because +assert_recognizes+ doesn't always pass the full params hash
+    #   including globbed parameters.
+		def matches?(request)
+			page_glob = request.symbolized_path_parameters[:page_glob]
+			
+			# assert_recognizes doesn't pass the full params hash as we would in a real Rails
+			# application.  So we have to always pass this constraint if we're testing.
+			return true if page_glob.nil? && Rails.env.test?
+			
+			page_glob.sub(/^\//, '').split(/\//).all? do |part|
+				part =~ /^[a-z][a-z0-9\-]*$/
+			end
+		end
+	end
+end
+
+ActionDispatch::Routing::Mapper.class_eval do
+  # Defines a "cadmus_pages" DSL command you can use in config/routes.rb.  This sets up a Cadmus
+  # PagesController that will accept the following routes:
+  #
+  # * GET /pages -> PagesController#index
+  # * GET /pages/new -> PagesController#new
+  # * POST /pages -> PagesController#create
+  # * GET /pages/anything/possibly-including/slashes/edit -> PagesController#edit
+  # * GET /pages/anything/possibly-including/slashes -> PagesController#show
+  # * PUT /pages/anything/possibly-including/slashes -> PagesController#update
+  # * DELETE /pages/anything/possibly-including/slashes -> PagesController#destroy
+  #
+  # cadmus_pages accepts two additional options:
+  #
+  # * :controller - changes which controller it maps to.  By default, it is "pages" (meaning PagesController).
+  # * :shallow - if set to "true", the edit, show, update and destroy routes won't include the "/pages" prefix.  Useful if you're
+  #   already inside a unique prefix.
+	def cadmus_pages(options)	
+		options = options.with_indifferent_access
+		
+		controller = options[:controller] || 'pages'
+		
+		get "pages" => "#{controller}#index", :as => 'pages'
+		get "pages/new" => "#{controller}#new", :as => 'new_page'
+		post "pages" => "#{controller}#create"
+
+		slug_constraint = Cadmus::SlugConstraint.new
+		
+		page_actions = Proc.new do
+			get "*page_glob/edit" => "#{controller}#edit", :as => 'edit_page', :constraints => slug_constraint
+			get "*page_glob" => "#{controller}#show", :as => 'page', :constraints => slug_constraint
+			put "*page_glob" => "#{controller}#update", :constraints => slug_constraint
+			delete "*page_glob" => "#{controller}#destroy", :constraints => slug_constraint
+		end
+		
+		if options[:shallow]
+			instance_eval(&page_actions)
+		else
+			scope 'pages' do
+				instance_eval(&page_actions)
+			end
+		end
+	end
+end

data/lib/cadmus/slugs.rb

@@ -0,0 +1,83 @@
+module Cadmus
+  module Slugs
+    
+    # Tests whether a string is a valid Cadmus slug or not.  A valid Cadmus slug
+    # consists of one or more valid slug parts separated by forward slashes.  A valid
+    # slug part consists of a lower-case letter followed by any combination of lower-case letters,
+    # digits, and hyphens.
+    #
+    # For example, +about-us/people+, +special-deals+, and +winter-2012+ are all valid slugs, but
+    # +3-things+, +123+, +nobody-lives-here!+, and +/root-page+ aren't.
+    SLUG_REGEX = /^([a-z][a-z0-9\-]*\/)*[a-z][a-z0-9\-]*$/
+  
+    # Converts a string to a valid slug part by changing all whitespace to hyphens, converting all
+    # upper-case letters to lower-case, removing all remaining non-alphanumeric, non-hyphen
+    # characters, and removing any non-alphabetical characters at the beginning of the string.
+    #
+    # For example:
+    # * "Katniss Everdeen" becomes "katniss-everdeen"
+    # * "21 guns" becomes "guns"
+    # * "We love you, Conrad!!!1" becomes "we-love-you-conrad1"
+    def self.slugify(string)
+      string.to_s.downcase.gsub(/\s+/, '-').gsub(/[^a-z0-9\-]/, '').sub(/^[^a-z]+/, '')
+    end
+    
+    # An extension for ActiveRecord::Base that adds a +has_slug+ method.  This can also be
+    # safely included in non-ActiveRecord objects to allow for a similar method, but those
+    # objects have to at least include ActiveModel::Validations.
+    module HasSlug
+      extend ActiveSupport::Concern
+      
+      module ClassMethods
+        
+        # Sets up an automatic slug-generating field on this class.  There is a slug field,
+        # which will store the resulting slug, and a slug generator field, which, if set,
+        # will automatically generate a slugified version of its content and store it in
+        # the slug field.
+        #
+        # Additionally, +has_slug+ sets up a format validator for the slug field to ensure
+        # that it's a valid Cadmus slug, and defines +to_param+ to return the slug (so
+        # that links to the slugged object can use the slug in their URL).
+        #
+        # +has_slug+ attempts to be smart about detecting when the user has manually set a
+        # slug for the object and not overwriting it.  Auto-generated slugs are only used
+        # when there is not already a slug set.
+        #
+        # @param [Hash] options options to override the default behavior.
+        # @option options slug_field the name of the slug field.  Defaults to +:slug+.
+        # @option options slug_generator_field the name of the slug generator field.  Defaults
+        #   to +:name+.
+        def has_slug(options={})
+          cattr_accessor :slug_field, :slug_generator_field
+          
+          self.slug_field = (options.delete(:slug_field) || :slug).to_s
+          self.slug_generator_field = (options.delete(:slug_generator_field) || :name).to_s
+          
+          validates_format_of slug_field, :with => Cadmus::Slugs::SLUG_REGEX
+          
+          class_eval <<-EOF
+          def #{slug_generator_field}=(new_value)
+            write_attribute(:#{slug_generator_field}, new_value)
+            if #{slug_field}.blank?
+              self.#{slug_field} = Cadmus::Slugs.slugify(new_value)
+              @auto_assigned_slug = true
+            end
+          end
+          
+          # If the user enters a title and no slug, don't overwrite the auto-assigned one
+          def #{slug_field}=(new_slug)
+            return if new_slug.blank? && @auto_assigned_slug
+            write_attribute(:#{slug_field}, new_slug)
+          end
+          
+          def to_param
+            #{slug_field}
+          end
+          EOF
+        end
+      end
+    end
+  end
+end
+
+ActiveRecord::Base.send :include, Cadmus::Slugs::HasSlug

data/lib/cadmus/version.rb

@@ -0,0 +1,3 @@
+module Cadmus
+  VERSION = "0.4.1"
+end

data/lib/cadmus.rb

@@ -0,0 +1,12 @@
+require "cadmus/version"
+require "cadmus/routing"
+require "cadmus/renderers"
+require "cadmus/controller_extensions"
+require "cadmus/slugs"
+require "cadmus/page"
+require "rails"
+
+module Cadmus
+  class Engine < Rails::Engine
+  end
+end

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification
+name: cadmus
+version: !ruby/object:Gem::Version
+  version: 0.4.1
+  prerelease: 
+platform: ruby
+authors:
+- Nat Budin
+- Aziz Khoury
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-04-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: &70361178912560 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: *70361178912560
+- !ruby/object:Gem::Dependency
+  name: liquid
+  requirement: &70361178912140 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70361178912140
+description: Why deal with setting up a separate CMS?  Cadmus is just a little bit
+  of CMS and fits nicely into your existing app.  It can be used for allowing users
+  to customize areas of the site, for creating editable "about us" pages, and more.
+email:
+- natbudin@gmail.com
+- bentael@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .yardopts
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- app/assets/javascripts/cadmus.previewablehtml.js
+- app/views/cadmus/pages/_form.html.erb
+- app/views/cadmus/pages/edit.html.erb
+- app/views/cadmus/pages/index.html.erb
+- app/views/cadmus/pages/new.html.erb
+- app/views/cadmus/pages/show.html.erb
+- cadmus.gemspec
+- lib/cadmus.rb
+- lib/cadmus/controller_extensions.rb
+- lib/cadmus/markdown.rb
+- lib/cadmus/page.rb
+- lib/cadmus/renderers.rb
+- lib/cadmus/routing.rb
+- lib/cadmus/slugs.rb
+- lib/cadmus/version.rb
+homepage: http://github.com/gively/cadmus
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.11
+signing_key: 
+specification_version: 3
+summary: Embeddable CMS for Rails 3 apps
+test_files: []
+has_rdoc: