Automatically Assign group leaders

closes: CNVS-11834

This creates a way for an instructor to
assign a random student as the group leader.
It only applies when an instructor is having groups
created automatically at the time of defining
a group category.

This also take an opportunity to refactor out
some bloated code from the group_categories_controller
and move it into some separate objects
that can be more easily understood and rapidly
unit tested through all the necessary permutations
(allowing higher level integration tests to just
cover a case or two)

It ALSO removes group leadership knowledge into
it's own object so that the callbacks in other
objects are simple and the logic regarding
how to do group leadership management is in
one place.

TEST PLAN:

AUTO_DISTRIBUTION:
1) login as an instructor
2) go to the "people" tab and try to create a group
set.
3) click on the "Create [0] groups for me" radio
button; verify you now have controls for assigning
a group leader automatically and that the strategy
radio buttons are greyed out.
4) check the "Assign a group leader automatically"
checkbox; verify the 2 nested radio buttons for
"random" and "first" strategies become enabled
5) select a strategy and fill out the rest of the
form, then submit (make sure your background job
is running)
6) verify after groups are created that each group
has a leader, and that the leader is in fact a member
of the group.

SelfSignup:
1) login as an instructor
2) go to the "people" tab and try to create a group
set.
3) enable self-signup.
4) check the "Assign a group leader automatically"
checkbox; verify the 2 nested radio buttons for
"random" and "first" strategies become enabled
5) select a strategy and fill out the rest of the
form, then submit.
6) Login as a student for the same course and join
the group.
7) verify that the student has been made the group
leader.

Change-Id: I2cdd9f5ed2fd577469beec4ab7369c69ecf7eaa6
Reviewed-on: https://gerrit.instructure.com/35130
Tested-by: Jenkins <jenkins@instructure.com>
Reviewed-by: Braden Anderson <banderson@instructure.com>
QA-Review: Trevor deHaan <tdehaan@instructure.com>
Product-Review: Ethan Vizitei <evizitei@instructure.com>

Author: evizitei

app/coffeescripts/views/groups/manage/GroupCategoryCreateView.coffee

@@ -15,24 +15,49 @@ define [
 
     defaults:
       width: 600
-      height: if ENV.allow_self_signup then 460 else 310
+      height: if ENV.allow_self_signup then 520 else 310
       title: I18n.t('create_group_set', 'Create Group Set')
 
     els: _.extend {},
       GroupCategoryEditView::els
       '.admin-signup-controls': '$adminSignupControls'
       '#split_groups': '$splitGroups'
+      '.auto-group-leader-toggle': '$autoGroupLeaderToggle'
+      '.auto-group-leader-controls': '$autoGroupLeaderControls'
+      '.admin-signup-controls input[name=split_groups][value=1]': '$autoGroupSplitControl'
 
     events: _.extend {},
       GroupCategoryEditView::events
       'click .admin-signup-controls [name=create_group_count]': 'clickSplitGroups'
+      'click .auto-group-leader-toggle': 'toggleAutoGroupLeader'
+      'click .admin-signup-controls input[name=split_groups]' : 'setVisibilityOfGroupLeaderControls'
+
+
+    afterRender: ->
+      super()
+      @setVisibilityOfGroupLeaderControls()
+      @toggleAutoGroupLeader()
+
+    toggleAutoGroupLeader: ->
+      enabled = @$autoGroupLeaderToggle.prop 'checked'
+      @$autoGroupLeaderControls.find('label.radio').css opacity: if enabled then 1 else 0.5
+      @$autoGroupLeaderControls.find('input[name=auto_leader_type]').prop('disabled', !enabled)
+
+    setVisibilityOfGroupLeaderControls: ->
+      splitGroupsChecked = @$autoGroupSplitControl.prop("checked")
+      show = (@selfSignupIsEnabled() or splitGroupsChecked)
+      @$autoGroupLeaderControls.toggle(show)
 
     toggleSelfSignup: ->
-      enabled = @$selfSignupToggle.prop('checked')
+      enabled = @selfSignupIsEnabled()
       @$el.toggleClass('group-category-self-signup', enabled)
       @$el.toggleClass('group-category-admin-signup', !enabled)
       @$selfSignupControls.find(':input').prop 'disabled', !enabled
       @$adminSignupControls.find(':input').prop 'disabled', enabled
+      @setVisibilityOfGroupLeaderControls()
+
+    selfSignupIsEnabled: ->
+      @$selfSignupToggle.prop('checked')
 
     clickSplitGroups: (e) ->
       # firefox doesn't like multiple inputs in the same label, so a little js to the rescue
@@ -53,4 +78,4 @@ define [
         create_group_count = parseInt(data.create_group_count)
         unless create_group_count > 0
           errors["create_group_count"] = [{type: 'positive_group_count', message: @messages.positive_group_count}]
-      errors
+      errors

app/controllers/group_categories_controller.rb

@@ -52,6 +52,16 @@
 #             ]
 #           }
 #         },
+#         "auto_leader": {
+#           "description": "Gives instructors the ability to automatically have group leaders assigned.  Values include 'random', 'first', and null; 'random' picks a student from the group at random as the leader, 'first' sets the first student to be assigned to the group as the leader",
+#           "type": "string",
+#           "allowableValues": {
+#             "values": [
+#               "first",
+#               "random"
+#             ]
+#           }
+#         },
 #         "context_type": {
 #           "description": "The course or account that the category group belongs to. The pattern here is that whatever the context_type is, there will be an _id field named after that type. So if instead context_type was 'Course', the course_id field would be replaced by an course_id field.",
 #           "example": "Account",
@@ -91,7 +101,7 @@ class GroupCategoriesController < ApplicationController
   # Returns a list of group categories in a context
   #
   # @example_request
-  #     curl https://<canvas>/api/v1/accounts/<account_id>/group_categories \ 
+  #     curl https://<canvas>/api/v1/accounts/<account_id>/group_categories \
   #          -H 'Authorization: Bearer <token>'
   #
   # @returns [GroupCategory]
@@ -116,7 +126,7 @@ def index
   # the rights to see it.
   #
   # @example_request
-  #     curl https://<canvas>/api/v1/group_categories/<group_category_id> \ 
+  #     curl https://<canvas>/api/v1/group_categories/<group_category_id> \
   #          -H 'Authorization: Bearer <token>'
   #
   # @returns GroupCategory
@@ -145,6 +155,13 @@ def show
   #   "enabled":: allows students to self sign up for any group in course
   #   "restricted":: allows students to self sign up only for groups in the
   #                  same section null disallows self sign up
+  #
+  # @argument auto_leader [Optional, "first"|"random"]
+  #   Assigns group leaders automatically when generating and allocating students to groups
+  #   Valid values are:
+  #   "first":: the first student to be allocated to a group is the leader
+  #   "random":: a random student from all members is chosen as the leader
+  #
   # @argument group_limit [Optional]
   #   Limit the maximum number of users in each group (Course Only). Requires
   #   self signup.
@@ -160,14 +177,13 @@ def show
   #   (Course Only)
   #
   # @example_request
-  #     curl htps://<canvas>/api/v1/courses/<course_id>/group_categories \ 
-  #         -F 'name=Project Groups' \ 
+  #     curl htps://<canvas>/api/v1/courses/<course_id>/group_categories \
+  #         -F 'name=Project Groups' \
   #         -H 'Authorization: Bearer <token>'
   #
   # @returns GroupCategory
   def create
     if authorized_action(@context, @current_user, :manage_groups)
-      process_group_category_api_params if api_request?
       @group_category = @context.group_categories.build
       if populate_group_category_from_params
         if api_request?
@@ -194,6 +210,13 @@ def create
   #   "enabled":: allows students to self sign up for any group in course
   #   "restricted":: allows students to self sign up only for groups in the
   #                  same section null disallows self sign up
+  #
+  # @argument auto_leader [Optional, "first"|"random"]
+  #   Assigns group leaders automatically when generating and allocating students to groups
+  #   Valid values are:
+  #   "first":: the first student to be allocated to a group is the leader
+  #   "random":: a random student from all members is chosen as the leader
+  #
   # @argument group_limit [Optional]
   #   Limit the maximum number of users in each group (Course Only). Requires
   #   self signup.
@@ -209,17 +232,16 @@ def create
   #   (Course Only)
   #
   # @example_request
-  #     curl https://<canvas>/api/v1/group_categories/<group_category_id> \ 
-  #         -X PUT \ 
-  #         -F 'name=Project Groups' \ 
+  #     curl https://<canvas>/api/v1/group_categories/<group_category_id> \
+  #         -X PUT \
+  #         -F 'name=Project Groups' \
   #         -H 'Authorization: Bearer <token>'
   #
   # @returns GroupCategory
   def update
     if authorized_action(@context, @current_user, :manage_groups)
       @group_category ||= @context.group_categories.find_by_id(params[:category_id])
       if api_request?
-        process_group_category_api_params
         if populate_group_category_from_params
           includes = ['progress_url']
           includes.concat(params[:includes]) if params[:includes]
@@ -242,7 +264,7 @@ def update
   #
   # @example_request
   #     curl https://<canvas>/api/v1/group_categories/<group_category_id> \
-  #           -X DELETE \ 
+  #           -X DELETE \
   #           -H 'Authorization: Bearer <token>'
   #
   def destroy
@@ -272,7 +294,7 @@ def destroy
   # Returns a list of groups in a group category
   #
   # @example_request
-  #     curl https://<canvas>/api/v1/group_categories/<group_cateogry_id>/groups \ 
+  #     curl https://<canvas>/api/v1/group_categories/<group_cateogry_id>/groups \
   #          -H 'Authorization: Bearer <token>'
   #
   # @returns [Group]
@@ -443,35 +465,14 @@ def assign_unassigned_members
 
   def populate_group_category_from_params
     args = api_request? ? params : params[:category]
-    name = args[:name] || @group_category.name
-    enable_self_signup = value_to_boolean args[:enable_self_signup]
-    restrict_self_signup = value_to_boolean args[:restrict_self_signup]
-    @group_category.name = name
-    @group_category.configure_self_signup(enable_self_signup, restrict_self_signup)
-    if @context.is_a?(Course)
-      if @group_category.self_signup
-        @group_category.create_group_count = args[:create_group_count].to_i
-      elsif args[:split_groups] != '0'
-        @group_category.create_group_count = args[:split_group_count] ? args[:split_group_count].to_i : args[:create_group_count].to_i
-        @group_category.assign_unassigned_members = true if @group_category.create_group_count
-      end
-    end
-    @group_category.group_limit = args[:group_limit]
+    @group_category = GroupCategories::ParamsPolicy.new(@group_category, @context).populate_with(args)
     unless @group_category.save
       render :json => @group_category.errors, :status => :bad_request
       return false
     end
     true
   end
 
-  def process_group_category_api_params
-    if params.has_key? 'self_signup'
-      self_signup = params[:self_signup].to_s.downcase
-      params[:enable_self_signup] = "1" if %w(enabled restricted).include? self_signup
-      params[:restrict_self_signup] = "1" if "restricted" == self_signup
-    end
-  end
-
   protected
   def get_category_context
     begin
@@ -483,7 +484,3 @@ def get_category_context
   end
 
 end
-
-
-
-

app/models/group.rb

@@ -133,11 +133,11 @@ def full?
   def group_category_limit_met?
     group_category && group_category.group_limit && participating_users.size >= group_category.group_limit
   end
+  private :group_category_limit_met?
 
   def student_organized?
     group_category && group_category.student_organized?
   end
-  private :group_category_limit_met?
 
   def update_max_membership_from_group_category
     if group_category && group_category.group_limit && (!max_membership || max_membership == 0)

app/models/group_categories/params.rb

@@ -0,0 +1,92 @@
+module GroupCategories
+
+  class Params < Struct.new(:name, :group_limit)
+
+    attr_reader :raw_params
+
+    def initialize(args, opts={})
+      super(args[:name], args[:group_limit])
+      @boolean_translator = opts.fetch(:boolean_translator){ Canvas::Plugin }
+      @raw_params = args
+    end
+
+    def self_signup
+      return _self_signup if _self_signup
+      return nil if !enable_self_signup
+      return 'restricted' if restrict_self_signup
+      'enabled'
+    end
+
+    def auto_leader
+      return _auto_leader if _auto_leader
+      return nil if !enable_auto_leader
+      return auto_leader_type if ['first', 'random'].include?(auto_leader_type)
+      raise(ArgumentError, "Invalid AutoLeader Type #{auto_leader_type}")
+    end
+
+    def create_group_count
+      return _create_group_count if self_signup
+      return nil unless split_group_enabled?
+      split_group_count
+    end
+
+    def assign_unassigned_members
+      return false if self_signup
+      split_group_enabled? && create_group_count && create_group_count > 0
+    end
+
+    private
+
+    def value_to_boolean(value)
+      @boolean_translator.value_to_boolean(value)
+    end
+
+    def split_group_enabled?
+      raw_params[:split_groups] != '0'
+    end
+
+    def split_group_count
+      if raw_params[:split_group_count]
+        raw_params[:split_group_count].to_i
+      else
+        _create_group_count
+      end
+    end
+
+    def _create_group_count
+      raw_params[:create_group_count].to_i
+    end
+
+    def _self_signup
+      raw_value = raw_params[:self_signup]
+      return nil unless raw_value
+      raw_value = raw_value.to_s.downcase
+      %w(enabled restricted).include?(raw_value) ? raw_value : nil
+    end
+
+    def _auto_leader
+      raw_value = raw_params[:auto_leader]
+      return nil unless raw_value
+      raw_value = raw_value.to_s.downcase
+      %w(random first).include?(raw_value) ? raw_value : nil
+    end
+
+    def auto_leader_type
+      raw_params[:auto_leader_type].downcase
+    end
+
+    def enable_self_signup
+      value_to_boolean raw_params[:enable_self_signup]
+    end
+
+    def restrict_self_signup
+      value_to_boolean raw_params[:restrict_self_signup]
+    end
+
+    def enable_auto_leader
+      value_to_boolean raw_params[:enable_auto_leader]
+    end
+
+  end
+
+end

app/models/group_categories/params_policy.rb

@@ -0,0 +1,26 @@
+module GroupCategories
+
+  class ParamsPolicy
+    attr_reader :group_category, :context
+
+    def initialize(category, category_context)
+      @group_category = category
+      @context = category_context
+    end
+
+    def populate_with(args, populate_opts={})
+      params = Params.new(args, populate_opts)
+      group_category.name = (params.name || group_category.name)
+      group_category.self_signup = params.self_signup
+      group_category.auto_leader = params.auto_leader
+      group_category.group_limit = params.group_limit
+      if context.is_a?(Course)
+        group_category.create_group_count = params.create_group_count
+        group_category.assign_unassigned_members = params.assign_unassigned_members
+      end
+      group_category
+    end
+
+  end
+
+end