zen 0.2.8 → 0.3b

data/lib/zen/package/settings/lib/settings/controller/settings.rb

@@ -1,76 +1,102 @@
-#:nodoc:
+##
+# Package for managing and registering settings.
+#
+# ## Controllers
+#
+# * {Settings::Controller::Settings}
+#
+# ## Models
+#
+# * {Settings::Model::Setting}
+#
+# ## Generic Modules & Classes
+#
+# * {Settings::Setting}
+# * {Settings::SettingsGroup}
+# * {Settings::SingletonMethods}
+#
 module Settings
   #:nodoc:
   module Controller
     ##
-    # Controller for managing settings. Each setting is saved as a separate
-    # row in the database, making management and retrieving them easier.
+    # Controller for managing settings. Settings are used to store the name of
+    # the website, what anti-spam system to use and so on. These settings can be
+    # managed via the admin interface rather than having to edit configuration
+    # files. Settings can be managed by going to ``/admin/settings``. This page
+    # shows an overview of all the available settings organized in a number of
+    # groups where each group is placed under it's own tab. An example of this
+    # overview can be seen in the image below.
+    #
+    # ![General](../../_static/settings/overview_general.png)
+    # ![Security](../../_static/settings/overview_security.png)
+    # ![User Settings](../../_static/settings/overview_user.png)
+    #
+    # Out of the box Zen ships with the following settings:
+    #
+    # * **Website name**: the name of the website.
+    # * **Website description**: a short description of the website.
+    # * **Language**: the default language to use for the admin interface.
+    # * **Frontend Language**: the default language to use for the frontend of
+    #   your website.
+    # * **Theme**: the theme to use for the frontend.
+    # * **Date format**: the default date format to use in the backend.
+    # * **Enable anti-spam**: whether or not comments should be verified to see
+    #   if they're spam or ham.
+    # * **Anti-spam system**: the anti-spam system to use. Zen by default only
+    #   comes with Defensio support.
+    # * **Defensio key**: the API key for the Defensio anti-spam system.
+    # * **Allow Registration**: defines whether or not visitors are allowed to
+    #   register a user account.
+    #
+    # ## Used Permissions
+    #
+    # This controller uses the following permissions:
+    #
+    # * show_setting
+    # * edit_setting
+    #
+    # ## Events
+    #
+    # Unlike other controllers events in this controller do not receive an
+    # instance of a model. Instead they'll receive an instance of
+    # {Settings::Plugin::SettingBase}. In order to update the value of a setting
+    # you'll simply call ``#value=()`` and specify a new value.
+    #
+    # @example Trimming the value of a setting
+    #  Zen::Event(:after_edit_setting) do |setting|
+    #    if setting.name == 'website_name'
+    #      setting.value = setting.value.strip
+    #    end
+    #  end
     #
-    # @author Yorick Peterse
     # @since  0.1
+    # @map    /admin/settings
+    # @event  after_edit_setting
     #
     class Settings < Zen::Controller::AdminController
-      include ::Settings::Model
-
-      map '/admin/settings'
+      map   '/admin/settings'
+      title 'settings.titles.%s'
 
-      # Load all required Javascript files
-      javascript ['zen/lib/tabs']
-
-      before_all do
-        csrf_protection(:save, :delete) do
-          respond(lang('zen_general.errors.csrf'), 403)
-        end
-      end
-
-      ##
-      # Load our language packs, set the form URLs and define our page title.
-      #
-      # This method loads the following language files:
-      #
-      # * settings
-      #
-      # @author Yorick Peterse
-      # @since  0.1
-      #
-      def initialize
-        super
-
-        @form_save_url = Settings.r(:save)
-
-        # Set the page title
-        if !action.method.nil?
-          method      = action.method.to_sym
-          @page_title = lang("settings.titles.#{method}") rescue nil
-        end
-      end
+      csrf_protection  :save
+      load_asset_group :tabs
 
       ##
       # Show all settings and allow the user to change them.
-      # The values of each setting item are stored in the database,
-      # the descriptions, names and possible values are stored in
-      # the language packs that come with this module.
-      #
-      # This method requires the following permissions:
       #
-      # * read
-      # * update
-      #
-      # @author Yorick Peterse
-      # @since  0.1
+      # @since      0.1
+      # @permission show_setting
       #
       def index
-        require_permissions(:read, :update)
+        authorize_user!(:show_setting)
 
         set_breadcrumbs(lang('settings.titles.index'))
 
         @settings_ordered = {}
-        @groups           = ::Settings::Plugin::Settings::Registered[:groups]
+        @groups           = ::Settings::SettingsGroup::REGISTERED
 
         # Organize the settings so that each item is a child
         # item of it's group.
-        ::Settings::Plugin::Settings::Registered[:settings].each \
-        do |name, setting|
+        ::Settings::Setting::REGISTERED.each do |name, setting|
           if !@settings_ordered.key?(setting.group)
             @settings_ordered[setting.group] = []
           end
@@ -80,42 +106,41 @@ module Settings
       end
 
       ##
-      # Saves the values of each setting. Since each setting
-      # is a new row we'll have to loop through them and execute quite
-      # a few queries.
-      #
-      # This method requires the following permissions:
+      # Updates all the settings in both the database and the cache
+      # (Ramaze::Cache.settings).
       #
-      # * update
-      #
-      # @author Yorick Peterse
-      # @since  0.1
+      # @since      0.1
+      # @permission edit_setting
+      # @event      after_edit_setting
       #
       def save
-        require_permissions(:update)
+        authorize_user!(:edit_setting)
 
-        post = request.params.dup
+        post = request.params
         post.delete('csrf_token')
         post.delete('id')
 
-        flash_success = lang('settings.success.save')
-        flash_error   = lang('settings.errors.save')
-        success       = true
+        success = lang('settings.success.save')
+        error   = lang('settings.errors.save')
 
         # Update all settings
         post.each do |key, value|
+          setting = get_setting(key)
+
           begin
-            plugin(:settings, :get, key).value = value
+            setting.value = value
           rescue => e
             Ramaze::Log.error(e.inspect)
-            message(:error, flash_error)
+            message(:error, error)
 
             flash[:form_errors] = setting.errors
-            success             = false
+            redirect_referrer
           end
+
+          Zen::Event.call(:after_edit_setting, setting)
         end
 
-        message(:success, flash_success) if success === true
+        message(:success, success)
         redirect_referrer
       end
     end # Settings

data/lib/zen/package/settings/lib/settings/language/en/settings.rb

@@ -0,0 +1,41 @@
+# encoding: utf-8
+
+Zen::Language::Translation.add do |trans|
+  trans.language = 'en'
+  trans.name     = 'settings'
+
+  trans.translate do |t|
+    t['titles.index'] = 'Settings'
+
+    t['labels.website_name']           = 'Website name'
+    t['labels.website_description']    = 'Website description'
+    t['labels.language']               = 'Language'
+    t['labels.frontend_language']      = 'Frontend language'
+    t['labels.theme']                  = 'Theme'
+    t['labels.enable_antispam']        = 'Enable anti-spam'
+    t['labels.date_format']            = 'Date format'
+
+    t['descriptions.website_name']        = 'The name of the website.'
+    t['descriptions.website_description'] = 'The description of the website.'
+    t['descriptions.language']            = 'The language to use for the system.'
+    t['descriptions.theme']               = 'The frontend theme to use.'
+    t['descriptions.enable_antispam'] = 'Whether or not anti-spam protection ' \
+      'should be used for comments'
+    t['descriptions.frontend_language'] = 'The language to use for the ' \
+      'frontend of the website.'
+    t['descriptions.date_format'] = 'A custom format used for all the dates ' \
+      'displayed in the backend.'
+
+    t['tabs.general']  = 'General'
+    t['tabs.security'] = 'Security'
+
+    t['buttons.save'] = 'Save'
+
+    t['success.save'] = 'The settings have been saved.'
+    t['errors.save']  = 'The settings could not be saved.'
+    t['description']  = 'Package for managing settings.'
+
+    t['permissions.show'] = 'Show setting'
+    t['permissions.edit'] = 'Edit setting'
+  end
+end

data/lib/zen/package/settings/lib/settings/language/nl/settings.rb

@@ -0,0 +1,41 @@
+# encoding: utf-8
+
+Zen::Language::Translation.add do |trans|
+  trans.language = 'nl'
+  trans.name     = 'settings'
+
+  trans.translate do |t|
+    t['titles.index'] = 'Instellingen'
+
+    t['labels.website_name']           = 'Website naam'
+    t['labels.website_description']    = 'Website beschrijving'
+    t['labels.language']               = 'Taal'
+    t['labels.frontend_langauge']      = 'Taal voor bezoekers'
+    t['labels.theme']                  = 'Thema'
+    t['labels.enable_antispam']        = 'Anti-spam inschakelen'
+    t['labels.date_format']            = 'Datum formaat'
+
+    t['descriptions.website_name']        = 'De naam van de website.'
+    t['descriptions.website_description'] = 'De beschrijving van de website.'
+    t['descriptions.language']            = 'De taal die gebruikt moet worden '\
+      'voor het admin gedeelte.'
+    t['descriptions.theme']           = 'Het thema dat bezoekers zullen zien.'
+    t['descriptions.enable_antispam'] = 'Waarde die aangeeft of het anti-spam ' \
+      'systeem moet worden gebruikt voor reacties.'
+    t['descriptions.frontend_language'] = 'De taal die gebruikt moet worden '\
+      'voor bezoekers.'
+    t['descriptions.date_format'] = 'Het formaat van de datum voor het '\
+      'admin gedeelte.'
+
+    t['tabs.general']  = 'Algemeen'
+    t['tabs.security'] = 'Beveiliging'
+
+    t['buttons.save'] = 'Opslaan'
+    t['success.save'] = 'De instellingen zijn opgeslagen.'
+    t['errors.save']  = 'De instellingen konden niet worden opgeslagen.'
+    t['description']  = 'Pakket voor het beheren van instellingen.'
+
+    t['permissions.show'] = 'Instelling weergeven'
+    t['permissions.edit'] = 'Instelling aanpassen'
+  end
+end

data/lib/zen/package/settings/lib/settings/model/setting.rb

@@ -1,11 +1,9 @@
-#:nodoc:
 module Settings
   #:nodoc:
   module Model
     ##
     # Model that represents a single setting.
     #
-    # @author Yorick Peterse
     # @since  0.1
     #
     class Setting < Sequel::Model

data/lib/zen/package/settings/lib/settings/setting.rb

@@ -0,0 +1,379 @@
+module Settings
+  ##
+  # {Settings::Setting} is a class that can be used to register and migrate
+  # settings without having to manually insert the data. It provides an API
+  # similar to registering packages or themes and takes care of synchronizing
+  # data between the database and the cache.
+  #
+  # ## Adding Settings
+  #
+  # In order to add a setting you'll first need to ensure there's at least a
+  # single setting group available. These groups don't add any extra features
+  # or whatsoever but are used to display settings in different tabs in the
+  # backend interface. In order to register a new group you'd write the
+  # following code:
+  #
+  #     Settings::SettingsGroup.add do |group|
+  #       group.title = 'My Group'
+  #       group.name  = :my_group
+  #     end
+  #
+  # When registering a group you only need to specify a title and a name. The
+  # name is used to associate a setting with it's group and thus should always
+  # be unique. The title is displayed in the tab for the specific settings
+  # group.
+  #
+  # Once a setting group has been added we can add a setting as following:
+  #
+  #     Settings::Setting.add do |setting|
+  #       setting.title       = 'My Setting'
+  #       setting.description = 'This is my setting!'
+  #       setting.name        = :my_setting
+  #       setting.group       = :my_group
+  #       setting.type        = 'select'
+  #       setting.values      = ['yorick', 'zen']
+  #       setting.default     = 'yorick'
+  #     end
+  #
+  # Note that the values array (or hash) is used to determine the possible
+  # values for a field. These values will only be used for elements that only
+  # allow a user to choose a single value (e.g. a checkbox). For the type
+  # getter/setter you can use any of the following values:
+  #
+  # * textbox
+  # * textarea
+  # * radio
+  # * checkbox
+  # * date
+  # * select
+  # * select_multiple
+  #
+  # ## Migrating Settings
+  #
+  # Once a setting has been added you still have to migrate it. Zen takes care
+  # of this so usually you don't need to manually migrate your settings. If
+  # you do want to migrate them however you can simple execute the following
+  # code:
+  #
+  #     Settings::Setting.migrate
+  #
+  # ## Removing Settings
+  #
+  # If you ever need to remove a setting both from the database and the system
+  # you can do so as following:
+  #
+  #     Settings::Setting.remove([:name, :name1])
+  #
+  # You don't have to specify an array of names, you can also specify the name
+  # of a single setting to delete.
+  #
+  # @since  0.2.5
+  #
+  class Setting
+    include ::Zen::Validation
+
+    # Array containing all possible setting types.
+    Types = [
+      'textbox',
+      'textarea',
+      'radio',
+      'checkbox',
+      'date',
+      'select',
+      'select_multiple'
+    ]
+
+    # Hash containing all registered settings.
+    REGISTERED = {}
+
+    # The name of the setting
+    attr_reader :name
+
+    # The title of the setting, displayed in the GUI
+    attr_writer :title
+
+    # A small description about the setting
+    attr_writer :description
+
+    # The name of the settings group this setting belongs to
+    attr_reader :group
+
+    # The type of setting (e.g. textbox)
+    attr_accessor :type
+
+    # The possible values for the setting
+    attr_writer :values
+
+    # The default value of the setting
+    attr_accessor :default
+
+    class << self
+      ##
+      # Registers a new setting using the specified block.
+      #
+      # @example
+      #  Settings::Setting.add do |setting|
+      #    setting.name    = 'example'
+      #    setting.title   = 'Example setting'
+      #    setting.group   = 'example'
+      #    setting.type    = 'select'
+      #    setting.values  = ['yorick', 'chuck']
+      #  end
+      #
+      # @since  0.2.5
+      #
+      def add
+        setting = self.new
+
+        yield setting
+
+        setting.validate
+
+        REGISTERED[setting.name] = setting
+      end
+
+      ##
+      # Inserts all settings into the database. This method will ignore the
+      # settings that have already been inserted into the database.
+      #
+      # @since  0.2.5
+      #
+      def migrate
+        settings = ::Settings::Model::Setting.all.map { |s| s.name }
+
+        REGISTERED.each do |name, setting|
+          name = name.to_s
+
+          if !settings.include?(name)
+            Zen.database[:settings].insert(:name => name)
+          end
+        end
+      end
+
+      ##
+      # Removes the settings who's names match those specified in the array. The
+      # values of these settings will also be removed from the database.
+      #
+      # @since  0.2.5
+      # @param  [Array] namese An array with setting names to remove.
+      #
+      def remove(names)
+        if names.class != Array
+          names = [names]
+        end
+
+        names.each_with_index do |v, k|
+          names[k] = v.to_s
+          REGISTERED.delete(v.to_sym)
+        end
+
+        ::Settings::Model::Setting.filter(:name => names).destroy
+      end
+    end # class << self
+
+    ##
+    # Validates all attributes of this class.
+    #
+    # @since  0.2.5
+    #
+    def validate
+      validates_presence([:name, :title, :group, :type])
+
+      # Validate the setting type
+      if !Types.include?(type)
+        raise(::Zen::ValidationError, "The setting type \"#{type}\" is invalid.")
+      end
+
+      # Check if the setting hasn't been registered yet
+      if REGISTERED.key?(name)
+        raise(
+          ::Zen::ValidationError,
+          "The setting #{name} has already been registered"
+        )
+      end
+
+      # Validate the group
+      if !Settings::SettingsGroup::REGISTERED.key?(group)
+        raise(
+          ::Zen::ValidationError,
+          "The settings group \"#{group}\" doesn't exist."
+        )
+      end
+    end
+
+    ##
+    # Sets the name of the setting and converts it to a symbol.
+    #
+    # @since  0.3
+    # @param  [#to_sym] name The name of the setting.
+    #
+    def name=(name)
+      @name = name.to_sym
+    end
+
+    ##
+    # Sets the name of the group this setting belongs to.
+    #
+    # @since  0.3
+    # @param  [#to_sym] group The name of the settings group.
+    #
+    def group=(group)
+      @group = group.to_sym
+    end
+
+    ##
+    # Returns the title of the setting and tries to translate it.
+    #
+    # @since  0.3
+    # @return [String]
+    #
+    def title
+      begin
+        return lang(@title)
+      rescue
+        return @title
+      end
+    end
+
+    ##
+    # Returns the description of the setting and translates it.
+    #
+    # @since  13-11-2011
+    # @return [String]
+    #
+    def description
+      begin
+        return lang(@description)
+      rescue
+        return @description
+      end
+    end
+
+    ##
+    # Updates the value of a setting both in the cache and the SQL database.
+    #
+    # @since  0.2.6.1
+    # @param  [String] value The value to set the setting to.
+    #
+    def value=(value)
+      value = serialize(value)
+
+      # First we'll update the SQL database
+      ::Settings::Model::Setting[:name => name.to_s].update(:value => value)
+
+      # Sync the cache
+      ::Ramaze::Cache.settings.store(name, value)
+    end
+
+    ##
+    # Retrieves the setting. If it exists in the cache the cache's value is
+    # used, otherwise it will be retrieved from the SQL database and cached.
+    #
+    # @since  0.2.6.1
+    #
+    def value
+      val = ::Ramaze::Cache.settings.fetch(name)
+
+      # Get the setting from the database
+      if val.nil?
+        setting = ::Settings::Model::Setting[:name => name.to_s]
+
+        # If the value is also nil we'll use the default value
+        if setting.value.nil? or setting.value.empty?
+          val = default
+        else
+          val = setting.value
+        end
+
+        ::Ramaze::Cache.settings.store(name, val)
+      end
+
+      return unserialize(val)
+    end
+
+    ##
+    # Retrieves the possible values for the setting. If the value is a Proc or
+    # Lambda (or anything else that responds to call()) it will be called and
+    # it's return value is used.
+    #
+    # @since  0.2.8
+    # @return [Mixed]
+    #
+    def values
+      if @values.respond_to?(:call)
+        return @values.call
+      else
+        return @values
+      end
+    end
+
+    ##
+    # Returns the parameters for the BlueForm helper.
+    #
+    # @since  0.3
+    # @return [Array]
+    #
+    def form_parameters
+      return BlueFormParameters.send(type, self)
+    end
+
+    ##
+    # Small helper method that makes it a bit easier to check if a certain
+    # setting is set to true or false. Because settings are stored as strings
+    # with values of "1" or "0" you'd normally have to do the following:
+    #
+    #     get_setting(:allow_registration).value == '1'
+    #
+    # This method allows you to do the following instead:
+    #
+    #     get_setting(:allow_registration).true?
+    #
+    # @since  12-11-2011
+    # @return [TrueClass|FalseClass]
+    #
+    def true?
+      val = value
+
+      return val.is_a?(String) && val == '1'
+    end
+
+    private
+
+    ##
+    # Serializes a value using Marshal and packs it so that it can be stored in
+    # the database.
+    #
+    # @since  13-11-2011
+    # @param  [Mixed] value The value to serialize.
+    # @return [String]
+    #
+    def serialize(value)
+      return [Marshal.dump(value)].pack('m')
+    end
+
+    ##
+    # Unserializes a value that was serialized using
+    # {Settings::Setting#serialize}.
+    #
+    # @since  13-11-2011
+    # @param  [String] value The value to unserialize.
+    # @return [Mixed]
+    #
+    def unserialize(value)
+      begin
+        return Marshal.load(value.unpack('m')[0])
+      rescue
+        begin
+          return Marshal.load(value)
+        rescue
+          Ramaze::Log.info(
+            'Failed to unpack the setting using Marshal, using the ' \
+              'raw value instead'
+          )
+
+          return value
+        end
+      end
+    end
+  end # Setting
+end # Settings