your_platform 0.0.1 → 0.0.2

data/app/models/group_mixins/guests.rb

@@ -0,0 +1,61 @@
+#
+# All groups have associated special groups, for example the `guests_parent` group, which
+# contains all guests of the group. 
+# 
+# This mixin provides the accessor methods for the guests_parent special group.
+#
+# The mechanism used in the mixin is defined in `StructureableMixins::HasSpecialGroups`.
+#
+module GroupMixins::Guests
+
+  extend ActiveSupport::Concern
+
+  included do
+    # see, for example, http://stackoverflow.com/questions/5241527/splitting-a-class-into-multiple-files-in-ruby-on-rails
+  end
+  
+  
+  # Guests
+  # ==========================================================================================
+
+  def find_guests_parent_group
+    find_special_group(:guests_parent)
+  end
+
+  def create_guests_parent_group
+    create_special_group(:guests_parent)
+  end
+
+  def find_or_create_guests_parent_group
+    find_or_create_special_group(:guests_parent)
+  end
+
+  def guests_parent
+    find_or_create_guests_parent_group
+  end
+
+  def guests_parent!
+    find_guests_parent_group || raise('special group :guests_parent does not exist.')
+  end
+
+  def find_guest_users
+    guests_parent.descendant_users
+  end
+
+  def guests
+    find_guest_users
+  end
+
+  # This method lists all guest subgroups of self, but not of the subgroups of self.
+  # This is used, for example, if there are several kinds of guests.
+  #
+  #    my_group
+  #        |---------- guests_parent
+  #                       |----------- regular_guests    <-- returned by this
+  #                       |----------- vip_guests        <-- method.
+  #
+  def find_guests_groups
+    find_guests_parent_group.descendant_groups
+  end
+  
+end  

data/app/models/group_mixins/hidden_users.rb

@@ -0,0 +1,43 @@
+#
+# There are certain gloabl special groups, for example the `everyone` group, which contains
+# all users.
+#
+# The mechanism used by this mixin is defined in `StructureableMixins::HasSpecialGroups`.
+#
+module GroupMixins::HiddenUsers
+
+  extend ActiveSupport::Concern
+
+  included do
+    # see, for example, http://stackoverflow.com/questions/5241527/splitting-a-class-into-multiple-files-in-ruby-on-rails
+  end
+
+  # Hidden Users
+  # ==========================================================================================
+  #
+  # This group contains all users that are hidden to normal users and only visible
+  # to their administrators.
+  #
+  module ClassMethods
+    def find_hidden_users_group
+      find_special_group(:hidden_users)
+    end
+    
+    def create_hidden_users_group
+      create_special_group(:hidden_users)
+    end
+
+    def find_or_create_hidden_users_group
+      find_or_create_special_group(:hidden_users)
+    end
+    
+    def hidden_users
+      find_or_create_hidden_users_group
+    end
+    
+    def hidden_users!
+      find_hidden_users_group || raise('special group :hidden_users does not exist.')
+    end
+  end
+
+end

data/app/models/group_mixins/import.rb

@@ -0,0 +1,321 @@
+# -*- coding: utf-8 -*-
+
+# This module extends the Group model by group import methods.
+# This allows, for example, to import groups from a previous application or to auto-load
+# a certain default group structure.
+#
+# The module is included in the Group model by `include GroupMixins::Import`.
+# The methods of the module can be accessed just like any other Group model methods:
+#    Group.class_method()
+#    g = Group.new()
+#    g.instance_method()
+#
+module GroupMixins::Import
+
+  extend ActiveSupport::Concern
+
+  included do
+  end
+
+
+  # Hash Array Import
+  # ==========================================================================================
+
+  module ClassMethods
+
+    # Import Hash Array of groups into a parent group.
+    # Each group in the array is represented by a hash. Each hash contains the attributes
+    # of the group. The group's children are represented by another hash array, which is
+    # stored at the `children` key.
+    #
+    # The hash array should like this:
+    #     [
+    #         {
+    #             :name => "Group 1",
+    #             :children => [
+    #                 {
+    #                     :name => "Group 1.1"
+    #                 },
+    #                 {
+    #                     :name => "Group 1.2"
+    #                 }
+    #             ]
+    #         }
+    #     ]
+    #
+    # This is a helper method, which is used by other import methods like
+    # `json_import_groups_into_parent_group`.
+    #
+    def hash_array_import_groups_into_parent_group( hash_array_of_groups, parent_group )
+      return unless hash_array_of_groups
+      counter_for_created_groups = 0
+
+      for new_group_hash in hash_array_of_groups do
+        
+        unless parent_group.children.select { |child| child.name == (new_group_hash["name"] || new_group_hash[:name]) }.count > 0
+
+          # get children from hash
+          sub_group_hash_array = new_group_hash[ "children" ]
+          sub_group_hash_array = new_group_hash[ :children ] unless sub_group_hash_array
+          new_group_hash.reject! { |key| key.to_sym == :children }
+
+          # get domain from hash
+          domain = new_group_hash[ "domain" ]
+          new_group_hash.reject! { |key| key.to_sym == :domain }
+
+          # create the new group
+          g = Group.create( new_group_hash )
+          g.parent_groups << parent_group
+          g.set_flags_based_on_group_name
+          g.save
+
+          # import the child's children as well
+          self.hash_array_import_groups_into_parent_group sub_group_hash_array, g if sub_group_hash_array
+          counter_for_created_groups += 1
+
+          # set domain as url component in navnode
+          g.navnode.update_attribute(:url_component, "#{domain}/")
+        end
+      end
+
+      return counter_for_created_groups.to_s + " groups created."
+    end
+
+    # Convert an array of group names, like
+    #
+    #   [ "Group 1",
+    #     { "Group 2" => [ "Group 2.1", "Group 2.2" ] },
+    #     ... ]
+    #
+    # into an array of hashes as used by the `hash_array_import_groups_into_parent_group`
+    # method.  The result looks like this:
+    #
+    #   [
+    #      { :name => "Group 1" },
+    #      { :name => "Group 2", children: [
+    #                                         { name: "Group 2.1" },
+    #                                         { name: "Group 2.2" }
+    #                                      ]
+    #      },
+    #      ...
+    #   ]
+    #
+    # This method is used in the YAML import mechanism.
+    #
+    def convert_group_names_to_group_hashes( group_names )
+      group_names.map do |array_item|
+        if array_item.kind_of? String
+          { name: array_item }
+        elsif array_item.kind_of? Hash
+          unless array_item[ :name ]
+            { name: array_item.keys.first,
+              children: convert_group_names_to_group_hashes( array_item[ array_item.keys.first ] )
+            }
+          end
+        end
+      end
+    end
+
+  end
+
+
+  # CSV Import
+  # ==========================================================================================
+
+  module ClassMethods
+
+    # Import groups listed in a comma-separated-values file (CSV) into a parent group.
+    # The CSV format should look like this:
+    #
+    #    token;name
+    #    GA;Group A
+    #    GB;Group B
+    #
+    # Feel free to use other attributes in the CSV file as well. They will simply be
+    # converted into a hash and then passed to a `create` method.
+    #
+    # Note: This script expects a semicolon (;) to be used as separator.
+    #
+    # The csv file is to be placed in the #{Rails.root}/import folder of the main
+    # application. For the file #{Rails.root}/import/foo_groups.csv, call:
+    #
+    #    Group.csv_import_groups_into_parent_group( "foo_groups.csv", foo_parent_group )
+    #
+    def csv_import_groups_into_parent_group( csv_file_title, parent_group )
+      import_file_name = File.join( Rails.root, "import", csv_file_title )
+      require 'csv'
+      CSV.foreach import_file_name, headers: true, col_sep: ';' do |row|
+
+        new_child_group = Group.create row.to_hash
+        parent_group.child_groups << new_child_group
+
+      end
+    end
+
+  end
+
+
+  # JSON Import
+  # ==========================================================================================
+
+  module ClassMethods
+
+    # Import groups from a JSON format file into a parent group.
+    # The JSON file should look like this:
+    #
+    #     [
+    #         {
+    #             "name": "Group 1",
+    #             "children":
+    #             [
+    #                 {
+    #                     "name": "Group 1.1"
+    #                 },
+    #                 {
+    #                     "name": "Group 1.2",
+    #                     "children":
+    #                     [
+    #                         {
+    #                             "name": "Group 1.2.1"
+    #                         },
+    #                         {
+    #                             "name": "Group 1.2.2"
+    #                         }
+    #                     ]
+    #                 }
+    #             ]
+    #         },
+    #         {
+    #             "name": "Group 2"
+    #         }
+    #     ]
+    #
+    # The json file is to be placed in the #{Rails.root}/import folder of the main
+    # application. For the file #{Rails.root}/import/foo_groups.json, call:
+    #
+    #    Group.json_import_groups_into_parent_group( "foo_groups.json", foo_parent_group )
+    #
+    def json_import_groups_into_parent_group( json_file_title, parent_group )
+      raise "no parent group given during import" unless parent_group
+      import_json_file = File.open( File.join( Rails.root, "import", json_file_title ), "r" )
+      json = IO.read( import_json_file )
+
+      new_child_groups_hash_array = JSON.parse( json )
+      p self.hash_array_import_groups_into_parent_group new_child_groups_hash_array, parent_group
+    end
+
+  end
+
+
+  # YAML Import
+  # ==========================================================================================
+
+  module ClassMethods
+
+    # Import the groups of a YAML file into a parent group.
+    # The YAML file should look like this:
+    #
+    #   - Group 1
+    #   - Group 2:
+    #       - Group 2.1:
+    #           - Group 2.1.1
+    #           - Group 2.1.2
+    #       - Group 2.2
+    #   - Group 3:
+    #       - Group 3.1
+    # 
+    # The YAML files are expected to be stored in the `#{Rails.root}/import` directory 
+    # of the main application. For example, the file `#{Rails.root}/import/foo.yml`
+    # is imported by calling:
+    # 
+    #    Group.yaml_import_groups_into_parent_group( "foo.yml", parent_group )
+    # 
+    def yaml_import_groups_into_parent_group( yaml_file_title, parent_group )
+      yaml_file_name = File.join( Rails.root, "import", yaml_file_title )
+      if File.exists? yaml_file_name
+
+        sub_group_hashes = []
+        File.open( yaml_file_name, "r" ) do |file|
+          sub_group_hashes = YAML::load(file)
+        end
+        
+        # This allows to use a short-form of yaml. Because of this, one doesn't need to
+        # specify the `name` attribute in yaml, but can just use the group name as key,
+        # like shown above in the description of the `yaml_import_groups_into_parent_group`
+        # method.
+        sub_group_hashes = convert_group_names_to_group_hashes( sub_group_hashes )
+        
+        Group.hash_array_import_groups_into_parent_group( sub_group_hashes, parent_group )
+
+      else
+        return false
+      end
+    end
+
+  end
+
+
+  # Import of the Default Sub-Structure of a Group
+  # ==========================================================================================
+
+  # Import the default group structure.
+  # This is called after creation of the group.
+  #
+  # The structure is to be placed in a file at
+  #   #{Rails.root}/import/default_group_sub_structures/#{self.name}.yml
+  # and is to be formatted in yaml, like this:
+  #
+  #   - Group 1
+  #   - Group 2:
+  #       - Group 2.1:
+  #           - Group 2.1.1
+  #           - Group 2.1.2
+  #       - Group 2.2
+  #   - Group 3:
+  #       - Group 3.1
+  #
+  def import_default_group_structure( yaml_file_title = nil )
+    yaml_file_title ||= yaml_file_title = File.join( "default_group_sub_structures",
+                                                     "#{self.name}.yml" )
+    parent_group = self
+    Group.yaml_import_groups_into_parent_group( yaml_file_title, parent_group )
+  end
+
+
+  # Special Groups
+  # ==========================================================================================
+
+  # When importing group structures, certain group names indicate special group attributes.
+  # This method sets these flags based on the group name.
+  # 
+  # This method is called by the `hash_array_import_groups_into_parent_group` method.
+  # 
+  def set_flags_based_on_group_name 
+
+    # Officers
+    set_flag_based_on_name :officers_parent
+
+    # Guests
+    set_flag_based_on_name :guests_parent
+
+    # Deceased
+    set_flag_based_on_name :deceased_parent
+    
+    # Former Members
+    set_flag_based_on_name :former_members_parent
+    
+  end
+
+  def set_flag_based_on_name( name )
+    translations = []
+    name = name.to_sym
+    I18n.translate( name ) # required to initialize the I18n 
+    I18n.backend.send( :translations ).each do |language, translations_hash|
+      translations << translations_hash[ name ]
+    end
+    if self.name.in? translations
+      self.add_flag( name )
+    end
+  end
+
+end

data/app/models/group_mixins/memberships.rb

@@ -0,0 +1,207 @@
+# 
+# This module contains the methods of the Group model regarding the associated 
+# user group memberships and users, i.e. members.
+#
+module GroupMixins::Memberships
+  
+  extend ActiveSupport::Concern
+  
+  # TODO: Refactor conditions to rails 4 standard when migrating to rails 4.
+  # See, for example, https://github.com/fiedl/neo4j_ancestry/blob/master/lib/models/neo4j_ancestry/active_record_additions.rb#L117.
+  
+  included do
+
+    # User Group Memberships
+    # ==========================================================================================
+    
+    # This associates all UserGroupMembership objects of the group, including indirect 
+    # memberships.
+    #
+    has_many( :memberships, 
+              class_name: 'UserGroupMembership',
+              foreign_key: :ancestor_id, conditions: { ancestor_type: 'Group', descendant_type: 'User' } )
+    
+    # This associates all memberships of the group that are direct, i.e. direct 
+    # parent_group-child_user memberships.
+    #
+    has_many( :direct_memberships,
+              class_name: 'UserGroupMembership', 
+              foreign_key: :ancestor_id, conditions: { ancestor_type: 'Group', descendant_type: 'User', direct: true } )
+              
+    # This associates all memberships of the group that are indirect, i.e. 
+    # ancestor_group-descendant_user memberships, where groups are between the
+    # ancestor_group and the descendant_user.
+    #
+    has_many( :indirect_memberships,
+              class_name: 'UserGroupMembership', 
+              foreign_key: :ancestor_id, conditions: { ancestor_type: 'Group', descendant_type: 'User', direct: false } )
+     
+    
+    #  This method builds a new membership having this group (self) as group associated.
+    #
+    def build_membership
+      direct_memberships.build(descendant_type: 'User')
+    end
+    
+    # This returns the UserGroupMembership object that represents the membership of the 
+    # given user in this group.
+    # 
+    # options:
+    #   - also_in_the_past 
+    #
+    def membership_of(user, options = {})
+      if options[:also_in_the_past]
+        base = UserGroupMembership.with_invalid
+      else
+        base = UserGroupMembership
+      end
+      base.find_by_user_and_group(user, self)
+    end
+    
+    # This returns a string of the titles of the direct members of this group. This is used
+    # for in-place editing, for example.
+    # 
+    # The string would be something like this:
+    # 
+    #    "#{user1.title}, #{user2.title}, ..."
+    #
+    def direct_members_titles_string
+      direct_members.collect { |user| user.title }.join( ", " )
+    end
+    
+    # This sets the memberships of a group according to the given string of user titles.
+    # 
+    # For example, after calling
+    # 
+    #    direct_members_titles_string = "#{user1.title}, #{user2.title}",
+    # 
+    # the users `user1` and `user2` are the only direct members of the group.
+    # The memberships are removed using the standard methods, which means that the memberships
+    # are only marked as deleted. See: acts_as_paranoid_dag gem.
+    #
+    def direct_members_titles_string=( titles_string )
+      new_members_titles = titles_string.split( "," )
+      new_members = new_members_titles.collect do |title|
+        u = User.find_by_title( title.strip )
+        self.errors.add :direct_member_titles_string, 'user not found: #{title}' unless u
+        u
+      end
+      for member in self.direct_members
+        unassign_user member unless member.in? new_members if member
+      end
+      for new_member in new_members
+        assign_user new_member if new_member
+      end
+    end
+    
+    def memberships_including_members
+      memberships.includes(:descendant).order('valid_from' => 'desc')
+    end
+    
+    # This returns the memberships that appear in the member list
+    # of the group.
+    #
+    # For a regular group, these are just the usual memberships.
+    # For a corporation, the members of the 'former members' subgroup
+    # of the corporation are excluded, even though they still have 
+    # memberships.
+    #
+    def memberships_for_member_list
+      cached do
+        if corporation?
+          (
+            memberships_including_members - 
+              becomes(Corporation).former_members_memberships -
+              becomes(Corporation).deceased_members_memberships
+          )
+        else
+          memberships_including_members
+        end
+      end
+    end
+    def memberships_for_member_list_count
+      cached { memberships_for_member_list.count }
+    end
+    
+    def latest_memberships
+      cached do
+        # TODO: Fix this syntax when migrating to Rails 4.
+        # self.memberships.with_invalid...
+        UserGroupMembership.with_invalid.find_all_by_group(self).reorder('valid_from DESC').limit(10).includes(:descendant)
+      end
+    end
+    
+    def memberships_this_year
+      cached do
+        # TODO: Fix this syntax when migrating to Rails 4.
+        # self.memberships.this_year...
+        UserGroupMembership.this_year.find_all_by_group(self)
+      end
+    end
+
+    # User Assignment
+    # ==========================================================================================
+    
+    # This assings the given user as a member to the group, i.e. this will
+    # create a UserGroupMembership.
+    #
+    def assign_user( user, options = {} )
+      if user and not user.in?(self.direct_members)
+        membership = UserGroupMembership.create(user: user, group: self)
+        time_of_joining = options[:joined_at] || options[:at] || options[:time] || Time.zone.now
+        membership.update_attribute(:valid_from, time_of_joining)
+        return membership
+      end
+    end
+    
+    # This method will remove a UserGroupMembership, i.e. terminate the membership
+    # of the given user in this group.
+    #
+    def unassign_user( user, options = {} )
+      if user and user.in?(self.members)
+        time_of_unassignment = options[:at] || options[:time] || Time.zone.now
+        UserGroupMembership.find_by(user: user, group: self).invalidate(at: time_of_unassignment)
+      end
+    end
+    
+    
+    def calculate_validity_range_of_indirect_memberships
+      self.indirect_memberships.where(valid_from: nil).each do |membership| 
+        membership.recalculate_validity_range_from_direct_memberships
+        membership.save
+      end
+    end
+    
+    
+    # Members
+    # ==========================================================================================
+
+    # This associates the group members (users), direct ones as well as indirect ones.
+    #
+    # Attention! The conditions on the `memberships` association are ignored by Rails 3
+    # when generating the SQL query. This is why the conditions have to be repeated here.
+    #
+    has_many(:members, 
+      through: :memberships, 
+      source: :descendant, source_type: 'User', :uniq => true,
+      conditions: { 'dag_links.ancestor_type' => 'Group' }
+      )
+
+    # This associates only the direct group members (users).
+    #
+    has_many(:direct_members, 
+      through: :direct_memberships, 
+      source: :descendant, source_type: 'User', :uniq => true,
+      conditions: { 'dag_links.ancestor_type' => 'Group', 'dag_links.direct' => true }
+      )
+    
+    # This associates only the indirect group members (users).
+    #
+    has_many(:indirect_members, 
+      through: :indirect_memberships, 
+      source: :descendant, source_type: 'User', :uniq => true,
+      conditions: { 'dag_links.ancestor_type' => 'Group', 'dag_links.direct' => false }
+      )
+    
+  end
+end