Obsolete:Groupings OU

Since Moodle 1.8, the groups work has drifted somewhat, and The Open University hopes to do some further re-factoring during our current development phase with the Moodle community to get things back on track. To make the best use of limited time, we need to assess the current situation, where we want to go, and what are suitable self-contained tasks.

IMPORTANT: this 'specification' is not trying to compete with Enrique Castro's or Petr Skodak's (links below) - I hope we can reach a concensus.

(Also, still some gaps to fill!)

Relevant Links

• Enrique Castro group specification and bug [https://tracker.moodle.org/browse/MDL-10383 MDL-10383] (Uni of Las Palmas ULPGC).
• Petr Skodak group specification.
• Old Moodle meta bug [https://tracker.moodle.org/browse/MDL-7380 MDL-7380].
• Forum discussion: Possible groups features, J.White, June-November 2006.
• How groups work in Moodle, J.White, old.
• Groups documentation for module developers, J.White, old.
• JISC JoinIn project: Sharing Groups between LAMS and Moodle, December 2006, original collaboration by the Open University's Institute of Education Technology/Juliette White et al.

Glossary/ key

Grouping

The perhaps confusing term for a collection of groups, think groups for a particular purpose/activity, course categories. Do you have a better suggestion?

Not in a grouping

NIAG/ orphaned groups resulted from the ill-advised decision not to create a default grouping for a course during the upgrade to Moodle 1.8 (1.8.1).

DEL/ D

Proposal to delete files and/or functions and/or code.

MV

Proposal to move files and/or functions and/or code.

OU

Files, functions or code that are either specific to the Open University, or currently only in ou-moodle.

Current specification

The current specification is based on Moodle 1.8.1 (also see 1.9 dev), and highlights where there are differences in ou-moodle 'r18' (OU VLE 1.5?)

Database schema

The current schema is below.

Petr's proposal

The Database schema diagram above is currently in a state of change - the details below refer to the version of 9 July 2007.

This list is a way of clarifying Petr's specification - we're in agreement with most of it, but just finalising details! I assume that existing columns in for example the 'group/groups' table remain (name, description, enrolmentkey... timemodified).

1. Rename table: groups TO group,
   • Add column/key: groupingid, int(10).
2. Rename table: groups_courses_groupings TO course_groupings.
3. Rename table: groups_members TO group_members,
   • Add column: syncroleid, for enrolment synchronisation.
4. Rename table: groups_groupings TO grouping,
   • Add column: globalgrouping, flag int(1),
   • uniqueid ?
   • defaultsyncroleid ?
   • manualsync ?
5. Delete table: groups_courses_groups.
6. Delete table: groups_groupings_groups.
7. Modify table: course,
   • Add column: groupingid, int(10) - why, there's already a globalgrouping flag?
8. Modify table: course_modules,
   • Add column: groupingid, int(10) - as the OU and ecastro propose,

groups_groupings

This table describes a grouping, or collection of groups.

Field	Type	Default	Info
id	int(10)		autoincrementing
name	varchar(255)		Short grouping name
description	text	NULL
timecreated	int(10)	0	The time this grouping was first created
viewowngroup	int(1)	1	Unused permission flag - DEL?
viewallgroupsmembers	int(1)	0	Unused permission flag - DEL?
viewallgroupsactivities	int(1)	0	Unused permission flag - DEL?
teachersgroupmark	int(1)	0	Unused permission flag - DEL?
teachersgroupview	int(1)	0	Unused permission flag - DEL?
teachersoverride	int(1)	0	Unused permission flag - DEL?
teacherdeletable	int(1)	0	Unused permission flag - DEL?

groups

A pre-Moodle 1.8 table with some 1.8 changes, represents a group.

Field	Type	Default	Info
id	int(10)		autoincrementing
name	varchar(255)	' '	Short group name, unique to course (or site for site-wide group).
description	text	NULL
enrolmentkey	varchar(50)	Was mis-named/mis-used 'password' pre-Moodle 1.8.
lang	varchar(30)	en	Override course/site language for this group.
theme	varchar(50)		Override course/site theme for this group.
picture	int(10)	0	Flag to indicate presence of picture, should be int(1) ?
hidepicture	int(1)	0	Flag to show/hide group picture.
timecreated	int(10)	0	The time this group was first created.
timemodified	int(10)	0	Time of last modification.

groups_members

A pre-Moodle 1.8 table, connects a user to a group.

Field	Type	Default	Info
id	int(10)		autoincrementing
groupid	int(10)	0	Foreign key (table: groups)
userid	int(10)	0	Foreign key (table: user)
timeadded	int(10)	0	The time this user was first added to a group.

groups_courses_groups

Connects a group to a course (redundant if all groups are in a grouping).

Field	Type	Default	Info
id	int(10)		autoincrementing
courseid	int(10)	0	Foreign key (table: course)
groupid	int(10)	0	Foreign key (table: groups)

groups_courses_groupings

Connects a group to a course.

Field	Type	Default	Info
id	int(10)		autoincrementing
courseid	int(10)	0	Foreign key (table: course)
groupingid	int(10)	0	Foreign key (table: groups_groupings)

groups_groupings_groups

Connects a group to a grouping.

Field	Type	Default	Info
id	int(10)		autoincrementing
groupingid	int(10)	0	Foreign key (table: groups_groupings)
groupid	int(10)	0	Foreign key (table: groups)
timeadded	int(10)	0	The time this group was first added to grouping

course_modules

Pre-Moodle 1.8 table, OU additional column.

Field	Type	Default	Info
id	int(10)		autoincrementing
course	int(10)	0	Course ID, index (table: course)
...
groupmode	int(4)	0
groupingid	int(10)	0	OU-only, should be foreign key/index (table: groups_groupings)

Core group/grouping files, functions, constants

Folder: group

Mostly user-interface, except lib.php, version.php

• assign.php - add/remove group members.
• edit_form.php - formslib file.
• edit.php - create/edit groups.
• grouping_edit_form.php - formslib file.
• grouping.php
• index.php
• lib.php - includes group/lib/* files
• printgrouping.php
• version.php - Moodle component version.

Folder: group/db

db/dbbasicgrouplib.php MV:

• groups_db_get_user, groups_db_get_groups, groups_db_get_members, groups_get_member_users, groups_db_get_groups_for_user, groups_db_get_group_settings,
• groups_db_users_in_common_group, groups_db_group_exists, groups_db_group_matches, groups_db_group_name_exists, groups_db_is_member, groups_db_group_belongs_to_course,
• groups_db_create_group, groups_db_upgrade_group, groups_db_add_member, groups_db_set_group_settings, groups_db_remove_member, groups_db_delete_group, groups_db_set_group_modified,
• groups_members_from_sql, groups_members_join_sql, groups_members_where_sql,

db/dbcleanup.php DEL:

• groups_remove_user_from_all_groups, groups_remove_all_group_members, groups_remove_all_groups, groups_cleanup_groups,

db/dbcourselib.php DEL:

• groups_db_get_forced_grouping, groups__db_set_forced_grouping,

db/dbgroupinglib.php MV:

• groups_db_get_groupings, groups_db_get_groups_in_grouping, groups_db_get_groupings_for_group, groups_db_get_grouping_settings, groups_db_get_grouping_for_coursemodule,
• groups_db_grouping_exists, groups_db_belongs_to_any_grouping, groups_db_belongs_to_grouping, groups_db_is_member_of_some_group_in_grouping, groups_db_grouping_belongs_to_course,
• groups_db_create_grouping, groups_db_add_group_to_grouping, groups_db_set_grouping_settings, groups_db_set_grouping_for_coursemodule, groups_db_remove_group_from_grouping, groups_db_delete_grouping,

db/dbmodulelib.php DEL/ MV:

• groups___db_m_get_groupingid, groups_db_m_set_groupingid, groups_db_m_get_group,

db/dbsetup.php DEL:

• groups_create_database_tables, groups_db_copy_moodle_group_to_imsgroup,

db/install.xml (XMLDB database schema)

db/upgrade.php:

• install_group_db, undo_groupings, upgrade_group_db, groups_transfer_db, groups_drop_keys_indexes_db, groups_revert_db, xmldb_group_upgrade,

Folder: group/lib

lib/automaticgroupinglib.php DEL:

• groups_seed_random_number_generator, groups_create_automatic_grouping, groups_distribute_in_random_sets, groups_random_list, groups_last_element_in_set,

lib/basicgrouplib.php:

• groups_get_groups, groups_get_members, groups_get_member_records, groups_get_groups_for_user, groups_get_all_groups_for_user, groups_get_groups_for_current_user,
• groups_get_group_settings, groups_get_group_image_path, groups_get_group_name, groups_get_users_not_in_group,
• groups_users_in_common_group, groups_group_exists, groups_group_matches, groups_group_name_exists, groups_is_member, groups_group_belongs_to_course, groups_is_member_of_group_in_course, groups_set_default_group_settings,
• groups_create_group, groups_restore_group, groups_set_group_settings, groups_add_member, groups_restore_member, groups_delete_group, groups_remove_member, groups_remove_all_members, groups_update_group,

lib/clientlib.js (Javascript):

• function UpdatableGroupsCombo(..), success: function(o), failure: function(o), UpdatableGroupsCombo.prototype.refreshGroups = function(..)
• function UpdatableMembersCombo(..), success: function(o), failure: function(o), UpdatableMembersCombo.prototype.refreshMembers = function(..)
• var createLoaderImg = function(..), var removeLoaderImgs = function(..)

lib/courselib.php DEL:

• groups_get_forced_grouping, groups_set_forced_grouping, groups_course_print_group_selector,

lib/groupinglib.php:

• Constants/ defines: GROUP_NOT_IN_GROUPING, GROUP_ANY_GROUPING.
• groups_get_groupings, groups_get_grouping_records, groups_get_groups_in_grouping, groups_get_groups_in_grouping_records, groups_get_groupings_for_group,
• groups_get_grouping_settings, groups_set_grouping_settings, groups_get_grouping_name, groups_get_groups_for_user_in_grouping,
• groups_get_groups_not_in_grouping, groups_get_groups_not_in_any_grouping, groups_get_users_not_in_any_group_in_grouping,
• groups_user_is_in_multiple_groups, groups_set_default_grouping_settings, groups_get_grouping_for_coursemodule,
• groups_grouping_exists, groups_grouping_matches, groups_belongs_to_grouping, groups_is_member_of_some_group_in_grouping, groups_grouping_belongs_to_course,
• groups_create_grouping, groups_add_group_to_grouping, groups_set_grouping_for_coursemodule, groups_update_grouping, groups_remove_group_from_grouping, groups_delete_grouping, groups_delete_all_groupings,

lib/legacylib.php:

• groups_get_group_by_name, get_groups, user_group, ismember, get_group_users, add_user_to_group, mygroupid, groupmode,
• set_current_group, get_current_group, get_and_set_current_group, setup_and_print_groups,
• D oldgroups_print_user_group_info, groups_get_group, groups_get_groups_names, groups_get_groups_users,
• OU ou_is_old_group_dataload, ou_is_auto_group, ou_auto_groups_visible, ou_remove_auto_groups, ou_user_remove_auto_groups.

lib/modulelib.php:

• D groups_m_uses_groups, groups_m_print_group_selector,
• groups_m_get_selected_group, groups_m_get_groups_for_user, groups_m_get_my_group,
• D groups_m_has_permission, groups_m_get_members_with_permission,
• groups_m_get_group, groups_m_get_groups, groups_m_get_members, groups_m_get_and_set_current, groups_m_get_current, groups_m_setup_and_print,

lib/utillib.php:

• groups_count_group_members, groups_count_groups_in_grouping,
• groups_get_user_displayname, groups_get_group_displayname, groups_get_grouping_displayname,
• (D) groups_users_to_userids, groups_userids_to_user_names, groups_groups_to_groupids, groups_groupids_to_groups, groups_groupids_to_group_names,
• groups_compare_name, D groups_groupingids_to_groupings, groups_get_user, groups_get_course_info, groups_get_course,
• groups_group_edit_url, groups_grouping_edit_url, groups_members_add_url, groups_home_url, groups_param_action,

Folder: group/simpletest

simpletest/test_basicgrouplib.php:

• __construct, test_get_user, test_get_course_info, test_create_group, test_group_matches, test_add_member, test_remove_member, test_delete_group.

simpletest/test_groupinglib.php:

• __construct, __destruct, setUp, tearDown, test_create_grouping, test_groups_grouping_matches, test_add_group_to_grouping, test_remove_group_from_grouping, test_delete_grouping.

Others

backup/backuplib.php:

• backup_groups_info, backup_groups_members_info, backup_groupings_info, backup_groupids_info.

backup/restorelib.php:

• backup_ids table reference: "groups".
• restore_read_xml_groups, restore_read_xml_groupings,
• restore_create_groups, restore_create_groups_members, restore_create_groupings, restore_create_groupings_groups.

lib/moodlelib.php

• MV Constants/ defines: NOGROUPS, SEPARATEGROUPS, VISIBLEGROUPS.

lib/weblib.php

• print_group_picture, update_group_button, update_groups_button, print_group_menu

Groupings for course modules

These are currently only in ou-moodle. We now have grouping support in these course modules: data, forum, quiz (reports), wiki. For brevity, only mod/data is shown below. (There may be ommissions!)

course/lib.php:

• function set_coursemodule_grouping.

course/moodleform_mod.php:

• function standard_coursemodule_elements($supportsgroups=true, $supportsgroupings=false)

lib/db/install.xml

• <TABLE NAME="course_modules" ...>
• ... <FIELD NAME="groupingid" TYPE="int" LENGTH="10" NOTNULL="true" ...DEFAULT="0" ...PREVIOUS="groupmode"/> ...

lib/db/upgrade.php

• ... $table = new XMLDBTable('course_modules');
• $field = new XMLDBField('groupingid');
• ... add_field($table, $field); ...

lib/form/modgrouping.php:

• class MoodleQuickForm_modgrouping extends MoodleQuickForm_select.

lib/formslib.php:

• ... MoodleQuickForm::registerElementType('modgrouping' ...)

mod/data/mod_form.php

• $this->standard_coursemodule_elements(true, true);

... mod/data/view.php

• groups_m_setup_and_print($cm ...); ...

Future requirements

Objectives

1. Improve the confidence of Martin D, Petr Skodak and the community in groups.
2. Maintain backwards compatibility with 1.8 and 1.8.1 - so no significant removal of high-level functionality (in time we want groupings, site-wide groups etc - these are additions).
3. Make upgrade, backup and restore (from 1.8, 1.7, 1.6 etc.) more robust.
4. Make database access more efficient - fewer queries per page.
5. Simplification of database schema - but not at the expense of future-proofing and flexibility.
6. Simplification of group libraries, so code is easier to maintain and use.
7. Simplification/ improvement to group management user interface - "Not in a grouping" (NIAG)/ orphaned groups will go!
8. Add groupings support for course modules - already in ou-moodle.
9. Investigate synchronisation with enrollments, and fix group import.
10. Minimise differences between core Moodle and ou-moodle.

Proposed tasks

(Order to be discussed.)

1. Create additional (simpletest) unit tests - how many do we have time for? To ensure that subsequent steps don't break things!
2. Delete unused/ unfinished code, functions and files from the libraries (see DEL above). [Simplify]
3. Merge some library fixes and module-grouping specific code from OU to core Moodle. [OU diff]
4. Move code from db/db*lib.php files to lib/*lib.php files - so groups_db_create_group etc. will go, just leaving groups_create_group. General refactor of code and PHP doc-comments. [Simplify]
5. Rewrite groups_get_groups functions etc. so that they return arrays of group objects (group ID used as key), not groupids. Delete inefficient groups_groupids_to_groups etc. [Efficiency]
6. New upgrade, creating default grouping for a course - NIAG will go/ DB schema changes (stabilisation).
7. (OU-specific: modify group dataload.)

...

Proposed process

• Discuss/ modify this specification until a concensus is reached.
• One meta/tracking-bug, and a 'sub-task' bug per task above.
• One or more patches per task, to be reviewed by Martin D and/or Petr Skodak and others, committed by Martin, Petr, NDF or other.
• Modifications on core Moodle HEAD.

See also

• Enrique Castro group specification.
• Petr Skodak group specification.