zen 0.1a → 0.2

data/README.md

@@ -0,0 +1,114 @@
+# README
+
+Zen is a modular CMS written on top of the awesome Ramaze framework.
+Zen was built out of the frustration with Expression Engine, a popular CMS built on top of
+the Codeigniter framework which in turn is written using PHP. While I really like Codeigniter,
+ExpressionEngine and EllisLab there were several problems that bothered me.
+So I set out to write a system that's loosely based on ExpressionEngine but fits my needs.
+Because of this certain features may seem similar to those provided by EE and while at
+certain points there are similarities there are also pretty big differences.
+
+## Requirements
+
+The following Gems are always required:
+
+* Ramaze
+* Sequel
+* Liquid
+* BCrypt
+* JSON
+* Ruby 1.9
+* Defensio
+* Thor
+* Sequel Sluggable
+
+These Gems are only required when developing/hacking Zen itself:
+
+* RDiscount
+* YARD
+* RSpec 2
+* Webrat
+
+## Installation
+
+Installing Zen using Rubygems is probably the easiest way:
+
+    $ gem install zen
+    $ zen app application_name
+
+If you like to hack with the core of Zen it's best to install it using Git:
+
+    $ git clone git://github.com/zen-cms/zen-core.git
+    $ cd zen-core
+    $ thor build:gem_clean
+
+## Database Support
+
+Technically Zen should run on any given DBMS that's supported by Sequel as Zen doesn't
+use any DBMS specific field types. However, there might be a chance that it won't work.
+If you happen to have any problems getting Zen running using your database of choice
+feel free to submit a ticket or post it on the mailing list.
+
+The Zen website itself is tested and served using MySQL, SQLite3 works just as fine and
+PostgreSQL will be tested in the near future.
+
+## Running Zen
+
+Zen can be run using any webserver as long as it supports Rack. Thin, Unicorn or Passenger,
+they should all work. The main website of Zen is served using Unicorn and Nginx, development
+is done using WEBRick and Unicorn.
+
+## Documentation
+
+The documentation (both the userguide and the API docs) can be found on the website,
+located [here][zen documentation].
+
+## Hacking/Contributing
+
+Zen follows a relatively strict set of guidelines when it comes to developing core features
+and making sure everything goes along smoothly. When working with Git a branch model based
+on [nvie's branch model][nvie branch model] is used. This means that the "master" branch
+is directly used for pushing Gems and thus should *always* contain stable code. Develop
+is used to contain less stable (but not unstable) commits that will be pushed into "master"
+from time to time. All other branches, e.g. "rspec2" will be used for individual features.
+
+Besides following this model developers are also expected to write tests using either
+RSpec or Webrat for their features. Webrat is used to test controllers and browser based
+tests while RSpec is used to test libraries, helpers, etc.
+
+If you have a cool idea, implemented it and think it's worth merging into Zen itself feel
+free to submit a pull request and I'll take a look at it.
+
+## Coding Standards
+
+* 2 spaces per indentation level for Ruby code.
+* 4 spaces per indentation level for Javascript, CSS and HTML.
+* Document your code, that includes CSS and Javascript files.
+* No tabs at all times
+* Markdown is used for all markup
+* Comments should be in English 
+* The maximum width of each line should be no more than 90 columns, this makes it easier
+to read code in terminals or when using split view modes.
+* Big changes should always be added to the file "CHANGELOG.md".
+
+## Community
+
+* [Website][zen website]
+* Mailing list
+
+Zen does not have it's own IRC channel at this time but you can usually find me in any
+of the following channels on Freenode (all are prefixed with a hash sign):
+
+* forrst-chat
+* ramaze
+* codeigniter
+* mootools
+
+## License
+
+Zen is licensed under the MIT license. For more information about this license open
+the file "license.txt".
+
+[zen website]: http://zen-cms.com/
+[zen documentation]: http://zen-cms.com/documentation/
+[nvie branch model]: http://nvie.com/posts/a-successful-git-branching-model/

data/ROADMAP.md

@@ -0,0 +1,31 @@
+# Roadmap
+
+Please note that the release dates in this roadmap may and most likely will change from
+time to time. List items that contain a "(!)" are considered to be important and should
+be solved/added before any of the other items. Items containing "(?)" are considered
+to be unverified/undecided and might not be added/completed at all.
+
+## Planned Releases
+
+### 0.3 - June 2011
+
+* Most parts of the core covered by specs. (!)
+* A working (although probably rough) plugin system to extend the inner parts of Zen. 
+An example of a plugin would be something that allows the use of Akismet for comments
+rather than Defensio.
+* Website completely up and running. (!)
+* Translation system for the Javascript used in the backend
+* Documentation/Userguide online
+
+### 0.2 - March 2011
+
+* General code improvements.
+* Navigation module for the frontend.
+* Improved Liquid tags.
+* A working datepicker
+* Refilling forms in case of errors (!)
+
+### 0.1a - February 2011
+
+The first public alpha released, mainly meant to give people and idea of what Zen is 
+all about.

data/Thorfile

@@ -0,0 +1,8 @@
+require File.expand_path('../lib/zen', __FILE__)
+require 'thor'
+
+task_dir = File.expand_path('../lib/zen/task', __FILE__)
+
+Dir.glob("#{task_dir}/*.rb").each do |f|
+  require(f)
+end

data/lib/zen.rb

@@ -11,21 +11,21 @@ module Zen
   require 'bcrypt'
   require 'liquid'
   require 'json'
-  require 'redcloth'
-  require 'rdiscount'
   require 'defensio'
+  require 'thor'
+  require 'sequel_sluggable'
+  require 'yaml'
   require __DIR__('zen/base/version')
   
   include Innate::Optioned
   
   # Update several paths so we can load helpers/layouts from the Zen gem
-  Innate::HelpersHelper.options.paths << __DIR__('zen')
-  Ramaze.options.roots << __DIR__('zen')
+  Innate::HelpersHelper.options.paths.push(__DIR__('zen'))
+  Ramaze.options.roots.push(__DIR__('zen'))
   
   options.dsl do
     # General configuration options
     o 'The character encoding to use when dealing with data',   :encoding,       'utf8'
-    o 'The system language',                                    :language,       'en'
     o 'The date format to use for log files and such.',         :date_format,    '%d-%m-%Y'
     o 'The base directory of Zen.',                             :root,           ''
   end
@@ -49,11 +49,11 @@ module Zen
   require __DIR__ 'zen/liquid/strip'
   
   class << self
-    attr_accessor :logger
+    attr_reader :languages
   end
   
   # Update the language paths
-  Zen::Language.language_paths << __DIR__('zen')
+  Zen::Language.options.paths.push(__DIR__('zen'))
   
   # Register our Liquid tags
   ::Liquid::Template.register_tag('strip'   , Liquid::Strip)
@@ -63,15 +63,18 @@ module Zen
   # Intitializes Zen by connecting the database and setting up various other things.
   #
   # @author Yorick Peterse
+  # @since  0.1
   #
   def self.init
     # Initialize the database
     Zen::Database.init
+    Zen::Language.load('zen_general')
     
     require __DIR__ 'zen/model/settings'
     require __DIR__ 'zen/model/methods'
     
-    # Initialize the logger
-    @logger = Zen::Logger.new("#{Zen.options.root}/logs/common")
+    @languages = {
+      'en' => lang('zen_general.special.language_hash.en')
+    }
   end
-end
+end

data/lib/zen/base/database.rb

@@ -1,39 +1,45 @@
+#:nodoc:
 module Zen
   ##
   # The database module is one of the most important classes in Zen (which is quite obvious).
-  # Without this module the application wouldn't exist. The database module is basically a small
-  # wrapper around the Sequel.connect method and allows developers to specify database
-  # settings for various environments (live, test, production, etc) using a simple block.
+  # Without this module the application wouldn't exist. The database module is 
+  # basically a small wrapper around the Sequel.connect method and allows developers 
+  # to specify database settings for various environments (live, test, production, etc) 
+  # using a simple block.
   #
-  # h2. Database Configuration
+  # ## Database Configuration
   #
   # Connecting to a database is fairly easy and only requires a single configuration file.
-  # In this file, called "database.rb" you'll define all your database environments (live, dev, test, etc).
+  # In this file, called "database.rb" you'll define all your database environments 
+  # (live, dev, test, etc).
   # 
-  # bc.. Zen::Database.mode :dev do |db|
-  #   db.adapter  = 'mysql'
-  #   db.host     = 'localhost'
+  #     Zen::Database.mode :dev do |db|
+  #       db.adapter  = 'mysql'
+  #       db.host     = 'localhost'
   #
-  #   db.username = 'root'
-  #   db.password = 'root'
-  #   db.database = 'database'
-  # end
+  #       db.username = 'root'
+  #       db.password = 'root'
+  #       db.database = 'database'
+  #     end
   #
-  # p. In this example we're connecting to "localhost" using the mysql adapter and selecting the database
-  # called "database". When placing multiple environments in the same file you don't have to worry about 
-  # them overriding eachother, Zen will only load the environment settings of the block that matches
+  # In this example we're connecting to "localhost" using the mysql adapter and 
+  # selecting the database called "database". When placing multiple environments in the 
+  # same file you don't have to worry about them overriding eachother, Zen will only 
+  # load the environment settings of the block that matches
   # the current environment set in Ramaze.options.mode.
   #
-  # h2. Database Interaction
+  # ## Database Interaction
   #
-  # Once your database configuration file has been loaded you can communicate with the database using 
-  # models. Each model should extend the base model provided by Sequel:
+  # Once your database configuration file has been loaded you can communicate with the 
+  # database using  models. Each model should extend the base model provided by Sequel:
   #
-  # bc. class Comment < Sequel::Model
-  # end
+  #     class Comment < Sequel::Model
+  #     
+  #     end
   #
-  # Models can be called like any other class and don't need to be initialized. For more information
-  # on how to use models using Sequel you should read Sequel's documentation: http://sequel.rubyforge.com/
+  # Models can be called like any other class and don't need to be initialized. For 
+  # more information on how to use models using Sequel you should read Sequel's 
+  # documentation: http://sequel.rubyforge.com/
   #
   # @author Yorick Peterse
   # @since  0.1
@@ -73,7 +79,7 @@ module Zen
         :database => self.options.database, 
         :username => self.options.username, 
         :password => self.options.password, 
-        :logger   => Zen::Logger.new("#{Zen.options.root}/logs/database"),
+        :logger   => Zen::Logger.new("#{Zen.options.root}/log/database"),
         :test     => true, 
         :encoding => Zen.options.encoding)
       
@@ -84,10 +90,10 @@ module Zen
     end
     
     ##
-    # Method that's used to provide the ability to use different database configurations for each
-    # mode. This method basically just sets the Zen.options.db parameters based on the provided variables
-    # in the block. If you don't want to use different database configurations you can just set the variables
-    # directly using Zen.options.db.
+    # Method that's used to provide the ability to use different database configurations 
+    # for each mode. This method basically just sets the Zen.options.db parameters based 
+    # on the provided variables in the block. If you don't want to use different database 
+    # configurations you can just set the variables directly using Zen.options.db.
     #
     # @author Yorick Peterse
     # @since  0.1
@@ -102,4 +108,4 @@ module Zen
       end
     end
   end
-end
+end

data/lib/zen/base/language.rb

@@ -1,132 +1,214 @@
-require 'ostruct'
-
+#:nodoc:
 module Zen
   ##
-  # The Language module enables developers to create multi-lingual applications/extensions using
-  # nothing more than Ruby. While Ramaze already ships with multi-language support it relies on YAML
-  # for it's language files. While YAML is nice for config/language files my aim is to keep everything in Ruby
-  # as much as possible. Another problem with the language class provided by Ramaze is that at the time of writing
-  # (October 2011) it was completely undocumented and didn't make much sense.
+  # The language module is used for writing and using text translations. Translations are
+  # stored in a simple YAML file inside a directory called "language" followed by a directory
+  # who's name matches the language code for which it's translations should be used.
+  # Say we wanted to translate "Login" and "Register" into different languages our YAML
+  # file would look like the following:
+  #
+  #     ---
+  #     login: "Login"
+  #     register: "Register"
+  #
+  # If we save this file under parent_directory/language/en/tutorial.yml we could then
+  # load that file as following:
+  #
+  #     Zen::Language.load('tutorial')
   #
-  # h2. Usage
+  # ## Loading Translations
   #
-  # Using the language system provided by Zen is fairly straight forward. Create a directory named "language"
-  # and create a sub directory for each language. For example, if you're adding an English language pack this directory would be named "en".
-  # Language files can be named whatever you like as long as they contain the following block:
+  # The load() method will look for a YAML file of which the name matches the given string
+  # and can be found in the directory for the current language. This means that if we were
+  # to switch our language without creating a translation file for that language we wouldn't
+  # be able to use it (makes sense right?).
   #
-  # bc. Zen::Language.translation 'translation_name' do |item|
-  #   # ...
-  # end
+  # Once your translation file is in place and it's loaded it can be used using the lang()
+  # method. Example:
   #
-  # Inside this block you'll define your language items. For example, if we want a localized username and password we could
-  # do something like the following:
+  #     lang('tutorial.login') # => "Login"
   #
-  # bc. Zen::Language.translation 'example' do |item|
-  #   item.username = 'Username'
-  #   item.passowrd = 'Password'
-  # end
+  # ## Directory Structure
   #
-  # This language file can then be loaded as following (assuming it's named "example.rb"):
-  # 
-  # bc. lang = Zen::Language.load 'example'
-  # # We can now access our translation items from the lang variable
-  # lang.username
-  # lang.password
+  # As mentioned earlier language files are saved in a certain directory. The structure
+  # of this directory looks like the following:
   #
-  # Zen will use the setting Zen.options.language to determine what language should be loaded.
+  #     parent directory
+  #       |
+  #       |__ language
+  #          |
+  #          |__ language key (e.g. "en")
+  #             |
+  #             |__ filename.yml
   #
-  # h2. Sub Items
+  # When loading a language file this module will loop through a certain number of paths.
+  # The array containing all base directories to loop through can be updated as following:
   #
-  # Since language files are nothing more than Ruby blocks you can do everything you normally can. This makes
-  # it extremely easy to retrieve dynamic data for your language files (a list of installed extensions for example).
-  # Sub items are generally specified as a hash:
+  #     Zen::Language.options.paths.push('/path/to/directory')
   #
-  # bc. item.sub_items = {:name => 'Name'}
+  # It's important that you _don't_ add a /language segment to the path, this will be done
+  # automatically.
   #
-  # Note that Zen won't convert the keys from format A to B, if you specify a symbol it will stay a symbol.
+  # ## Options
+  #
+  # * language: Small string that defines the current language (e.g. "en").
+  # * paths: Array of paths to look for a language file
   #
   # @author Yorick Peterse
-  # @since  0.1
+  # @since  0.2 
   #
   module Language
-    @language_keys  = {}
-    @language_paths = []
-    
+    include Ramaze::Optioned
+
+    options.dsl do
+      o 'Small string that defines the current language (e.g. "en").', :language, 'en'
+      o 'Array of paths to look for a language file'                 , :paths   , [] 
+    end
+
     class << self
-      attr_accessor :language_keys
-      attr_accessor :language_paths
+      attr_reader :translations
     end
     
     ##
-    # Tries to load the specified language file from each directory specified in Ramaze.options.roots.
-    # After a language file has been loaded the OpenStruct object will be stored in a hash and returned
-    # in case the same language file is loaded multiple times.
-    # 
+    # Tries to load a language file for the given name. If no language files were found
+    # based on the name and the current language an exception will be raised. 
+    #
     # @example
-    #  @user_lang = Zen::Language.load 'user'
-    #  @user_lang.username
+    #  Zen::Language.load('user')
     #
     # @author Yorick Peterse
-    # @param  [String] lang_name The name of the language file to load. This name should match both
-    # the filename and the name defined in Zen::Language.translation().
-    # @return [Object] An OpenStruct object containing all the language keys and their values.
+    # @since  0.1
+    # @param  [String] lang_name The name of the language file to load. 
     # 
-    def self.load lang_name
-      # Each language file is stored in the hash using a key with the following format:
-      # language-name_language-file
-      hash_key = Zen.options.language + '_' + lang_name
-      hash_key = hash_key.to_sym
+    def self.load(lang_name)
+      @translations ||= {}
+      @translations[self.options.language.to_s] ||= {}
 
-      # Let's see if the language file is already loaded
-      if @language_keys.key?(hash_key)
-        return @language_keys[hash_key]
+      if @translations[self.options.language.to_s][lang_name.to_s]
+        return
       end
-      
-      # Time to load the file
-      paths = @language_paths + Ramaze.options.roots
-      
-      paths.each do |dir|
-        lang_path = "#{dir}/language/#{Zen.options.language}/#{lang_name}.rb"
 
-        # Load the file if it exists
-        if File.exist?(lang_path)
-          require lang_path  
-          return @language_keys[hash_key]
-        end
+      self.options.paths.each do |path|
+        path += "/language/#{self.options.language}/#{lang_name}.yml"
+
+        # Load the file and save it
+        if File.exist?(path)
+          translation = YAML.load_file(path)
+
+          # Conver the hash to a dot based hash. This means that {:person => {:age => 18}}
+          # would result in {'person.age' => 18}.
+          translation = self.to_dotted_hash({lang_name.to_s => translation})
+          
+          @translations[self.options.language.to_s] ||= {}
+          @translations[self.options.language.to_s].merge!(translation)
+          
+          # Prevents the exception from being raised
+          return
+        end        
       end
-      
-      # No language file found
-      return false
+
+      raise "No language file could be found for \"#{lang_name}\""
     end
-    
+
     ##
-    # Given a block this method will store all the keys in the language_keys instance variable.
-    # Using Zen::Language.load these variables will be returned as an OpenStruct object.
+    # Method for retrieving the correct language item based on the given string.
+    # If you want to retrieve sub-items you can separate each level with a dot:
+    #
+    #     lang('tutorial.main.sub')
+    #
+    # This would require our YAML file to look something like the following:
+    #
+    #     ---
+    #     main:
+    #       sub: "Something!"
+    #
+    # It's important to remember that your key should always include the name of the
+    # language file since once a file is loaded it will be kept in memory to reduce
+    # disk usage.
     #
     # @example
-    #  Zen::Language.translation 'example' do |lang|
-    #    lang.username = 'Username'
-    #    lang.password = 'Password'
-    #  end
+    #  lang('username')
     #
     # @author Yorick Peterse
-    # @param  [Block] Block containing all the language items.
+    # @since  0.2
+    # @param  [String] key The language key to select.
+    # @return [Mixed]
     #
-    def self.translation lang_name, &block
-      # Each language file is stored in the hash using a key with the following format:
-      # language-name_language-file
-      hash_key = Zen.options.language + '_' + lang_name
-      hash_key = hash_key.to_sym
-      
-      # Does the language key already exist?
-      if @language_keys.key?(hash_key)
-        raise "There already is a language file named \"#{lang_name}\" for the language \"#{Zen.options.language}\"."
+    def lang(key)
+      lang          = ::Zen::Language.options.language.to_s
+      groups        = []
+      translations  = ::Zen::Language.translations
+
+      if !translations or !translations.key?(lang)
+        raise "No translation files have been added for the language code \"#{lang}\""
+      end
+
+      if translations[lang][key]
+        return translations[lang][key]
       end
       
-      # Process the language file
-      @language_keys[hash_key] = OpenStruct.new
-      
-      yield @language_keys[hash_key]
+      raise "The specified language item \"#{key}\" does not exist"
+    end
+
+    private
+
+    ##
+    # Method that takes a hash or an array and converts it to a dot-based hash. For example,
+    # the following hash:
+    #
+    #     {:name => 'Name', :location => {:street => 'Street', :address => 'Address'}}
+    #
+    # would result in the following:
+    #
+    #     {'name' => 'Name', 'location.street' => 'Street', 'location.address' => 'Address'}
+    #
+    # Using arrays would result in the following:
+    #
+    #     to_dotted_hash(["Hello", "World"]) # => {'1' => 'Hello', '2' => 'World'}
+    #
+    # While it looks a bit goofy this allows you to do the following:
+    #
+    #     lang('1') # => 'Hello'
+    #
+    # @example
+    #  self.to_dotted_hash({:name => "Yorick"}) # => {'name' => 'Yorick'}
+    #
+    # The code for this method was mostly taken from a comment on Stack Overflow.
+    # This comment can be found here: <http://bit.ly/dHTjVR>
+    #
+    # @author Yorick Peterse
+    # @since  0.2
+    # @param  [Hash/Array] source The hash or array to conver to a dot-based hash.
+    # @param  [Hash] target The hash to store the new key/values in.
+    # @param  [String] namespace The namespace for the key (e.g. "user.location").
+    # @return [Hash] The converted hash where the keys are dot-based strings instead of
+    # regular strings/symbols with sub hashes.
+    #
+    def self.to_dotted_hash(source, target = {}, namespace = nil)
+      if namespace and !namespace.nil?
+        prefix = "#{namespace}."
+      else
+        prefix = ""
+      end
+
+      case source
+      when Hash
+        source.each do |k, v|
+          self.to_dotted_hash(v, target, "#{prefix}#{k}")
+        end
+      when Array
+        source.each_with_index do |v, i|
+          self.to_dotted_hash(v, target, "#{prefix}#{i}") 
+        end
+      else
+        if !namespace.nil?
+          target[namespace] = source
+        else
+          target = source
+        end
+      end
+
+      return target
     end
   end
-end
+end