zen 0.2.3 → 0.2.4

data/lib/zen/task/theme.rb

@@ -0,0 +1,88 @@
+Sequel.extension(:migration)
+
+module Zen
+  module Task
+    ##
+    # The Theme task is used to install, delete and manage Zen themes.
+    #
+    # @author Yorick Peterse
+    # @since  0.2.4
+    #
+    class Theme < Thor
+      namespace :theme
+
+      desc('list', 'Lists all installed themes')
+
+      ##
+      # Lists all installed themes
+      #
+      # @author Yorick Peterse
+      # @since  0.2.4
+      #
+      def list
+        table = []
+        table.push(['Name', 'Author', 'Identifier', 'Templates'])
+        table.push(['------', '------', '------', '------'])
+
+        Zen::Theme.themes.each do |ident, theme|
+          table.push([theme.name, theme.author, theme.identifier, theme.template_dir])
+        end
+
+        print_table(table)
+      end 
+
+      desc('migrate', 'Migrates a theme to the given version')
+
+      method_option(:version   , :type => :numeric, :default => nil)
+      method_option(:identifier, :type => :string , :default => nil, :required => true)
+     
+      ##
+      # Migrates a theme to the given version.
+      #
+      # @author Yorick Peterse
+      # @since  0.2.4
+      #
+      def migrate
+        version = options[:version]
+        ident   = options[:identifier]
+        
+        if Zen::Theme.themes.nil? or Zen::Theme.themes.empty?
+          abort "No themes have been loaded. Be sure to add them to config/requires.rb."
+        end
+
+        if version.nil?
+          puts "No version specified with --version, choosing the most recent version..."
+        end
+
+        install_theme = Zen::Theme[ident]
+
+        if ident.nil? or ident.empty?
+          abort "You specified an invalid identifier."
+        end
+
+        # Get the directory from the migration_dir getter, generate it if it isn't there.
+        if install_theme.respond_to?(:migration_dir) and !install_theme.migration_dir.nil?
+          dir = install_theme.migration_dir
+        else
+          abort "The specified theme has no migrations directory"
+        end
+
+        table = install_theme.identifier.gsub('.', '_').to_sym
+         
+        puts "Migrating theme..."
+        if File.directory?(dir)
+          Zen::Database.handle.transaction do
+            Sequel::Migrator.run(Zen::Database.handle, dir, :table => table, :target => version)
+            
+            if version == 0
+              # Remove the migrations table
+              Zen::Database.handle.drop_table table
+            end
+          end
+        end
+      end
+
+    end
+  end
+end
+

data/lib/zen/theme.rb

@@ -0,0 +1,129 @@
+require __DIR__('error/theme_error')
+require 'pathname'
+
+#:nodoc:
+module Zen
+  ##
+  # Themes in many ways are similar to plugins and packages but with a few differences.
+  # Unlike packages themes aren't able to update the entire Ramaze root, this prevents
+  # them from loading controllers and other classes unless the developer updates these
+  # paths manually. However, themes can set the following paths:
+  #
+  # * template_dir: the directory where all Liquid templates are located, always required.
+  # * partial_dir: the directory where all Liquid partials are located.
+  # * public_dir: the public directory containing assets such as CSS and Javascript files.
+  # * migration_dir: themes can use migrations to automatically add the required fields to
+  # the database, this setting should point to the directory where all migrations are
+  # located.
+  #
+  # ## Adding Themes
+  #
+  # Just like plugins and packages a theme can be added by calling Zen::Theme#add and
+  # passing a block to it. Once a theme has been loaded it will *not* be used until the
+  # user sets it as the active theme in the settings module.
+  #
+  # Example:
+  #
+  #     Zen::Theme.add do |theme|
+  #       theme.author     = 'Yorick Peterse'
+  #       theme.name       = 'Default'
+  #       theme.identifier = 'com.yorickpeterse.theme.default'
+  #     end
+  #
+  # The "identifier" key is very important and just like packages and plugins it should
+  # always stay the same once it has been set.
+  #
+  # ## Identifiers
+  #
+  # Theme identifiers should be in the following format:
+  #
+  #     com.VENDOR.theme.NAME
+  #
+  # For example:
+  #
+  #     com.yorickpeterse.theme.fancy_blog
+  #
+  # @author Yorick Peterse
+  # @since  0.2.4
+  # @attr_reader [Array] themes Array of all installed themes.
+  #
+  module Theme
+    class << self
+      attr_reader :themes
+    end
+
+    ##
+    # Adds a new theme to Zen. Note that the theme won't be used unless it has been set
+    # as the active theme in the settings package.
+    #
+    # @author Yorick Peterse
+    # @since  0.2.4
+    # @yield  [theme] Struct object containing all getter/setters for each theme.
+    #
+    def self.add
+      @themes ||= {}
+
+      required = [:name, :author, :about, :identifier, :template_dir]
+      theme    = Zen::StrictStruct.new(
+        :name, :author, :about, :url, :identifier, :template_dir, :partial_dir,
+        :public_dir, :migration_dir
+      ).new
+
+      yield theme
+
+      # Check if all required items have been set
+      theme.validate(required) do |k|
+        raise(Zen::ThemeError, "The following theme key is missing: #{k}")
+      end
+
+      # Validate all paths set
+      [:template_dir, :partial_dir, :public_dir, :migration_dir].each do |k|
+        # Only validate the path if it has been set
+        if theme.respond_to?(k) and !theme.send(k).nil? and !theme.send(k).empty?
+          if !File.exist?(theme.send(k))
+            raise(Zen::ThemeError, "The path #{k} doesn't exist.")
+          end
+        end
+      end
+
+      # Do we have a public directory?
+      if theme.respond_to?(:public_dir) and !theme.public_dir.nil?
+        if !Ramaze.options.publics.include?(theme.public_dir)
+          # Generate a relative path from ROOT to the theme
+          to   = Pathname.new(theme.public_dir)
+          from = Pathname.new(Zen.options.root)
+          dir  = to.relative_path_from(from.realpath).to_s
+
+          Ramaze.options.publics.push(dir)
+        end
+      end
+
+      if !@themes[theme.identifier].nil?
+        raise(Zen::ThemeError, "The theme #{theme.name} already exists.")
+      end
+
+      @themes[theme.identifier] = theme
+    end
+
+    ##
+    # Retrieves a single theme for hte given identifier.
+    #
+    # @author Yorick Peterse
+    # @since  0.2.4
+    # @param  [String] ident The identifier of the theme.
+    # @return [Struct] Instance of the theme.
+    #
+    def self.[](ident)
+      if @themes.nil?
+        raise(Zen::ThemeError, "No themes have been added.")
+      end
+
+      if !@themes[ident]
+        raise(Zen::ThemeError, "The theme #{ident} doesn't exist.")
+      end
+
+      return @themes[ident]
+    end
+
+  end
+end

data/lib/zen/{base/version.rb → version.rb}

@@ -8,5 +8,5 @@ module Zen
   # @author Yorick Peterse
   # @since  0.1
   #
-  Version = '0.2.3'
+  Version = '0.2.4'
 end

data/proto/app/config/config.rb

@@ -1,17 +1,30 @@
+##
 # Specify the root directory. This is required since there are multiple directories
 # to load resources from. This directory will be used for the database logger, modes, etc.
+#
 Zen.options.root     = __DIR__('../')
 
-# General configuration options
+##
+# UTF-8 bitches.
+#
 Zen.options.encoding = 'utf8'
 
-# Localization settings
+##
+# Sets the language to use in the event of the database settings not being set correctly.
+#
 Zen.options.language = 'en'
 
+##
 # Set the application's mode. Available modes are "dev" and "live"
-Ramaze.options.mode = :dev
+#
+Ramaze.options.mode  = :dev
 
-# Configure sessions
-Ramaze.options.session.key   = 'zen.sid'
+##
+# The session identifier to use for cookies.
+#
+Ramaze.options.session.key = 'zen.sid'
 
-Ramaze::View.options.cache   = false
+##
+# View caching.
+#
+Ramaze::View.options.cache = false

data/proto/app/config/database.rb

@@ -1,18 +1,74 @@
-# Database configuration
+##
+# Database group to use for developing the website.
+#
+# The following options can be set:
+#
+# * adapter: the SQL adapter used by Sequel to connect to the database. Examples of these
+# are mysql2, postgres, sqlite, etc.
+# * host: the hostname of the database server.
+# * username: the name of the user used for connecting to the database
+# * password: the password of the user used for connecting to the database.
+# * database: the name of the database to use.
+#
+# IMPORTANT: it's recommended to create a database user for your Zen application and
+# prevent it from being able to access other databases. Zen is new and may allow hackers
+# to exploit the system. Using an isolated user would prevent hackers from destroying
+# all databases.
+#
 Zen::Database.mode :dev do |db|
+  ##
+  # Example: mysql2
+  #
   db.adapter  = ''
+
+  ##
+  # Example: localhost
+  #
   db.host     = ''
 
+  ##
+  # Example: zen-app
+  #
   db.username = ''
+  
+  ##
+  # Example: 23x190jj38123x
+  #
   db.password = ''
+
+  ##
+  # Example: blog
+  #
   db.database = ''
 end
 
+##
+# Database group to use for your production server.
+# This group accepts the same settings as the block above.
+#
 Zen::Database.mode :live do |db|
+  ##
+  # Example: mysql2
+  #
   db.adapter  = ''
+
+  ##
+  # Example: localhost
+  #
   db.host     = ''
 
+  ##
+  # Example: zen-app
+  #
   db.username = ''
+  
+  ##
+  # Example: 23x190jj38123x
+  #
   db.password = ''
+
+  ##
+  # Example: blog
+  #
   db.database = ''
-end
+end

data/proto/app/config/middlewares.rb

@@ -1,17 +1,82 @@
-# Put your custom development modes in here
+##
+# All Rack middlewares should go in a block like the one below. Different combinations
+# can be used for different versions by setting the first argument of the middleware!
+# method to a symbol containing the name of the environment (e.g. :live).
+#
+# For development purposes we'll be loading various middlewares to make it easier to
+# detect errors, reloading the code and so on.
+#
 Ramaze.middleware! :dev do |m|
+  ##
+  # Rack::Lint is used to validate all code according to the Rack specification.
+  # It's not recommended to use this middleware in a production environment as it will
+  # slow your application down a bit.
+  #
   m.use Rack::Lint
+
+  ##
+  # Rack::CommonLogger is used to log requests in an Apache like format. Zen ships with
+  # a small extension of Ramaze::Log::RotatingInformer that automatically creates the
+  # required directories for each mode and group (database, server, etc) but any Rack
+  # compatible logger will do.
+  #
   m.use Rack::CommonLogger, Zen::Logger.new("#{Zen.options.root}/log/server")
+
+  ##
+  # Shows an error page whenever an exception was raised. It's not recommended to use
+  # this middleware on a production server as it may reveal sensitive details to the
+  # visitor.
+  #
   m.use Rack::ShowExceptions
+
+  ##
+  # Pretty much the same as Rack::ShowExceptions.
+  #
   m.use Rack::ShowStatus
-  m.use Rack::RouteExceptions
-  m.use Rack::ConditionalGet
-  m.use Rack::ETag, 'public'
+  
+  ##
+  # Routes exceptions to different actions, can be useful for catching 404's and such.
+  #
+  # m.use Rack::RouteExceptions
+  
+  ##
+  # Middleware that enables conditional GET using If-None-Match and If-Modified-Since.
+  # Currently Zen doesn't respond to conditional GET requests so it's fairly useless
+  # out of the box, it can be useful for custom extensions and such.
+  #
+  # m.use Rack::ConditionalGet
+  
+  ##
+  # Automatically sets the ETag header on all string bodies. Etags can be useful for
+  # checking if a certain page has been modified or not.
+  #
+  # IMPORTANT: Prior to Rack 1.2.2 Rack::ETag required the second argument of use() to
+  # be set to 'public'. Newer versions no longer require this.
+  #
+  m.use Rack::ETag
+  
+  ##
+  # Allows HEAD requests. HEAD requests are identical to GET requests but shouldn't
+  # return the body.
+  #
   m.use Rack::Head
+  
+  ##
+  # Automatically reloads your application whenever it detects changes. Note that this
+  # middleware isn't always as accurate so there may be times when you have to manually
+  # restart your server.
+  #
   m.use Ramaze::Reloader
+  
+  ##
+  # Runs Ramaze based on all mappings and such.
+  #
   m.run Ramaze::AppMap
 end
 
+##
+# Middlewares to use for a production environment.
+#
 Ramaze.middleware! :live do |m|
   m.use Rack::CommonLogger, Zen::Logger.new("#{Zen.options.root}/log/server")
   m.use Rack::RouteExceptions

data/proto/app/config/requires.rb

@@ -1,3 +1,10 @@
-
-# Load all core extensions that ship with Zen
+##
+# Load all core extensions that ship with Zen. 
+#
 require 'zen/package/all'
+
+##
+# All custom gems can go in here.
+#
+# require 'rdiscount'
+# require 'foobar'

data/proto/package/lib/package.rb

@@ -1,8 +1,4 @@
-
 Zen::Package.add do |p|
-  # The type of extension. Can either be "theme" or "extension".
-  p.type        = ''
-
   # The name of the package
   p.name        = '' 
 
@@ -12,26 +8,20 @@ Zen::Package.add do |p|
   # A URL to a page about the package
   p.url         = ''
 
-  # The version number of the package
-  p.version     = '1.0'
-
   # Describe what your theme or extension does.
   p.about       = ''
 
   ## 
   # An identifier is a unique string for your package in the following format: 
   # 
-  # * com.AUTHOR.NAME for extensions
-  # * com.AUTHOR.themes.NAME for themes
-  #
-  # An example of this would be "com.zen.sections" or "com.zen.themes.zen_website".
+  #     com.VENDOR.NAME
   #
-  p.identifier  = 'com.author.module'
+  p.identifier  = 'com.vendor.module'
 
   ##
   # Path to the directory containing the controllers, models, etc.
   #
-  p.directory   = __DIR__('modules')
+  p.directory   = __DIR__('package')
   
   # Note that themes can not have menu items (they'll be ignored).
   p.menu = [{