noumenon 0.0.3 → 0.1.0

data/.gitignore

@@ -2,3 +2,6 @@
 .bundle
 Gemfile.lock
 pkg/*
+.yardoc
+doc
+tmp

data/.travis.yml

@@ -1,6 +1,2 @@
 rvm:
-  - 1.8.7
   - 1.9.2
-  - ree
-  - rbx
-  - jruby

data/.yardopts

@@ -0,0 +1,5 @@
+--query @api.text == "public"
+--title "Noumenon"
+lib/**/*.rb
+lib/*.rb -
+README.md MIT-LICENSE

data/Gemfile

@@ -1,4 +1,2 @@
-source "http://rubygems.org"
-
-# Specify your gem's dependencies in noumenon.gemspec
+source :rubygems
 gemspec

data/README.md

@@ -1,6 +1,7 @@
 # Noumenon
 
-Noumenon: Noun. The intellectual conception of a thing as it is in itself, not as it is known through perception.
+I did have a description of where the name Noumenon came from here, but it doesn't actually fit that well. Maybe I'll
+come up with a better reason for th name choice some day.
 
 ## What is This Thing?
 
@@ -11,54 +12,30 @@ populate of a content management system using the tools they are most comfortabl
 In the case of developers (and some designers) that's version control and text editors, while in the case of content
 editors thats more likely to be a web interface.
 
-## How it Works
-
-A Noumenon site has two fundamental components, a content repository, and a theme.
-
-### The Content Repository
-
-The content repository is used to store items of content for the site. By default they're represented by YAML files
-in a directory tree which should match the URL structure you want to use:
+## Getting Started
 
-    /
-    - index.yml
-    - /about
-      - /index.yml
-      - /people.yml
-      - /company.yml
-    - /contact
-      - /config.yml
+If you want to skip the theory, and just play around with things in practice then your best bet is to run `noumenon site example_site`
+from a terminal, which will generate you a Gemfile, config.ru, content repository, and theme. If you want to run it
+any Rack based application server should work. I've tested under Thin and Unicorn, and Heroku will work if you want
+to publish a static site.
 
-In the example above visiting http://example.org/ will render the content in /index.yml, while visiting 
-http://example.org/about/people will render /about/people.yml
-
-Each item of content has this format:
-
-    template "page"
-    title: "People"
-    subtitle: "Our people are what makes us special"
-    body:
-      Here at Enormicorp we believe our people make us a great company.
-
-      Or at least the ones who's title starts with C and ends in O. Everyone else is just a cog really.
-
-When requested a template with a matching name will be loaded from the current theme, and rendered with the fields
-defined in the content item.
+## How it Works
 
+Noumenon splits your site into three parts:
 
 ### Themes
 
-Themes define how your content should be presented, and can provide templates and assets. A theme will usually come
-in the form of a Rubygem, either published to rubygems.org, or from some other source which Bundler can access.
-
-For an example, take a look at http://github.com/Noumenon/example_theme
+Themes define how your content should be presented, and can provide templates and assets. You can load a theme from any
+filesystem path in your config.ru file. In the near future Ruby Gem based themes will also be supported.
 
 #### Assets
 
 Assets such as images, stylesheets, and javascripts are placed in the "assets" directory, and are accessible from your 
-application at http://example.org/themes/theme_name/asset.png. The URL structure directly matches the directory structure
+application at http://example.org/themes/Theme Name/asset.png. The URL structure directly matches the directory structure
 of your assets directory.
 
+In the future some asset types will be served from the content repository instead, such as images embedded within a page.
+
 #### Templates
 
 The core of a theme is the templates it provides. Each template can list the fields that it supports, and mark some or all
@@ -92,38 +69,10 @@ If not specified the type defaults to "string", the label to a capitalised versi
 
 Any fields provided to a template which aren't specified will still be available in the Liquid template part.
 
-### Custom URL handlers
-
-If part of your site requires something other then rendering a piece of content within a static template then you can use a 
-custom URL handler to provide that part of the site. In this example we'll provide a basic contact form.
-
-#### Specifying the handler
-
-Within your content repository create a directory with the same name as the URL you want to mount the application at, and add
-a file called "config.yml" with the following content:
-
-    application: "Noumenon::Applications::ContactForm"
-
-This specifies that instead of using the core Noumenon application you want to use the ContactForm application, an example implementation
-is shown below - usually the application would be provided by a Rubygem or other source, and referenced in your Gemfile.
-
-#### The ContactForm Handler
-
-    class Noumenon::Applications::ContactForm < Noumenon::Core
-      get '/' do
-        render_template "templates/contact/form.html"
-      end
-
-      post '/send' do
-        require 'pony'
-        Pony.send :to => "contact@example.org", :body => params[:body], :from => params[:from]
-
-        render_template "templates/contact/thanks.html", "body" => params[:body], "from" => params[:from]
-      end
-    end
-
 #### Layouts
 
+*WARNING:* This isn't implemented in the current version.
+
 Layouts are used to wrap a piece of content with the overall look and feel of your website, and are provided with a single field
 "body" containing the rendered content. Currently only one layout per theme is supported, and it should be called "layout.html".
 
@@ -155,27 +104,53 @@ Layouts are used to wrap a piece of content with the overall look and feel of yo
       </body>
     </html>
 
-## Publishing Your Site
+### A Content Repository
+
+The site's content is stored within a repository. Each piece of content is represented by a set of key/value pairs, something
+like this:
 
-Currently the quickest way to get a Noumenon site on the internet is using Heroku. See http://github.com/Noumenon/example_site for
-an example of how to get that working.
+    template: team_member
+    name: Jon Wood
+    position: Head Honcho of Awesomeness
+    description: Do you need a description after a position like that?
 
-Note that once the admin backend is in place, Heroku may not be supported, and certainly won't be supported when using a filesystem
-based backend for your content repository.
+Currently the only available content repository uses YAML files to store your content, but shortly a MongoDB one will be created,
+and the API for content repositories is simple enough that just about any datastore could be used if you want to implement an
+adapater for it.
 
-### Example config.ru
+### Applications
 
-If you want to host on your own hardware use a config.ru like this:
+If part of your site requires something other then rendering a piece of content within a static template then you can use a 
+custom URL handler to provide that part of the site. In this example we'll provide a basic contact form.
 
-    require 'bundler/setup'
-    require 'noumenon'
+#### The ContactForm Handler
 
-    Noumenon.config do |c|
-      c.content_repository_path = "/path/to/content_repository"
-      c.theme = "noumenon-example_theme" # Requires you to have a reference to noumenon-example_theme in your Gemfile.
+    class Noumenon::Applications::ContactForm < Noumenon::Core
+      def initialize(options = {})
+        @to = options[:to]
+      end
+      
+      get '/' do
+        Noumenon.theme.template("templates/contact/form.html")
+      end
+
+      post '/send' do
+        require 'pony'
+        Pony.send :to => @to, :body => params[:body], :from => params[:from]
+
+        Noumenon.theme.template("templates/contact/thanks.html").render(body: params[:body], from: params[:from])
+      end
     end
 
-    run Noumenon.boot
+#### The Content item
+
+To mount an application you need to put a content item in the tree where you want it, so in this example we'll put this at "/contact":
+
+    type: application
+    application: Noumenon::Applications::ContactForm
+    to: info@example.org
+
+Make sure you've loaded the file that defines Noumenon::Applications::ContactForm.
 
 ## Getting Help and Contributing
 
@@ -185,6 +160,8 @@ on Noumenon as simple as possible. The best way to get in touch is to open an is
 If you'd like to contribute fork this repository, and then submit a pull request when you're done. Please make sure to include some tests
 so that your feature doesn't get broken in the future.
 
+There are full API docs available at http://rubydoc.info/gems/noumenon/ which are generated whenever a new version is published.
+
 ## License
 
 Noumenon is released under the MIT license by Blank Pad Development.

data/Rakefile

@@ -1,9 +1,20 @@
-require 'bundler'
-Bundler::GemHelper.install_tasks
+require 'rspec/core/rake_task'
+require 'cucumber/rake/task'
+require 'yard'
+require 'yard/rake/yardoc_task'
 
-task :default => "specs"
+task :default => [ :spec, :cucumber ]
 
-desc "Run all specs"
-task "specs" do
-  exec "rspec spec"
+RSpec::Core::RakeTask.new
+
+Cucumber::Rake::Task.new do |t|
+  t.cucumber_opts = %w(--format progress)
+end
+
+Cucumber::Rake::Task.new("cucumber:wip") do |t|
+  t.cucumber_opts = %w(--tags @wip:4 --wip)
+end
+
+YARD::Rake::YardocTask.new do |t|
+  t.name = :doc
 end

data/bin/noumenon

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+require 'noumenon/cli'
+require 'noumenon/version'
+
+puts "Noumenon #{Noumenon::VERSION}\n\n"
+Noumenon::Cli.start

data/features/dynamic_template_rendering.feature

@@ -0,0 +1,107 @@
+Feature: Rendering dynamic templates
+  As a designer
+  I want to render a content item within a template
+  So that the end user can update their site
+  
+  Background:
+    Given this template exists at "dynamic.nou.html"
+      """
+      title:
+        required: true
+      body:
+        required: true
+      ---
+      <h1>{{ title }}</h1>
+      <p>{{ body }}</p>
+      """
+
+  Scenario: All fields provided
+    Given this content item exists at "/dynamic"
+      | template | dynamic                           |
+      | title    | An example                        |
+      | body     | Some content within the template. |
+    When I view "/dynamic"
+    Then the page should load
+    And the headline should be "An example"
+    And the body text should be "Some content within the template."
+    
+  Scenario: Some fields are missing
+    Given this content item exists at "/dynamic"
+      | template | dynamic     |
+      | title    | An example  |
+    When I view "/dynamic"
+    Then the page should return a 500 error
+    And the headline should be "Missing Fields"
+    And the body text should be "The following fields were missing from your content: body"
+
+  Scenario: Rendering within the default layout
+    Given this layout exists at "default.nou.html"
+      """
+      <!doctype html>
+      <html>
+        <head>
+          <title>{{ title }}</title>
+        </head>
+
+        <body>
+          <header>
+            <h1>A Site</h1>
+          </header>
+          
+          <section id="content">
+            {{ content }}
+          </section>
+        </body>
+      </html>
+      """
+    And this content item exists at "/layout"
+      | template | dynamic             |
+      | title    | Hello, world!       |
+      | body     | Good morning world. |
+    When I view "/layout"
+    Then the page should load
+    And the page title should be "Hello, world!"
+    And the page header should be "A Site"
+    And the body text should be "Good morning world."
+  
+  Scenario: Rendering with a non-default layout
+    Given this layout exists at "non_default_layout.nou.html"
+      """
+      <!doctype html>
+      <html>
+        <head>
+          <title>{{ title }}</title>
+        </head>
+
+        <body>
+          <header>
+            <h1>A Site</h1>
+          </header>
+          
+          <section id="content">
+            {{ content }}
+          </section>
+        </body>
+      </html>
+      """
+    And this content item exists at "/layout"
+      | template | dynamic             |
+      | layout   | non_default_layout  |
+      | title    | Hello, world!       |
+      | body     | Good morning world. |
+    When I view "/layout"
+    Then the page should load
+    And the page title should be "Hello, world!"
+    And the page header should be "A Site"
+    And the body text should be "Good morning world."
+  
+  Scenario: Rendering with a missing non-default layout
+    Given no layout exists at "non_default_layout.nou.html"
+    And this content item exists at "/layout"
+      | template | dynamic             |
+      | layout   | non_default_layout  |
+      | title    | Hello, world!       |
+      | body     | Good morning world. |
+    When I view "/layout"
+    Then the page should return a 500 error
+    And the body text should be "The layout 'non_default_layout' does not exist within the current theme."

data/features/generator/site_generator.feature

@@ -0,0 +1,25 @@
+Feature: Generating a Noumenon site
+  As a user
+  I want to generate a basic site
+  So that I don't I have to repeat the same steps everytime
+
+  Scenario: No arguments
+    When I run `bundle exec ../../bin/noumenon`
+    Then the output should match /Noumenon ([\d]+\.[\d]+\.[\d]+)/
+    And the output should contain "Tasks:"
+    And the output should contain "noumenon help [TASK]"
+    And the output should contain "noumenon site PATH"
+
+  Scenario: Site generator specified, but no path
+    When I run `bundle exec ../../bin/noumenon site`
+    Then the output should contain:
+      """
+      "site" was called incorrectly. Call as "noumenon site PATH".
+      """
+
+  Scenario: Site generator specified with a path
+    When I run `bundle exec ../../bin/noumenon site example_site`
+    Then a directory named "example_site" should exist
+    And the directory "example_site" should contain a Noumenon site
+    And the directory "example_site/theme" should contain a theme
+    And the directory "example_site/content" should contain a repository

data/features/mounted_applications.feature

@@ -0,0 +1,30 @@
+Feature: Mounted Applications
+  As a developer
+  I want to mount an application at /app
+  So that I can provide extra functionality
+  In order to deliver the site my client wants
+
+  Scenario: An application has been mounted
+    Given this content item exists at "/app"
+      | type        | application                |
+      | application | Noumenon::Spec::ExampleApp |
+    When I view "/app"
+    Then the page should load
+    And the headline should be "This is a mounted application"
+  
+  Scenario: Loading paths below the mounted application
+    Given this content item exists at "/app"
+      | type        | application                |
+      | application | Noumenon::Spec::ExampleApp |
+    When I view "/app/sub"
+    Then the page should load
+    And the headline should be "This is a sub-page"
+
+  Scenario: Passing configuration to an application
+    Given this content item exists at "/app"
+      | type        | application                |
+      | application | Noumenon::Spec::ExampleApp |
+      | message     | Hello, world!              |
+    When I view "/app"
+    Then the page should load
+    And the headline should be "Hello, world!"

data/features/static_template_rendering.feature

@@ -0,0 +1,43 @@
+Feature: Rendering a static template
+  In order to display a non-dynamic page
+  As a designer
+  I want to render a static template
+
+  Scenario: Template exists
+    Given this template exists at "static.nou.html"
+      """
+      <h1>Static Template</h1>
+      <p>This is a static template which does not have any fields.</p>
+      """
+    And this content item exists at "/static"
+      | template | static |
+    When I view "/static"
+    Then the page should load
+    And the headline should be "Static Template"
+    And the body text should be "This is a static template which does not have any fields."
+  
+  Scenario: Template does not exist
+    Given no template exists at "static.nou.html"
+    And this content item exists at "/static"
+      | template | static |
+    When I view "/static"
+    Then the page should return a 500 error
+    And the headline should be "Missing Template"
+    And the body text should be "The template 'static' does not exist within the current theme."
+  
+  Scenario: Template is not specified
+    Given this template exists at "default.nou.html"
+      """
+      <h1>Default Template</h1>
+      """
+    And this content item exists at "/default"
+      | key | value |
+    When I view "/default"
+    Then the page should load
+    And the headline should be "Default Template"
+  
+  Scenario: Content item does not exist
+    Given no content item exists at "/static"
+    When I view "/static"
+    Then the page should return a 404 error
+    And the headline should be "Page Not Found"

data/features/step_definitions/asset_steps.rb

@@ -0,0 +1,7 @@
+Given /^the asset "([^"]*)" does not exist within the theme$/ do |asset_name|
+  # noop
+end
+
+Given /^the asset "([^"]*)" exists within the theme with this content:$/ do |asset_name, content|
+  File.open(File.join(Noumenon.theme.path, "assets", asset_name), "w") { |f| f.print content }
+end

data/features/step_definitions/content_steps.rb

@@ -0,0 +1,7 @@
+Given /^this content item exists at "([^"]*)"$/ do |path, fields|
+  Noumenon.content_repository.put(path, fields.rows_hash)
+end
+
+Given /^no content item exists at "([^"]*)"$/ do |path|
+  # noop
+end

data/features/step_definitions/generator_steps.rb

@@ -0,0 +1,22 @@
+def generator_file(generator, file)
+  File.read File.expand_path("../../../generators/#{generator}/#{file}", __FILE__)
+end
+
+Then /^the directory "([^"]*)" should contain a Noumenon site$/ do |path|
+  Then %Q{a file named "#{path}/Gemfile" should exist}
+   And %Q{a file named "#{path}/config.ru" should exist}
+  
+  check_exact_file_content "#{path}/Gemfile", generator_file("site", "Gemfile")
+  check_exact_file_content "#{path}/config.ru", generator_file("site", "config.ru")
+end
+
+Then /^the directory "([^"]*)" should contain a theme$/ do |path|
+  check_exact_file_content "#{path}/theme.yml", generator_file("theme", "theme.yml")
+  check_exact_file_content "#{path}/layouts/default.nou.html", generator_file("theme", "layouts/default.nou.html")
+  check_exact_file_content "#{path}/templates/default.nou.html", generator_file("theme", "templates/default.nou.html")
+  check_exact_file_content "#{path}/assets/style.css", generator_file("theme", "assets/style.css")
+end
+
+Then /^the directory "([^"]*)" should contain a repository$/ do |path|
+  check_exact_file_content "#{path}/index.yml", generator_file("repository", "index.yml")
+end

data/features/step_definitions/request_steps.rb

@@ -0,0 +1,31 @@
+When /^I view "([^"]*)"$/ do |path|
+  visit path
+end
+
+Then /^the page should load$/ do
+  page.status_code.should == 200
+end
+
+Then /^the page should return a (\d+) error$/ do |status|
+  page.status_code.should == status.to_i
+end
+
+Then /^the page content should be:$/ do |content|
+  page.source.should == content
+end
+
+Then /^the headline should be "([^"]*)"$/ do |headline|
+  page.should have_css "h1", :text => headline
+end
+
+Then /^the body text should be "([^"]*)"$/ do |body|
+  page.should have_css "p", :text => body
+end
+
+Then /^the page title should be "([^"]*)"$/ do |title|
+  page.should have_css "head title", :text => title
+end
+
+Then /^the page header should be "([^"]*)"$/ do |header|
+  page.should have_css "header h1", :text => header
+end

data/features/step_definitions/theme_steps.rb

@@ -0,0 +1,19 @@
+Given /^this template exists at "([^"]*)"$/ do |path, template|
+  File.open(File.join(Noumenon.theme.path, "templates", path), "w") do |f|
+    f.write(template)
+  end
+end
+
+Given /^no template exists at "([^"]*)"$/ do |path|
+  # noop
+end
+
+Given /^this layout exists at "([^"]*)"$/ do |path, template|
+  File.open(File.join(Noumenon.theme.path, "layouts", path), "w") do |f|
+    f.write(template)
+  end
+end
+
+Given /^no layout exists at "([^"]*)"$/ do |arg1|
+  # noop
+end

data/features/support/env.rb

@@ -0,0 +1,38 @@
+# Generated by cucumber-sinatra. (2011-05-20 13:59:19 +0100)
+
+ENV['RACK_ENV'] = 'test'
+
+require File.join(File.dirname(__FILE__), '..', '..', 'lib/noumenon.rb')
+
+require 'aruba/cucumber'
+require 'capybara/cucumber'
+require 'rspec'
+
+require 'fileutils'
+
+include Noumenon::Spec::ThemeHelpers
+
+Capybara.app = Noumenon.server
+
+World do
+  include RSpec::Expectations
+  include RSpec::Matchers
+
+  def content_path
+    File.expand_path('../tmp/content', __FILE__)
+  end
+
+  true
+end
+
+Before do
+  Noumenon.theme = create_theme(name: "Example Theme")
+  
+  FileUtils.mkdir_p content_path
+  Noumenon.content_repository = Noumenon::Repository::FileSystem.new(path: content_path)
+end
+
+After do
+  FileUtils.rm_r content_path
+  FileUtils.rm_r theme_path
+end

data/features/support/theme/theme.yml

@@ -0,0 +1,5 @@
+name: Cucumber Features Theme
+author: Jon Wood
+email: jon@blankpad.net
+copyright: 2011, Blank Pad Development
+license: MIT

data/features/theme_assets.feature

@@ -0,0 +1,22 @@
+Feature: Theme Assets
+  As a designer
+  I want to serve files from my theme
+  So that I can bundle any required images with it
+  In order to make using themes simpler
+
+  Scenario: The asset does not exist
+    Given the asset "foo.txt" does not exist within the theme
+    When I view "/themes/Example%20Theme/foo.txt"
+    Then the page should return a 404 error
+
+  Scenario: The asset does exist
+    Given the asset "foo.txt" exists within the theme with this content:
+      """
+      Hello, world!
+      """
+    When I view "/themes/Example%20Theme/foo.txt"
+    Then the page should load
+    And the page content should be:
+      """
+      Hello, world!
+      """

data/generators/repository/index.yml

@@ -0,0 +1,3 @@
+template: "default"
+title: "Welcome to Noumenon"
+body: "You've just created a Noumenon site, well done!"

data/generators/site/Gemfile

@@ -0,0 +1,3 @@
+source :rubygems
+
+gem "noumenon"

data/generators/site/config.ru

@@ -0,0 +1,7 @@
+require 'bundler/setup'
+require 'noumenon'
+
+Noumenon.theme = Noumenon::Theme.load("./theme")
+Noumenon.content_repository = Noumenon::Repository::FileSystem.new(path: "./content")
+
+run Noumenon.server

data/generators/theme/assets/style.css

@@ -0,0 +1 @@
+/* Your themes styles should go here. */