zen 0.2.8 → 0.3b

data/lib/zen/model/helper.rb

@@ -0,0 +1,65 @@
+module Zen
+  module Model
+    ##
+    # Zen::Model::Helper is a helper module that contains a few methods for
+    # Sequel models. Using this helper can be done by simply including it into
+    # your model:
+    #
+    #     class MyModel < Sequel::Model
+    #       include Zen::Model::Helper
+    #     end
+    #
+    # See the individual methods in this module for more information.
+    #
+    # @since  16-10-2011
+    #
+    module Helper
+      # Array containing the database adapters that don't support regular
+      # expressions.
+      NoRegexpSupport = [:sqlite]
+
+      ##
+      # Extends the including class with the methods in the {ClassMethods}
+      # module.
+      #
+      # @since  16-10-2011
+      #
+      def self.included(into)
+        into.extend(ClassMethods)
+      end
+
+      # The methods in this module will be added as class methods to the
+      # including class.
+      module ClassMethods
+        ##
+        # Given a column name and a value this method will determine whether a
+        # regular expression should be used or a simple LIKE statement. If the
+        # DBMS supports the use of regular expressions those will be used,
+        # otherwise a LIKE in the format of "%VALUE%" is used.
+        #
+        # The return value of this method is either a ``Hash`` containing the
+        # column and the regular expression or an instance of
+        # ``Sequel::SQL::BooleanExpression``.
+        #
+        # @example Using a DBMS that supports the use of a regex
+        #  search_column(:name, 'ruby \d+') # => {:name => /ruby \d+/i}
+        #
+        # @example Using a DBMS that does not support the use of a regex
+        #  search_column(:name, 'ruby \d+') # => #<Sequel::SQL::BooleanExpression ....>
+        #
+        # @since  16-10-2011
+        # @param  [Symbol] column The column to use in the statement.
+        # @param  [String] value The value for the statement.
+        # @return [Hash|Sequel::SQL::BooleanExpression]
+        #
+        def search_column(column, value)
+          if NoRegexpSupport.include?(Zen.database.adapter_scheme)
+            return column.like("%#{value}%")
+          else
+            return {column => /#{value}/i}
+          end
+        end
+      end # ClassMethods
+    end # Helper
+  end # Model
+end # Zen

data/lib/zen/model/init.rb

@@ -0,0 +1,62 @@
+Zen::Language.load('zen_models')
+
+Sequel::Model.plugin(:validation_helpers)
+Sequel::Model.plugin(:association_pks)
+
+Sequel.extension(:migration)
+Sequel.extension(:pagination)
+Sequel.extension(:inflector)
+
+Sequel::Plugins::ValidationHelpers::DEFAULT_OPTIONS.merge!(
+{
+  :exact_length => {
+    :message    => lambda { |length| lang('zen_models.exact_length') & length }
+  },
+
+  :format => {
+    :message => lang('zen_models.format')
+  },
+
+  :includes  => {
+    :message   => lambda { |arg| lang('zen_models.includes') % arg.inspect },
+    :allow_nil => false
+  },
+
+  :integer => {
+    :message   => lang('zen_models.integer'),
+    :allow_nil => true
+  },
+
+  :length_range => {
+    :message => lang('zen_models.length_range')
+  },
+
+  :max_length => {
+    :message   => lambda { |length| lang('zen_models.max_length') % length },
+    :allow_nil => true
+  },
+
+  :min_length => {
+    :message  => lambda { |length| lang('zen_models.min_length') % length }
+  },
+
+  :not_string => {
+    :message  => lang('zen_models.not_string')
+  },
+
+  :numeric   => {
+    :message => lang('zen_models.numeric')
+  },
+
+  :type      => {
+    :message => lambda { |type| lang('zen_models.type') % type }
+  },
+
+  :presence  => {
+    :message => lang('zen_models.presence')
+  },
+
+  :unique    => {
+    :message => lang('zen_models.unique')
+  }
+})

data/lib/zen/model/methods.rb

@@ -3,25 +3,24 @@ module Sequel
   #:nodoc:
   class Model
     ##
-    # Retrieves all primary values and an optional column and returns the 
-    # results as an array of hashes in which the keys of these hashes are the 
-    # IDs and the values the values of the specified column. This array can be 
+    # Retrieves all primary values and an optional column and returns the
+    # results as an array of hashes in which the keys of these hashes are the
+    # IDs and the values the values of the specified column. This array can be
     # used when creating <select> elements using the BlueForm helper.
     #
     # @example
     #  Sections::Model::Section.pk_hash(:name) # => {1 => 'Blog', 2 => 'General'}
     #
-    # @author Yorick Peterse
     # @param  [Symbol] column The name of the optional column to select.
     # @return [Hash]
     #
-    def self.pk_hash column
+    def self.pk_hash(column)
       hash = {}
-      
+
       self.select(:id, column.to_sym).each do |row|
         hash[row.id] = row.send(column)
       end
-      
+
       return hash
     end
   end # Model

data/lib/zen/package.rb

@@ -1,280 +1,391 @@
 require 'ramaze/gestalt'
-require __DIR__('error/package_error')
-require __DIR__('package/base')
+require __DIR__('package/menu')
 
-#:nodoc:
 module Zen
   ##
-  # Module used for registering extensions and themes, setting their details and
-  # the whole shebang. Packages follow the same directory structure as Rubygems
-  # and can actually be installed using either Rubygems or by storing them in a
-  # custom directory. As long as you require the correct file you're good to go.
+  # Zen::Package allows developers to register so called "packages". Packages
+  # are collections of controllers, models, views and pretty much anything else
+  # that goes in a typical Ramaze application. In fact, you can actually
+  # distribute entire Ramaze applications as a package (though it would most
+  # likely require some modifications).
   #
-  # Packages are added or "described" using a simple block and the add() method
-  # as following:
+  # A package is registered by calling ``Zen::Package.add`` and passing a block
+  # to it. This block will be yielded on a new instance of ``Zen::Package``:
+  #
+  #     Zen::Package.add do |p|
   #
-  #     Zen::Package.add do |ext|
-  #       # ....
   #     end
   #
-  # When using this block you're required to set the following attributes:
+  # When adding a package you must **always** set the following attributes:
   #
-  # * name: the name of the package in lowercased letters and/or numbers.
-  # * author: the name of the person who made the package.
-  # * about: a small description of the package.
-  # * url: the URL to the package's website.
-  # * directory: the root directory of the package, set this using __DIR__('path').
+  # * name: the name of the package, should be a symbol
+  # * title: the title of the package. This should be a language key such as
+  #   "users.titles.index" as this allows users to view the package name in
+  #   their chosen language.
+  # * author: the name of the package's author.
+  # * about: a description of the package, just like the title attribute this
+  #   should be a language key, "users.description" is an example of such a key.
+  # * root: the root directory of the package, this path should point to the
+  #   directory containing your ``helper/`` and ``language/`` directories as
+  #   well as any ``public/`` directories.
   #
-  # Optionally you can also specify the attribute "menu" (more on that later).
+  # Setting these (and other) attributes is very easy:
   #
-  # ## ACL
+  #     Zen::Package.add do |p|
+  #       p.name   = :some_package
+  #       p.title  = 'some_package.titles.index'
+  #       p.author = 'John Doe'
+  #       p.root   = __DIR__('some_package')
+  #     end
   #
-  # Packages allow developers to register controllers for the ACL system that
-  # ships with Zen. Doing this means a user can set controller specific rules
-  # in the backend without having to write any code. In order to register a set
-  # of controllers you'll need to set the "controllers" attribute in the package
-  # block to a hash. The keys of this hash should be a human readable name of
-  # the controller and the values the full namespace of the controller as either
-  # a string or a constants:
+  # Besides the required attributes listed above you can also set the following
+  # ones:
   #
-  #     Zen::Package.add do |pkg|
-  #       pkg.controllers = {
-  #         'Test Controller' => Test::Controller::TestController
-  #       }
-  #     end
+  # * url: a URL that points to the website of the package.
+  # * migrations: a directory containing all Sequel migrations.
   #
-  # ## Menu Items
+  # ## Package Structure
   #
-  # The package system easily allows modules to add navigation/sub-navigation 
-  # elements to the backend menu. Each extension can have an attribute named 
-  # "menu", this attribute is an array of hashes. Each hash must have the 
-  # following 2 keys (they're symbols):
+  # Packages should have the same structure as generic Rubygems. In it's most
+  # basic form this means you'll end up with a structure that looks like the
+  # following:
   #
-  # * title: the value used for both the title tag and the text of the anchor 
-  #   element
-  # * url: the URI the navigation item will point to. Leading slash isn't 
-  #   required
+  #     root/
+  #     |
+  #     |__ lib/
+  #        |__ package.rb
+  #        |__ package/
+  #           |__ controller/
+  #           |__ helper/
   #
-  # Optionally you can specify child elements using the "children" key. This key
-  # will again contain an array of hashes just like regular navigation elements.
-  # For example, one could do the following:
+  # There's no requirement for the location of your migrations but it's
+  # recommended to place it in the same directory as the ``lib/`` directory as
+  # this is the convention followed by Zen itself.
   #
-  #     ext.menu = [{:title => "Dashboard", :url => "admin/dashboard"}]
+  # The advantage of this structure is that when a package is shipped via
+  # Rubygems it can be loaded in exactly the same way as a normal gem. Say the
+  # "some_package" example described earlier would be distributed via Rubygems,
+  # all a developer would have to do to load the package is the following:
   #
-  # Adding a number of child elements isn't very difficult either:
+  #     require 'some_package'
   #
-  #     ext.menu = [{
-  #       :title    => "Dashboard", :url => "admin/dashboard",
-  #       :children => [{:title => "Child", :url => "admin/dashboard/child"}]
-  #     }]
+  # It's not recommended to place packages or gems in the ``Zen`` namespace
+  # unless they modify or add core features such as more validation methods for
+  # ``Zen::Validation``.
   #
-  # Once a certain number of navigation elements have been added you can 
-  # generate the HTML for a fully fledged navigation menu using the 
-  # build_menu() method. This method uses Gestalt to build the HTML and also 
-  # takes care of permissions for each user/module.
+  # ## Menu Management
   #
-  # ## Migrations
+  # Menus can be added by calling the method ``menu()`` on the object passed to
+  # the block. This method takes a URL, a title/label and a hash of options.
+  # Note that just like the ``name`` attribute the title/label should be a
+  # language key.
+  #
+  #     Zen::Package.add do |p|
+  #       p.menu('some_package.titles.index', '/admin/some-packages')
+  #     end
   #
-  # If your package uses it's own database tables it's best to use migrations as 
-  # these make it very easy to install/uninstall the extension. Migrations 
-  # should be put in the root directory of your extension. For example, if your 
-  # extension is in "foobar" the migrations should be located in 
-  # "foobar/migrations", the lib directory in "foobar/lib", etc.
+  # For more information see ``Zen::Package#menu()`` and ``Zen::Package::Menu``.
   #
-  # Migrations can be executed using the Thor task "package:migrate" or 
-  # "db:migrate", the latter will install all packages while the first one will 
-  # only install the specified packages. For more information on these tasks 
-  # execute the following command:
+  # ## Permissions
+  #
+  # When creating a package you can add a number of permissions. These
+  # permissions can be assigned to a user or user group in the admin interface.
+  # Permissions allow you to restrict access to certain actions to specific
+  # users/user groups. A permission can be added by calling ``permission()`` on
+  # the object passed to the block. Again the title of the permission should be
+  # a langauge key so it can be displayed in a custom language:
+  #
+  #     Zen::Package.add do |p|
+  #       p.permission(:show_some_package, 'packages.titles.index')
+  #     end
+  #
+  # For more information on how to specify permission requirements in your
+  # controllers see ``Ramaze::Helper::ACL``.
+  #
+  # ## Migrations
   #
-  #     $ rake -T
+  # Zen comes with two tasks that allow users and developers to update their
+  # database, ``rake db:migrate`` and ``rake package:migrate``. For these tasks
+  # to work there of course have to be migrations. When registering a package
+  # you can set the ``migrations`` attribute. This attribute should contain a
+  # path to a directory containing a group of timestamp based migrations such as
+  # "1316770622_hello_world.rb".
   #
-  # @author Yorick Peterse
   # @since  0.1
   #
-  module Package
-    ##
-    # Hash containing all the registered packages. The keys of this hash are the 
+  class Package
+    include Zen::Validation
+
+    # Hash containing all the registered packages. The keys of this hash are the
     # names of all packages and the values the instances of Zen::Package::Base.
-    #
-    # @author Yorick Peterse
-    # @since  0.2.5
-    #
-    Registered = {}
+    REGISTERED = {}
 
-    ##
-    # Array containing all controllers of all packages.
-    #
-    # @author Yorick Peterse
-    # @since  0.2.5
-    #
-    Controllers = []
+    # The name of the package.
+    attr_reader :name
 
-    ##
-    # Adds a new package along with all it's details such as the name, author, 
-    # version and so on. Extensions can be added using a simple block as 
-    # following:
-    #
-    #     Zen::Package.add do |ext|
-    #       ext.name   = "name"
-    #       ext.author = "Author"
-    #     end
-    #
-    # When adding a new extension the following setters are required:
-    #
-    # * name
-    # * author
-    # * version
-    # * about
-    # * url
-    # * directory
-    #
-    # You can also set "migration_dir" to a directory with all migrations. By 
-    # default Zen will assume that it's 2 levels above your root directory.
-    #
-    # @author Yorick Peterse
-    # @since  0.1
-    # @yield  [package] Object containing all setters and getters for each 
-    # package.
-    #
-    def self.add
-      package = Zen::Package::Base.new
+    # The author of the package.
+    attr_accessor :author
+
+    # The URL of the package.
+    attr_accessor :url
 
-      yield package
+    # The root directory of the package.
+    attr_reader :root
 
-      # Validate the package
-      package.validate
-      package.name = package.name.to_sym
+    # The directory to all migrations.
+    attr_accessor :migrations
 
-      # Update the root but prevent duplicates
-      if !Ramaze.options.roots.include?(package.directory)
-        Ramaze.options.roots.push(package.directory)
+    class << self
+      ##
+      # Adds a new package along with all it's details such as the name, author,
+      # version and so on. Extensions can be added using a simple block as
+      # following:
+      #
+      #     Zen::Package.add do |ext|
+      #       extrans.name   = "name"
+      #       ext.author = "Author"
+      #     end
+      #
+      # @since  0.1
+      #
+      def add
+        package = self.new
+
+        yield(package)
+        package.validate
+
+        REGISTERED[package.name] = package
       end
 
-      # Update the language directory
-      if !Zen::Language.options.paths.include?(package.directory)
-        Zen::Language.options.paths.push(package.directory)
+      ##
+      # Retrieves the package for the given name.
+      #
+      # @example
+      #  Zen::Package[:users]
+      #
+      # @since  0.1
+      #
+      def [](name)
+        name = name.to_sym
+
+        if REGISTERED.empty?
+          raise(PackageError, "No packages have been added yet.")
+        end
+
+        if !REGISTERED.key?(name)
+          raise(PackageError, "The package \"#{name}\" doesn't exist.")
+        end
+
+        return REGISTERED[name]
       end
 
-      package.controllers.each do |name, controller|
-        controller = controller.to_s
+      ##
+      # Builds the entire navigation menu for all packages.
+      #
+      # @example
+      #  Zen::Package.build_menu('left', [:edit_user, :show_user, :show_setting])
+      #
+      # @since  0.3
+      # @param  [String] html_class An HTML class to apply to the <ul> element.
+      # @param  [Array] permissions An array of permissions for the current
+      #  user.
+      # @return [String]
+      #
+      def build_menu(html_class = 'navigation', permissions = [])
+        g = Ramaze::Gestalt.new
+
+        g.ul(:class => html_class) do
+          # Sort the hash
+          keys = REGISTERED.keys.sort
 
-        if !Controllers.include?(controller)
-          Controllers.push(controller)
+          keys.each do |key|
+            unless REGISTERED[key].menu.nil?
+              g.out << REGISTERED[key].menu.html(permissions)
+            end
+          end
         end
+
+        return g.to_s
       end
+    end # class << self
 
-      Registered[package.name.to_sym] = package
+    ##
+    # Sets the name of the package. The name of a package should be a short and
+    # unique name. A human readable version can be set using title=().
+    #
+    # @since  0.3
+    # @param  [#to_sym] name The name of the package.
+    #
+    def name=(name)
+      @name = name.to_sym
     end
 
     ##
-    # Retrieves the package for the given name.
+    # Sets the title of the package.
     #
-    # @author Yorick Peterse
-    # @since  0.1
+    # @since  0.3
+    # @param  [String] title The title or language key of the package.
     #
-    def self.[](name)
-      name = name.to_sym
+    def title=(title)
+      @title = title
+    end
 
-      if Registered.empty?
-        raise(PackageError, "No packages have been added yet.")
+    ##
+    # Returns the title of the package. This method will try to translate it and
+    # fall back to the original value in case the language key doesn't exist.
+    #
+    # @since  0.3
+    # @return [String]
+    #
+    def title
+      begin
+        return lang(@title)
+      rescue
+        return @title
       end
+    end
 
-      if !Registered.key?(name)
-        raise(PackageError, "The package \"#{name}\" doesn't exist.")
+    ##
+    # Returns the title as either an ``<a>`` tag or plain text depending on
+    # whether or not the package has a URL set.
+    #
+    # @since  19-11-2011
+    # @return [String]
+    #
+    def formatted_title
+      if url
+        return '<a href="%s" title="%s">%s</a>' % [url, title, title]
+      else
+        return title
       end
+    end
 
-      return Registered[name]
+    ##
+    # Sets the description of the package.
+    #
+    # @since  0.3
+    # @param  [String] about The description of the package.
+    #
+    def about=(about)
+      @about = about
     end
 
     ##
-    # Builds a navigation menu for all installed extensions.
-    # Extensions can have an infinite amount of sub-navigation
-    # items. This method will generate an unordered list of items
-    # of which each list item can contain N sub items.
+    # Tries to translate the description and returns it.
     #
-    # @author Yorick Peterse
-    # @param  [String] html_class A string of CSS classes to apply to the main UL 
-    # element.
-    # @param  [Hash] permissions Hash containing the permissions as returned by
-    # Ramaze::Helper::ACL.extension_permissions
-    # @since  0.1
+    # @since  0.3
+    # @return [String]
     #
-    def self.build_menu(html_class = '', permissions = {})
-      @g           = Ramaze::Gestalt.new
-      @permissions = permissions
-      menu_items   = []
-
-      Registered.each do |name, pkg|
-        # Got a menu for us?
-        if !pkg.menu.nil?
-          pkg.menu.each do |m|
-            menu_items.push(m)
-          end
-        end
+    def about
+      begin
+        return lang(@about)
+      rescue
+        return @about
       end
+    end
+
+    ##
+    # Sets the root directory of the package.
+    #
+    # @since  0.3
+    # @param  [String] root The path to the root directory.
+    #
+    def root=(root)
+      @root    = root
+      lang_dir = File.join(@root, 'language')
 
-      # Sort the menu alphabetical
-      menu_items = menu_items.sort_by do |item|
-        item[:title]
+      if !Ramaze.options.roots.include?(@root)
+        Ramaze.options.roots << @root
       end
 
-      @g.ul :class => html_class do
-        if !menu_items.empty?
-          menu_items.each do |m|
-            self.nav_list(m)
-          end
-        end
+      if !Zen::Language.options.paths.include?(@root) \
+      and File.directory?(lang_dir)
+        Zen::Language.options.paths << lang_dir
       end
 
-      return @g.to_s
+      if !Ramaze::HelpersHelper.options.paths.push.include?(@root)
+        Ramaze::HelpersHelper.options.paths << @root
+      end
     end
 
-    private
-
     ##
-    # Method that's used to generate the list items for each
-    # navigation menu along with all sub elements.
+    # Sets all the navigation items for the package. Sub items can be specified
+    # by calling this method and passing a block to it.
     #
-    # @author Yorick Peterse
-    # @param  [Hash] menu Hash containing the navigation items (url, title, etc)
-    # @since  0.1
+    # @example
+    #  Zen::Package.add do |p|
+    #    p.menu('Hello,' ,'/admin/hello') do |sub|
+    #      sub.menu('Sub menu', '/admin/hello/sub')
+    #    end
+    #  end
     #
-    def self.nav_list(menu)
-      if menu[:url][0, 1] != '/'
-        menu[:url] = '/' + menu[:url]
+    # @since  0.3
+    # @see    Zen::Package::Menu#initialize()
+    # @return [Zen::Package::Menu] The current navigation menu if no new one is
+    #  specified.
+    #
+    def menu(title = nil, url = nil, options = {}, &block)
+      if title.nil? and url.nil? and !block_given?
+        return @menu
       end
 
-      # Get the controller for the current item
-      controller = Ramaze::AppMap.at('/').url_map.at(menu[:url]).to_s
+      @menu = Zen::Package::Menu.new(title, url, options, &block)
+    end
+
+    ##
+    # Adds a new permission along with it's title or language key.
+    #
+    # @example
+    #  Zen::Package.add do |p|
+    #    p.permission :show_user, 'users.titles.index'
+    #    p.permission :edit_user, 'users.titles.edit'
+    #  end
+    #
+    # @since  0.3
+    # @param  [#to_sym] permission The name of the permission.
+    # @param  [String] title The title or language key of the permission, shown
+    #  in the admin interface.
+    #
+    def permission(permission, title)
+      @permissions                  ||= {}
+      @permissions[permission.to_sym] = title
+    end
 
-      if @permissions[controller].nil?
-        read_access = false
-      else
-        read_access = @permissions[controller].include?(:read)
-      end
+    ##
+    # Returns the permissions for the current package. This method will
+    # automatically try to translate the titles using the current language.
+    #
+    # @since  0.3
+    # @return [Hash]
+    #
+    def permissions
+      perms = {}
 
-      # Ignore the menu item alltogether
-      if !read_access and !menu.key?(:children)
-        return
+      @permissions.each do |perm, title|
+        begin
+          perms[perm] = lang(title)
+        rescue
+          perms[perm] = title
+        end
       end
 
-      @g.li do
-        # Easy way of disabling an item and not fucking up the menu
-        if !read_access
-          menu[:url] = '#'
-        end
+      return perms
+    end
 
-        @g.a :href => menu[:url], :title => menu[:title] do
-          menu[:title]
-        end
+    ##
+    # Validates all the attributes.
+    #
+    # @since  0.2.5
+    #
+    def validate
+      validates_presence([:name, :title, :author, :about, :root])
 
-        if menu.key?(:children)
-          @g.ul do
-            menu[:children].each do |c|
-              self.nav_list(c)
-            end
-          end
-        end
+      validates_filepath(:root)
+      validates_filepath(:migrations) unless migrations.nil?
+
+      # Check if the package hasn't been registered yet
+      if Zen::Package::REGISTERED.key?(name.to_sym)
+        raise(Zen::ValidationError, "The package #{name} already exists.")
       end
     end
   end # Package