noumenon 0.0.3 → 0.1.0

data/lib/noumenon/template.rb

@@ -1,88 +1,129 @@
+require 'noumenon'
 require 'liquid'
 
-module Noumenon
-  # Templates specify the structure and presentation of a particular piece of content in
-  # a Noumenon site, and are usually provided by a theme.
+# Templates specify the structure and presentation of a particular piece of content in
+# a Noumenon site, and are usually provided by a theme.
+#
+# A template is split into two parts, the metadata, which defines what data is needed for
+# the template, and a Liquid template, which defines how the data should be presented. When
+# loaded from a file, a template will look like this:
+#
+#   title:
+#     label: Page title
+#     required: true
+#     type: string
+#     help: The title displayed at the top of the page
+#   author:
+#     label: Author
+#     required: false
+#     type: string
+#     help: The author of the article. If not provided, no byline will be shown.
+#   body:
+#     label: Body text
+#     required: true
+#     type: text
+#     help: The main article body. Will be processed with Textile for formatting.
+#   ---
+#   <h1>{{ title }}</h1>
+#   {% if author %}
+#     <p class="byline">By {{ author }}</p>
+#   {% endif %}
+#   {{ body | textilize }}
+# 
+# And can be rendered like this:
+#   
+#  Template.from_file("/path/to/template").render("title" => "An Example Page", "author" => "Jon Wood", "body" => "This is an article...")
+#  
+# If any required fields are missing from the data provided then a MissingContentError will be raised.
+#
+# @api public
+class Noumenon::Template
+  # Indicates one or more required fields were not provided to the template.
   #
-  # A template is split into two parts, the metadata, which defines what data is needed for
-  # the template, and a Liquid template, which defines how the data should be presented. When
-  # loaded from a file, a template will look like this:
+  # The missing fields are listed in the error message.
   #
-  #     title:
-  #       label: Page title
-  #       required: true
-  #       type: string
-  #       help: The title displayed at the top of the page
-  #     author:
-  #       label: Author
-  #       required: false
-  #       type: string
-  #       help: The author of the article. If not provided, no byline will be shown.
-  #     body:
-  #       label: Body text
-  #       required: true
-  #       type: text
-  #       help: The main article body. Will be processed with Textile for formatting.
-  #     ---
-  #     <h1>{{ title }}</h1>
-  #     {% if author %}
-  #       <p class="byline">By {{ author }}</p>
-  #     {% endif %}
-  #     {{ body | textilize }}
-  # 
-  #  And can be rendered like this:
+  # @api public
+  class MissingContentError < StandardError; end
+
+  # Indicates the requested template could not be found.
   #
-  #      Template.from_file("/path/to/template").render("title" => "An Example Page", "author" => "Jon Wood", "body" => "This is an article...")
-  #  
-  #  If any required fields are missing from the data provided then a MissingContentError will be raised.
-  class Template
-    class MissingContentError < StandardError; end
-    class NotFoundError < StandardError; end
-    
-    # The location this template was loaded from.
-    attr_accessor :source
+  # @api public
+  class NotFoundError < StandardError; end
+  
+  # The location this template was loaded from.
+  # @api public
+  attr_accessor :source
 
-    # The template view.
-    attr_accessor :content
+  # The template view.
+  # @api public
+  attr_accessor :content
 
-    # The fields used by this template.
-    attr_accessor :fields
+  # The fields used by this template.
+  # @api public
+  attr_accessor :fields
+  
+  # Loads a template from the specified path.
+  #
+  # @api public
+  # 
+  # @param [ String, #to_s ] path the file to load the template from
+  # @raise [ Noumenon::Template::NotFoundError ] the template could not be found
+  # @return [ Noumenon::Template ] the loaded template
+  # @api public
+  def self.from_file(path)
+    raise NotFoundError.new("No template could be found at #{path}.") unless File.exists?(path)
     
-    # Loads a template from the specified path.
-    #
-    # If the file does not exist then a NotFoundError will be raised.
-    def self.from_file(path)
-      raise NotFoundError.new("No template could be found at #{path}.") unless File.exists?(path)
-      
-      content = File.read(path)
+    content = File.read(path)
 
-      parts = content.split("\n---\n")
-      if parts.size == 1
-        fields = {}
-      else
-        fields = YAML.load(parts.first)
-        content = parts.last
-      end
-
-      self.new(path, content, fields)
+    parts = content.split("\n---\n")
+    if parts.size == 1
+      fields = {}
+    else
+      fields = YAML.load(parts.first)
+      content = parts.last
     end
 
-    def initialize(source = nil, content = nil, fields = {})
-      @source = source
-      @content = content
-      @fields = fields
-    end
+    self.new(path, content, fields)
+  end
+  
+  # Creates a new Template instance.
+  #
+  # @api public
+  #
+  # @param [ #to_s ] source the location the template was loaded from
+  # @param [ #to_s ] content the Liquid template to render
+  # @param [ Hash, #each ] fields the list of fields used within the template
+  #
+  # @example Loading a template from a database
+  #   fields = load_field_rows.inject({}) do |fields, row|
+  #     fields[row[:name]] = { "required" => row[:required], "type" => row[:type] }
+  #   end
+  #
+  #   Noumenon::Template.new("mysql://localhost/database/table#row_32", row[:content], fields)
+  #
+  # @api public
+  def initialize(source = nil, content = nil, fields = {})
+    @source = source
+    @content = content
+    @fields = fields
+  end
+  
+  # Renders the template.
+  # 
+  # @param [ Hash, #each ] page_content the content to provide to the template
+  # @raise [ Noumenon::Template::MissingContentError ] one or more required fields were not provided
+  # @return [ #to_s ] the rendered template
+  # @api public
+  def render(page_content = {})
+    fields_from_page = page_content.stringify_keys
     
-    # Renders the template. If any fields are missing from page_content then a MissingContentError will be raised.
-    def render(page_content = {})
-      missing_fields = []
-      fields.each do |key, field|
-        missing_fields << key if field["required"] && !page_content.key?(key)
-      end
+    missing_fields = []
+    fields.each do |key, field|
+      missing_fields << key if field["required"] && !fields_from_page.key?(key)
+    end
 
-      raise MissingContentError.new("The following fields were missing from your content: #{missing_fields.sort.join(", ")}") unless missing_fields.empty?
+    raise MissingContentError.new("The following fields were missing from your content: #{missing_fields.sort.join(", ")}") unless missing_fields.empty?
 
-      Liquid::Template.parse(content).render(page_content)
-    end
+    Liquid::Template.parse(content).render(fields_from_page)
   end
 end

data/lib/noumenon/theme/assets_middleware.rb

@@ -0,0 +1,21 @@
+require 'noumenon/theme'
+require 'sinatra'
+
+# Handles requests for assets within loaded themes.
+#
+# Any request to /themes/Theme Name/* will be served from the theme's assets directory,
+# with existing files being served, and non-existant files generating a 404.
+#
+# The middleware is automatically added to the stack if you're running using Noumenon.server
+#
+# @api public
+class Noumenon::Theme::AssetsMiddleware < Sinatra::Base
+  get '/themes/:theme/*' do |theme, asset|
+    halt 404, "File Not Found" unless Noumenon::Theme.themes.key? theme
+
+    asset_path = File.join(Noumenon::Theme.themes[theme].path, "assets", asset)
+    halt 404, "File Not Found" unless File.exist?(asset_path)
+
+    send_file(asset_path)
+  end
+end

data/lib/noumenon/theme.rb

@@ -0,0 +1,106 @@
+require 'noumenon'
+require 'yaml'
+
+# Provides access to a theme and it's contents.
+#
+# @api public
+class Noumenon::Theme
+  autoload :AssetsMiddleware, 'noumenon/theme/assets_middleware'
+  
+  # The specified theme could not be loaded, either because the path does not exist, or it does not
+  # contain a theme.yml file.
+  #
+  # @api public
+  class NotFoundError < RuntimeError; end
+  
+  # Load a theme from the specified path. Metadata about the theme will be laoded from "theme.yml",
+  # which should have the format shown in the example.
+  #
+  # If the theme is loaded succesfully it will also be registered in the theme list.
+  #
+  # @param [ String, #to_s ] path The path to load from.
+  # @raise [ Noumenon::Theme::NotFoundError ]
+  # @return [ Noumenon::Theme ] A populated theme.
+  # @see Noumenon::Theme.themes
+  def self.load(path)
+    unless File.exist?("#{path}/theme.yml")
+      raise NotFoundError.new("No theme was found at #{path}. Did you create a theme.yml file?")
+    end
+    
+    description = YAML.load(File.read("#{path}/theme.yml"))
+    theme = Noumenon::Theme.new(path, description)
+
+    themes[theme.name] = theme
+    theme
+  end
+  
+  # @return [ Hash ] A hash containing any loaded themes, keyed by their name.
+  # @api public
+  def self.themes
+    @themes ||= {}
+  end
+  
+  # The path the theme was loaded from.
+  # @api public
+  attr_reader :path
+ 
+  # The name to refer to this theme by. Loaded from theme.yml.
+  # @api public
+  attr_accessor :name
+  
+  # The author of this theme. Loaded from theme.yml.
+  # @api public
+  attr_accessor :author
+  
+  # The email address to contact regarding this theme. Loaded from theme.yml.
+  # @api public
+  attr_accessor :email
+  
+  # The copyright line to attribute this theme to. Loaded from theme.yml.
+  # @api public
+  attr_accessor :copyright
+  
+  # The license this theme is distributed under. Loaded from theme.yml.
+  # @api public
+  attr_accessor :license
+  
+  # Create a new them instance.
+  #
+  # @param [ String, #to_s ] path The path the theme was loaded from.
+  # @param [ Hash ] description Any metadata to attach to theme.
+  # @option description [ String ] :name The human readable name of the theme.
+  # @option description [ String ] :author The author of the theme.
+  # @option description [ String ] :email The email address to content regarding this theme.
+  # @option description [ String ] :copyright The copyright line to attribute this theme to.
+  # @option description [ String ] :license The license this theme is distributed under.
+  # @api public
+  def initialize(path, description = {})
+    @path = path
+    
+    description.each do |name, value|
+      if respond_to? "#{name}="
+        send "#{name}=", value
+      end
+    end
+  end
+
+  # Load a template from the theme's templates directory.
+  #
+  # @param [ String, #to_s ] name The path to load the template from. This path will be prefixed with "templates/"
+  # @return [ Noumenon::Template ] The loaded template.
+  # @raise [ Noumenon::Template::NotFoundError ]
+  # @api public
+  def template(name)
+    Noumenon::Template.from_file File.join(path, "templates", name)
+  end
+  
+  # Load a template from the theme's layouts directory.
+  #
+  # @param [ String, #to_s ] name The path to load the template from. This path will be prefixed with "layouts/"
+  # @return [ Noumenon::Template ] The loaded template.
+  # @raise [ Noumenon::Template::NotFoundError ]
+  # @api public
+  def layout(name)
+    Noumenon::Template.from_file File.join(path, "layouts", name)
+  end
+end

data/lib/noumenon/version.rb

@@ -1,3 +1,5 @@
 module Noumenon
-  VERSION = "0.0.3"
+  # The current version of Noumenon.
+  # @api public
+  VERSION = "0.1.0"
 end

data/lib/noumenon.rb

@@ -1,109 +1,77 @@
-require 'noumenon/configuration'
-require 'noumenon/template'
-require 'noumenon/core'
+require 'noumenon/version'
+require 'noumenon/string_extensions'
+require 'facets'
+require 'rack/builder'
 
+# @api public
 module Noumenon
-  class TemplateNotFoundError < StandardError; end
-  class MissingApplicationError < StandardError; end
+  autoload :Core, 'noumenon/core'
+  autoload :Repository, 'noumenon/repository'
+  autoload :Template, 'noumenon/template'
+  autoload :Theme, 'noumenon/theme'
+  autoload :Spec, 'noumenon/spec'
   
-  class << self
-    # Returns a configured Noumenon application. Intended for use in a Rack configuration:
-    # 
-    # By default the following URL handlers are put in place:
-    #
-    # */themes/#{theme_name}/*
-    # 
-    # The assets directory of all installed themes are made accessible so that themes can
-    # bundle stylesheets, javascripts, and other static assets.
-    #
-    # */*
-    #
-    # Anything below / is handled by Noumenon::Core, which will simply load a content item
-    # if it exists, and render it within the specified template.
-    #
-    # *Configuring Custom URL Handlers*
-    #
-    # By placing a file called "config.yml" in a directory you can change the URL handler for
-    # it. The "application" attribute sets the class that will handle that URL, for example:
-    #
-    #   application: "Noumenon::Applications::ContactForm"
-    #
-    # Example:
-    #
-    #   require 'noumenon'
-    #   Noumenon::Core.set :content_repository_path, "/srv/sites/example.org"
-    #
-    #   run Noumenon.boot
-    def boot
-      Rack::Builder.new do
-        Noumenon.themes.each do |name, details|
-          map("/themes/#{name}") { run Rack::File.new(File.join(details[:path], "assets")) }
-        end
-        
-        Dir.glob(File.join(Noumenon.config.content_repository_path, "**/config.yml")).each do |path|
-          config = YAML.load(File.read(path))
-
-          if config["application"]
-            begin
-              url = path.gsub(Noumenon.config.content_repository_path, "").split("/")[0..-2].join("/")
-              app = Noumenon.constantize(config["application"]).new
-              
-              map(url) { run app }
-            rescue NameError => e
-              raise MissingApplicationError.new("The application #{config["application"]} has not been loaded.")
-            end
-          end
-        end
-        
-        map("/") { run Core.new }
-      end
-    end
-    
-    # Attempts to convert a string into a constant.
-    #
-    # If the constant could not be found then NameError will be raised.
-    def constantize(name)
-      mod = Module
-      name.split("::").each do |mod_name|
-        mod = mod.const_get(mod_name.to_sym)
-      end
-
-      mod
+  # Starts Noumenon serving, this will usually be called from a config.ru file
+  # something like this:
+  #
+  #   Noumenon.content_repository = Noumenon::Repository::FileSystem.new("/home/noumenon/content")
+  #   Noumenon.theme = Noumenon::Theme.load("/home/noumenon/theme")
+  #
+  #   run Noumenon.server
+  #
+  # While you can also just use an instance Noumenon::Core, keep in mind that it won't
+  # have the full Rack middleware stack, and so some functionality such as serving assets 
+  # from themes won't be available.
+  #
+  # @api public
+  # @return [ Rack::Builder ] the Rack stack to serve a Noumenon site
+  def self.server
+    Rack::Builder.new do
+      use Noumenon::Theme::AssetsMiddleware
+      run Noumenon::Core
     end
+  end
+  
+  # Returns the current content repository.
+  #
+  # @api public
+  # @return [ Noumenon::Repository, #get, #put ]
+  def self.content_repository
+    @content_repository
+  end
     
-    # Provides access to the configuration of this application.
-    #
-    # If passed a block then the current configuration will be yielded in the form
-    # of a Noumenon::Configuration instance, allowing it to be changed.
-    #
-    #     Noumenon.config do |c|
-    #       c.theme = "example_theme"
-    #     end
-    #
-    def config
-      @config ||= Configuration.new
-      yield @config if block_given?
-      @config
-    end
-    alias :configure :config
-    
-    # Set the application configuration
-    #
-    # Should be provided with something that implements the same interface as Noumenon::Configuration.
-    def config=(config)
-      @config = config
+  # Sets the repository to load site content from.
+  #
+  # @api public
+  # @param [ Noumenon::Repository, #get, #put ] repository the repository to use
+  def self.content_repository=(repository)
+    @content_repository = repository
+  end
+  
+  # Returns the current theme
+  #
+  # @api public
+  # @return [ Noumenon::Theme ] the current theme
+  def self.theme
+    @theme
+  end
+  
+  # Set the current theme.
+  #
+  # If provided with a [ Noumenon::Theme ] object then it will set that, otherwise
+  # it will convert the argument to a string, and attempt to find a loaded theme with
+  # that name.
+  #
+  # @api public
+  # @param [ Noumenon::Theme, #to_s ] theme either a theme object, or the name of a loaded theme
+  # @return [ Noumenon::Theme, nil ] the specified theme, or nil if it could not be found
+  def self.theme=(theme)
+    if theme.is_a? Noumenon::Theme
+      @theme = theme
+    else
+      self.theme = Noumenon::Theme.themes[theme]
     end
     
-    # Returns details of any registered themes.
-    def themes
-      @themes ||= {}
-    end
-
-    # Registers a theme for use by Noumenon.
-    #
-    # Any files in the assets/ directory below the path provided will be accessible from /themes/theme_name.
-    def register_theme(name, path)
-      themes[name] = { :path => path }
-    end
+    @theme
   end
 end

data/noumenon.gemspec

@@ -9,10 +9,10 @@ Gem::Specification.new do |s|
   s.authors     = ["Jon Wood"]
   s.email       = ["jon@blankpad.net"]
   s.homepage    = "https://github.com/Noumenon"
-  s.summary     = %q{An content management system backed by Git}
+  s.summary     = %q{A flexible content management system.}
   s.description = <<EOF
-Noumenon is a content management system designed to be backed by a file system, with
-theme support.
+Noumenon is a content management system designed to support being extended with Sinatra
+applications.
 
 It's currently in an early stage of development, but right now you can create a basic
 static site using templates from a theme which specify the structure and presentation
@@ -22,9 +22,6 @@ templates.
 Future development will include an end-user friendly web interface for editing and
 creating content, while retaining the ability for developers and designers to manage
 the site's presentation using the tools they're most comfortable with.
-
-See http://github.com/Noumenon/example-app/ for a really bare bones example of how
-Noumenon works.
 EOF
 
   s.rubyforge_project = "noumenon"
@@ -34,9 +31,16 @@ EOF
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
   
+  s.add_dependency "facets", ">= 2.9.1"
+  s.add_dependency "liquid", ">= 2.2"
   s.add_dependency "sinatra", ">= 1.2.3"
-  s.add_dependency "liquid",  ">= 2.2"
-
+  
+  s.add_development_dependency "aruba",     ">= 0.3.6"
+  s.add_development_dependency "capybara",  ">= 1.0.0.beta1"
+  s.add_development_dependency "cucumber",  ">= 0.10.2"
+  s.add_development_dependency "rake",      ">= 0.9.0"
+  s.add_development_dependency "rdiscount", ">= 1.6.8"
   s.add_development_dependency "rspec",     ">= 2.5.0"
-  s.add_development_dependency "rack-test", ">= 0.5"
+  s.add_development_dependency "thor",      ">= 0.14.6"
+  s.add_development_dependency "yard",      ">= 0.7.1"
 end

data/spec/noumenon/repository/file_system_spec.rb

@@ -0,0 +1,115 @@
+require 'spec_helper'
+
+describe Noumenon::Repository::FileSystem do
+  let(:content_path) { File.join(File.dirname(__FILE__), "..", "..", "..", "..", "tmp", "content") }
+
+  around do |example|
+    FileUtils.mkdir_p content_path
+    example.run
+    FileUtils.rm_r content_path 
+  end
+  
+  subject do
+    Noumenon::Repository::FileSystem.new path: content_path
+  end
+
+  describe "initialization" do
+    context "when no path option is provided" do
+      it "should raise an ArgumentError" do
+        lambda { Noumenon::Repository::FileSystem.new }.should raise_error ArgumentError
+      end
+
+      it "should provide details of the error of how to resolve the error" do
+        begin
+          Noumenon::Repository::FileSystem.new
+        rescue ArgumentError => e
+          e.to_s.should == "You must provide a path to the content repository: Noumenon::Repository::FileSystem.new(path: '/tmp')"
+        end
+      end
+    end
+  end
+  
+  it { should respond_to(:put) }
+
+  describe "putting content in the repository" do
+    context "when writing to a top level file" do
+      it "creates a YAML file at the specified path" do
+        lambda { subject.put "example", { template: "static" } }.should create_file File.join(content_path, "example.yml")
+      end
+
+      it "writes the provided hash to the specified path" do
+        subject.put "example", { template: "static" }
+
+        YAML.load(File.read(File.join(content_path, "example.yml"))).should == { template: "static" }
+      end
+
+      it "symbolises any field keys" do
+        subject.put "example", { "template" => "static" }
+        YAML.load(File.read(File.join(content_path, "example.yml"))).should == { template: "static" }
+      end
+    end
+
+    context "when writing to a sub-directory" do
+      context "without an existing YAML file" do
+        it "creates the tree leading to the file" do
+          lambda { subject.put "sub_directory/example", { template: "static" } }.should create_file File.join(content_path, "sub_directory", "example.yml")
+        end
+      end
+
+      context "when a file in the path already exists" do
+        before(:each) { subject.put "sub_directory", { example: true } }
+
+        it "creates the tree to the file" do
+          lambda { subject.put "sub_directory/example", { template: "static" } }.should create_directory File.join(content_path, "sub_directory")
+        end
+
+        it "it moves the existing file into an index.yml file in the path" do
+          lambda { subject.put "sub_directory/example", { template: "static" } }.should move_file({
+            from: File.join(content_path, "sub_directory.yml"), 
+            to: File.join(content_path, "sub_directory", "index.yml")
+          })
+        end
+      end
+
+      context "when the directory specified already exists" do
+        before(:each) { FileUtils.mkdir File.join(content_path, "sub_directory") }
+
+        it "creates the file as index.yml within the directory" do
+          lambda { subject.put "sub_directory", { template: "static" } }.should create_file File.join(content_path, "sub_directory", "index.yml")
+        end
+      end
+    end
+  end
+
+  describe "retrieving content from the repository" do
+    context "when the item does not exist" do
+      it "returns nil" do
+        subject.get("not_found").should be_nil
+      end
+    end
+
+    context "when the item exists" do
+      it "returns it's content in hash form" do
+        subject.put "example", { template: "static" }
+        subject.get("example").should == { template: "static" }
+      end
+
+      it "supports items with string based keys" do
+        File.open(File.join(content_path, "example.yml"), "w") { |f| f.print("template: foo") }
+        subject.get("example").should == { template: "foo" }
+      end
+    end
+
+    context "when the item is a directory" do
+      it "returns the contents of index.yml if it exists" do
+        subject.put "example/index", { template: "static" }
+        subject.get("example").should == { template: "static" }
+      end
+
+      it "returns nil if no index.yml exists" do
+        subject.put "example/page", { template: "static" }
+        subject.get("example").should be_nil
+      end
+    end
+  end
+end