zen 0.2.8 → 0.3b

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

@@ -1,113 +1,168 @@
-#:nodoc:
+##
+# Package for managing users, user groups and the permissions of users and user
+# groups.
+#
+# ## Controllers
+#
+# * {Users::Controller::Users}
+# * {Users::Controller::UserGroups}
+#
+# ## Helpers
+#
+# * {Ramaze::Helper::Users}
+# * {Ramaze::Helper::ACL}
+#
+# ## Models
+#
+# * {Users::Model::User}
+# * {Users::Model::UserGroup}
+# * {Users::Model::Permission}
+#
 module Users
   #:nodoc:
   module Controller
     ##
-    # Controller for managing users. Users in this case are people that have
-    # access to the backend. However, users might be able to access the backend
-    # but that doesn't mean they can actuall use it. The permission system will
-    # block anybody that don't have the correct permissions for each module. In
-    # case of a module like a forum it's probably better to add some additional
-    # checks to ensure people can't mess around with your system.
+    # Zen makes it easy for users to manage their own account as well as other
+    # users depending on their permissions. In Zen there's no special type of
+    # user such as an administrator or a contributor, instead users have access
+    # to various parts of your websites based on their permissions and the
+    # groups they have been assigned to (see {Users::Controller::UserGroups
+    # Managing User Groups} for more information).
+    #
+    # Users can be managed in the admin interface by going to ``/admin/users``.
+    # Just like other parts of the application you may not be able to manage
+    # users (or only partially) depending on your permissions.
+    #
+    # When navigating to the user overview (assuming you have the correct
+    # permissions) you should see a page that looks like the one shown in the
+    # image below.
+    #
+    # ![Users](../../_static/users/overview.png)
+    #
+    # This overview allows you to edit users (by clicking on their Email
+    # addresses), create new ones or delete existing users. When editing or
+    # creating a user you'll be presented a form as shown in the images below.
+    #
+    # ![Edit User](../../_static/users/edit_user.png)
+    # ![Edit Permissions](../../_static/users/edit_user_permissions.png)
+    #
+    # In this form the following fields can be filled:
+    #
+    # * **Name** (required): the full name of the user.
+    # * **Email** (required): the Email address of the user, used for logging
+    #   in.
+    # * **Website**: the website of the user (if he/she has any).
+    # * **Password** (required for new users): the raw password the user will
+    #   use in order to log in.
+    # * **Confirm password** (required for new users): an extra field to confirm
+    #   that the specified password is the right one. This field should match
+    #   the password specified in the "Password" field.
+    # * **Status**: field that indicates if a user is active or not. If the
+    #   status is set to "Closed" the user will not be able to log in.
+    # * **User Groups**: all the user groups the user belongs to.
+    # * **Language**: the language to use for the admin interface.
+    # * **Frontend language**: the language to use for the frontend of the
+    #   application.
+    # * **Date format**: the date format to use in the admin interface.
+    #
+    # Besides these fields there's also the tab "Permissions". This tab contains
+    # a collection of all installed packages and their permissions. This makes
+    # it possible to fine tune the access of a certain user.
+    #
+    # ## Used Permissions
+    #
+    # This controller uses the following permissions:
+    #
+    # * show_user
+    # * new_user
+    # * edit_user
+    # * delete_user
+    #
+    # ## Events
+    #
+    # Events in this controller receive an instance of {Users::Model::User}, the
+    # ``after_delete_user`` event receives an instance that has already been
+    # destroyed. Keep in mind that changing the Email address or password of a
+    # user will cause their session to no longer be valid, requiring them to log
+    # in again.
+    #
+    # @example Sending an Email for a new user
+    #  Zen::Event.listen(:after_new_user) do |user|
+    #    Mail.deliver do
+    #      from    'user@domain.tld'
+    #      to      user.email
+    #      subject 'Your new account'
+    #      body    "Dear #{user.name}, your account has been created."
+    #    end
+    #  end
     #
-    # @author Yorick Peterse
     # @since  0.1
+    # @map    /admin/users
+    # @event  before_new_user
+    # @event  after_new_user
+    # @event  before_edit_user
+    # @event  after_edit_user
+    # @event  before_delete_user
+    # @event  after_delete_user
+    # @event  user_login
+    # @event  before_register_user
+    # @event  after_register_user
     #
     class Users < Zen::Controller::AdminController
-      include ::Users::Model
+      helper :users, :layout
+      map    '/admin/users'
+      title  'users.titles.%s'
+      allow  [:login, :logout, :register]
 
-      helper :users
-      map '/admin/users'
+      csrf_protection :save, :delete
 
-      before_all do
-        csrf_protection(:save, :delete) do
-          respond(lang('zen_general.errors.csrf'), 403)
-        end
-      end
+      serve :javascript, ['/admin/js/users/permissions'], :minify => false
+      serve :css, ['/admin/css/users/permissions'], :minify => false
 
-      # Every action should use the admin layout except the 'login' method,
-      # that one will use a trimmed down version of the admin layout.
-      layout do |path, format|
-        if path == 'login'
-          :login
-        else
-          :admin
-        end
-      end
+      load_asset_group :tabs
 
-      ##
-      # Load our language packs, set the form URLs and define our page title.
-      #
-      # This method loads the following language files:
-      #
-      # * users
-      #
-      # @author Yorick Peterse
-      # @since  0.1
-      #
-      def initialize
-        super
-
-        Zen::Language.load('users')
-
-        # Set the page title
-        if !action.method.nil?
-          method      = action.method.to_sym
-          @page_title = lang("users.titles.#{method}") rescue nil
-        end
-
-        @status_hash = {
-          'open'   => lang('users.special.status_hash.open'),
-          'closed' => lang('users.special.status_hash.closed')
-        }
-      end
+      set_layout :admin => [:index, :edit, :new],
+        :login => [:login, :register]
 
       ##
       # Show an overview of all users and allow the current user
       # to manage these users.
       #
-      # This method requires the following permissions:
-      #
-      # * read
-      #
-      # @author Yorick Peterse
-      # @since  0.1
+      # @since      0.1
+      # @permission show_user
       #
       def index
-        require_permissions(:read)
+        authorize_user!(:show_user)
 
         set_breadcrumbs(lang('users.titles.index'))
 
-        @users = paginate(User)
+        @users = search do |query|
+          ::Users::Model::User.search(query).order(:id.asc)
+        end
+
+        @users ||= ::Users::Model::User.order(:id.asc)
+        @users   = @users.eager(:user_status)
+        @users   = paginate(@users)
       end
 
       ##
       # Edit an existing user based on the ID.
       #
-      # This method requires the following permissions:
-      #
-      # * read
-      # * update
-      #
-      # @author Yorick Peterse
-      # @param  [Integer] id The ID of the user to edit.
-      # @since  0.1
+      # @param      [Fixnum] id The ID of the user to edit.
+      # @since      0.1
+      # @permission edit_user
       #
       def edit(id)
-        require_permissions(:read, :update)
+        authorize_user!(:edit_user)
 
         set_breadcrumbs(
           Users.a(lang('users.titles.index'), :index),
           lang('users.titles.edit')
         )
 
-        if flash[:form_data]
-          @user = flash[:form_data]
-        else
-          @user = validate_user(id)
-        end
-
-        @user_group_pks = UserGroup.pk_hash(:name)
+        @user           = flash[:form_data] || validate_user(id)
+        @user_group_pks = ::Users::Model::UserGroup.pk_hash(:name).invert
+        @permissions    = @user.permissions.map { |p| p.permission.to_sym }
 
         render_view(:form)
       end
@@ -115,24 +170,19 @@ module Users
       ##
       # Create a new user.
       #
-      # This method requires the following permissions:
-      #
-      # * read
-      # * create
-      #
-      # @author Yorick Peterse
-      # @since  0.1
+      # @since      0.1
+      # @permission new_user
       #
       def new
-        require_permissions(:read, :create)
+        authorize_user!(:new_user)
 
         set_breadcrumbs(
           Users.a(lang('users.titles.index'), :index),
           lang('users.titles.new')
         )
 
-        @user           = User.new
-        @user_group_pks = UserGroup.pk_hash(:name)
+        @user           = flash[:form_data] || ::Users::Model::User.new
+        @user_group_pks = ::Users::Model::UserGroup.pk_hash(:name).invert
 
         render_view(:form)
       end
@@ -140,29 +190,29 @@ module Users
       ##
       # Show a form that allows a user to log in.
       #
-      # @author Yorick Peterse
       # @since  0.1
+      # @event  user_login
       #
       def login
         if request.post?
           # Let's see if we can authenticate
           if user_login(request.subset(:email, :password))
-            # Update the last time the user logged in
-            User[:email => request.params['email']] \
-              .update(:last_login => Time.new)
+            user.update(:last_login => Time.new)
 
+            Zen::Event.call(:user_login, user)
             message(:success, lang('users.success.login'))
             redirect(::Sections::Controller::Sections.r(:index))
           else
             message(:error, lang('users.errors.login'))
           end
+
+          redirect(r(:login))
         end
       end
 
       ##
       # Logout and destroy the user's session.
       #
-      # @author Yorick Peterse
       # @since  0.1
       #
       def logout
@@ -170,19 +220,72 @@ module Users
         session.clear
 
         message(:success, lang('users.success.logout'))
-        redirect(Users.r(:login))
+        redirect(r(:login))
       end
 
       ##
-      # Saves or creates a new user based on the POST data and a field named 'id'.
+      # Allows non registered users to create an account as long as the setting
+      # "allow_registration" allows this. In case of errors this method will
+      # redirect to itself, this works around those rather annoying "Do you want
+      # to resubmit this form?" messages most browsers give you.
       #
-      # This method requires the following permissions:
+      # The events ``before_register_user`` and ``after_register_user`` will
+      # receive an instance of {Users::Model::User} as well as the raw password
+      # specified by the user.
       #
-      # * create
-      # * update
+      # @since 0.3
+      # @event before_register_user
+      # @event after_register_user
       #
-      # @author Yorick Peterse
-      # @since  0.1
+      def register
+        redirect(::Sections::Controller::Sections.r(:index)) if logged_in?
+        redirect(r(:login)) unless get_setting(:allow_registration).true?
+
+        if request.post?
+          post = request.subset(:name, :email, :password)
+          user = Model::User.new(post)
+
+          # Check if the passwords match.
+          if post['password'] != request.params['confirm_password']
+            flash[:form_data] = user
+
+            message(:error, lang('users.errors.no_password_match'))
+            redirect(r(:register))
+          end
+
+          Zen::Event.call(:before_register_user, user, post['password'])
+
+          begin
+            user.save
+          rescue => e
+            Ramaze::Log.error(e.inspect)
+            message(:error, lang('users.errors.register'))
+
+            flash[:form_errors] = user.errors
+            flash[:form_data]   = user
+
+            redirect(r(:register))
+          end
+
+          Zen::Event.call(:after_register_user, user, post['password'])
+          message(:success, lang('users.success.register'))
+
+          redirect(r(:login))
+        end
+
+        @user = flash[:form_data] || Model::User.new
+      end
+
+      ##
+      # Saves or creates a new user based on the POST data.
+      #
+      # @since      0.1
+      # @permission new_user (when creating a new user)
+      # @permission edit_user (when editing a user)
+      # @event      before_new_user
+      # @event      after_new_user
+      # @event      before_edit_user
+      # @event      after_edit_user
       #
       def save
         post = request.subset(
@@ -190,9 +293,9 @@ module Users
           :email,
           :name,
           :website,
-          :new_password,
+          :password,
           :confirm_password,
-          :status,
+          :user_status_id,
           :language,
           :frontend_language,
           :date_format,
@@ -200,43 +303,42 @@ module Users
         )
 
         if post['id'] and !post['id'].empty?
-          require_permissions(:update)
+          authorize_user!(:edit_user)
 
-          user        = validate_user(post['id'])
-          save_action = :save
+          user         = validate_user(post['id'])
+          save_action  = :save
+          before_event = :before_edit_user
+          after_event  = :after_edit_user
         else
-          require_permissions(:create)
+          authorize_user!(:new_user)
 
-          user        = User.new
-          save_action = :new
+          user         = ::Users::Model::User.new
+          save_action  = :new
+          before_event = :before_new_user
+          after_event  = :after_new_user
         end
 
-        if !post['new_password'].nil? and !post['new_password'].empty?
-          if post['new_password'] != post['confirm_password']
-            message(:error, lang('users.errors.no_password_match'))
-            redirect_referrer
-          else
-            post['password'] = post['new_password']
-
-            post.delete('new_password')
-            post.delete('confirm_password')
-          end
+        if post['password'] != post['confirm_password']
+          message(:error, lang('users.errors.no_password_match'))
+          redirect_referrer
         end
 
+        post.delete('confirm_password')
         post.delete('id')
 
         post['user_group_pks'] ||= []
-        post['user_group_pks']   = post['user_group_pks'].map { |value| value.to_i }
-
-        flash_success = lang("users.success.#{save_action}")
-        flash_error   = lang("users.errors.#{save_action}")
+        success            = lang("users.success.#{save_action}")
+        error              = lang("users.errors.#{save_action}")
 
         begin
-          user.update(post)
-          message(:success, flash_success)
+          post.each { |k, v| user.send("#{k}=", v) }
+          Zen::Event.call(before_event, user)
+
+          user.save
+          user.user_group_pks = post['user_group_pks'] if save_action == :new
         rescue => e
           Ramaze::Log.error(e.inspect)
-          message(:error, flash_error)
+          message(:error, error)
 
           flash[:form_data]   = user
           flash[:form_errors] = user.errors
@@ -244,25 +346,32 @@ module Users
           redirect_referrer
         end
 
-        if user.id
-          redirect(Users.r(:edit, user.id))
-        else
-          redirect_referrer
+        # Add or update the permissions if the user is allowed to do so.
+        if user_authorized?(:edit_permission)
+          update_permissions(
+            :user_id,
+            user.id,
+            request.params['permissions'] || [],
+            user.permissions.map { |p| p.permission }
+          )
         end
+
+        Zen::Event.call(after_event, user)
+
+        message(:success, success)
+        redirect(Users.r(:edit, user.id))
       end
 
       ##
       # Delete all specified users.
       #
-      # This method requires the following permissions:
-      #
-      # * delete
-      #
-      # @author Yorick Peterse
-      # @since  0.1
+      # @since      0.1
+      # @permission delete_user
+      # @event      before_delete_user
+      # @event      after_delete_user
       #
       def delete
-        require_permissions(:delete)
+        authorize_user!(:delete_user)
 
         if !request.params['user_ids'] or request.params['user_ids'].empty?
           message(:error, lang('users.errors.no_delete'))
@@ -270,17 +379,25 @@ module Users
         end
 
         request.params['user_ids'].each do |id|
+          user = ::Users::Model::User[id]
+
+          next if user.nil?
+          Zen::Event.call(:before_delete_user, user)
+
           begin
-            User[id].destroy
-            message(:success, lang('users.success.delete'))
+            user.user_group_pks = []
+            user.destroy
           rescue => e
             Ramaze::Log.error(e.inspect)
-            message(:error,lang('users.errors.delete') % id)
+            message(:error, lang('users.errors.delete') % id)
 
             redirect_referrer
           end
+
+          Zen::Event.call(:after_delete_user, user)
         end
 
+        message(:success, lang('users.success.delete'))
         redirect_referrer
       end
     end # Users