MoodleDocs - User contributions [en]

Development:How groups work in Moodle

2006-10-24T15:06:36Z

Jvvw:

'''IMPORTANT:''' This documentation does not refer to current (1.6/1.7) versions of Moodle
and is here at the moment purely in order to obtain comments. Descriptions of
how groups work refer to how they hopefully work not how they will work now! This document is also written in the present tense even though it doesn't refer to the current version of Moodle. This is so I don't have to go through and change it all in a month or two's time.

=== How groups work in Moodle ===

It is possible to have groups of users in Moodle. A person with the right
permissions (generally an editting teacher or admin) can create groups for a course and add and remove users from groups. They can also create sets of groups for the course which we'll refer to as 'groupings'. Groups that belong to the course can be added to and removed from any of the groupings that have been created for the course.

If you haven't seen the interface for creating groupings and groups, I'd
recommend you go to a course in your installation of Moodle for which you have
edit access and which has some participants and follow the Groups link and take
a look (''note: you can't currently do this obviously as the code isn't released
yet!'').

=== An example ===

* Your course has five students: Alice, Bob, Charlie, David and Eve.
* You create two groupings - 'Grouping 1' and 'Grouping 2'. You create three groups for Grouping 1 called Group X, Group Y and Group Z and you create two groups in Grouping 2 called 'English student' and 'Scottish students'.
* You put Alice and Bob in Group X, Charlie and David in Group Y and Eve in Group Z.
* You put Alice and Charlie in 'English students' and Bob and Eve in 'Scottish students' (David is Welsh so we don't put him a group at all).
* You now create a wiki and a forum. You assign Grouping 1 to the wiki and Grouping 2 to the forum.
* The wiki now uses the groups Group X, Group Y and Group Z. The forum now uses the groups X, Y and Z. As David isn't in any of the groups for Grouping 2, he doesn't even see that the forum exists.

=== More details ===

Once there is at least one grouping created for a course, when an editor adds an
activity (i.e. an instance of a module) to a course they may if they wish assign one of the groupings for the
course to use with that instance of the module. A user who is not in a group for
a grouping assigned will not be able to see that the instance of the module
exists. It is also possible for the editor to specify a grouping to use for
everything for the course - this is set up in the course settings.

Each group and grouping must 'belong' to at least one course (it's possible for them to belong to more than one course, but there's no user interface to let you do this easily at the moment). Both teachers and students can belong to groups and a user can belong to more than one group. It is also possible for a group to belong to more than one grouping and for a user to belong to more than one group in a grouping.

There is a choice of various permission settings for a grouping - for instance
you can specify that students may both view and contribute to the group of which
they are a member but only view groups of which they are not members. In time
these settings wil hopefully be superceded by an extension of the roles and
permission system used elsewhere in Moodle, but at the moment they are
independent. The main types of permission that a user can have for a
particular group are 'student view', 'student contribute', 'teacher view' and
'teacher contribute', with it being up to modules to decide how to interpret
these. As we have seen, a user does not need to be a member of a group to have a
particular permission type for that group.

=== How does this differ from the way groups previously worked? ===

* Previously it was only possible to have one set of groups for a course. All activities for a course had to use the same set of groups, whereas now you can use different sets of groups for different activities.
* Previously, for a course with groups, there were two groups modes - separate and visible. With separate groups, students
could not see groups to which they did not belong, whereas with visible groups they could see groups to which they did not belong but not contribute to them. This caused a great deal of confusion when it came to teachers belonging to groups (and also
led to lots of really horrible logic in the code).
* You can now create groups automatically with a certain number of students per group randomly assigned, or with students distributed into a certain number of groups.
* If a student is not in a group for the grouping assigned for an activity, they will not be able to see that activity.
* The infrastructure supporting groups has been improved considerably so that it will make it much easier to make changes to groups in future as well as to module code. For instance, the changes to support global groups should now be fairly simple. If somebody wants to integrate groups with the roles and permissions system in some way this should also be much easier than it previously would have been.

=== Future plans? (Things I'd like to do or you can do for me!) ===

In no particular order:

* Bug fixing I guess :-)
* Global groups - I want it to be possible to set up groupings for course 1 and for these to be visible for all course on the site, but not editable or deletable. I think this code should actually be quite easy to write now and I might even do it before this code is put in, just haven't done it yet.
* A nicer user interface (that doesn't break the back button :-) Ajax separates the back and front end of the code really well, so if anyone has good ideas on this, it should be quite easy for someone else to do without having to know how the internals of the groups code work.
* Integration with roles and permissions
* Sign up sheets for groups
* Proper support for blocks and global features.
* A way for modules and blocks to declare whether they support groups or not.
* Putting in search_users functionality for group permissions as well as just members of groups.
* Cool ways to set up groups automatically for particular pedagogical reasons - things like minimising overlap with groups in another grouping, creating groups just from the users all in another group and creating groups which merge pairs of groups from another grouping.
* Allow settings for groupings which restrict users from being in more than one group, number of people per group, etc.

[[Category:Groups]]

Development:Setting up Eclipse

2006-09-25T15:17:36Z

Jvvw: /* Installing the necessary plugins */

[http://www.eclipse.org/ Eclipse] is an IDE originally designed for Java, but now with plugins for many languages including PHP. It has lots of very powerful features, and it is the editor that someMoodle developers like to use. Other (more) popular choices are vim and emacs.

However, Eclipse is not the easiest program in the world to get started with, so I'm going to take you through it step by step. These instructions assume Eclipse 3.2, the current version at the time of writing. It should not change much between releases.

;Warning
:This is just a brain-dump, and since I already have Eclipse installed on all my computers I have not been able to test all the the steps. I would be very grateful if some people could try these instructions and make the necessary corrections.[[User:Tim Hunt|Tim Hunt]] 21:32, 12 August 2006 (WST)

==Prerequisites==

Eclipse is written in Java, so I recommend getting the latest Java runtime environment from http://java.com/ for maximum speed and reliability.

Eclipse is quite big, so I recommend lots of memory in your computer. I have used it on Windows, MacOS X and Linux with 1GB, in each case with 1GB of memory, and that is plenty.

==Installing Eclipse==

Go to http://www.eclipse.org/downloads/. Click on the link where it says '''Download now: Eclipse SDK 3.2''' It should have automatically detected which platform you are using. Choose a Mirror, and wait for the ~100MB download.

You will notice that what you have got is a zip file (unless your system automatically decompresses it for you).

On Windows, upzip it into '''C:\Program Files''' (all the files go into an '''Eclipse''' folder there). Then look in the Eclipse folder and drag Eclipse.exe to the Start menu/Desktop/Quicklaunch bar to make a shortcut for starting it.

On MacOS, unzip and copy the Eclipse folder into Applications. Go into the Eclipse folder and drag the Eclipse app to the Dock for ease of launching.

On Linux, unzip somewhere suitable, and make an easy way to launch it.

==The first time you run Eclipse==

The first time you lauch Eclipse it does a bit of setup stuff, for instance, it create a '''workspace'''. This is where it stores the things you are working on. The default location is sensible on all platforms, so use that.

For some reason, every time you start Eclipse, it asks you which workspace you want to use. I have never seen the need to have more than one, so I recommend turning on the checkbox that says "Don't ask me this again".

Another thing that happens the first time you run Eclipse is that you arrive at a welcome screen. This has links to various bits of help, which you can read if you like, but you probaly don't need to if you are following these instructions. So find the button on the welcome page that closes it and gets you to the main Eclipse screen.

==Installing the necessary plugins==

By default, Eclipse comes with the Java tools. For everything else you will need to install some plugins.

If you are sitting behind a web proxy, from the '''Window''' menu choose '''Preferences ...'''. Choose '''Install/Update''' from the tree view on the left, and enter the proxy information in the boxes on the right. If you aren't behind a proxy, ignore this step.

From the '''Help''' menu choose '''Software Updates -> Find and Install'''.

On the first screen of the wizard, make sure that "Search for new features to install" is selected, then click '''Next >'''.

The next screen is a list of upgrade sites to check. You need to add one to the list, so click the '''New Remote Site ...''' Button.

In the pop-up dialog, give the remote site a name like '''PHPeclipse Update Site'''; set the URL to http://phpeclipse.sourceforge.net/update/releases/; then click '''OK'''.

Back in the wizard, turn on just two things in the box "Sites to include in search":
* Your newly created '''Phpeclipse Update Site'''; and
* the one called '''Callisto Discovery Site'''.
Then click '''Finish'''.

It goes off sees what updates are available at those sites. As it does so, it may occasionally pop up a dialog asking you to choose a mirror. Each time, select a sensible one.

Eventually, you get to a new wizard for selecting and installing the updates you want. The ones you want (you may have to search the tree structure) are, '''PHPeclipse''' (from your newly created PHPEclipse Update Site) and all the '''Web Standard Tools (WST)''' (usually under Callisto Discovery Site --> Web and J2EE Development).

Next, and very importantly, you must click the '''Select Required''' button. Then you can click the '''Next >''' button.

Read and agree to all the license agreements. Then click '''Next >'''.

Click '''Finish''', and wait for the plugins to download.

Once the downloads have finished, a warning will pop-up telling you that all the plugins you downloaded are not digitally signed. The Eclipse Foundation build digital signing of plugins into their architecture as a security measure, and then did not sign any of their own plugins! Anyway, click the '''Install All''' button.

Finally, a window will pop up asking you to restart Eclipse. Do so.

==Setting the preferences for Moodle development==

Now go to the '''Window''' menu, and choose '''Preferences ...'''.

The Eclipse preferences are immense, with a tree view on the left, which selects which screen to display on the right. Don't panic, we'll guide you through it.

===General settings===

If you have strong feelings about fonts, choose '''General -> Appearance -> Colors and Fonts''' from the tree on the left. Then on the right look under '''Basic''' and change '''Text Font'''. All the other editor font settings will inherit from this, so this is probably the only one you have to change.

Under '''General -> Content Types''', select PHP Source File, and add '''*.html''' to the box at the bottom.

Under '''General -> Editors -> File Associations''', add '''*.php''' to the top box. With '''*.php''' selected in the top box, make sure '''PHP Editor''' is set to default in the bottom box. With '''*.html''' selected in the top box, select '''PHP Editor''' in the bottom box and click the '''Default''' button to change it, because in Moodle, most HTML files actually contain PHP code.

If you use a web proxy, enter the details under '''Internet -> Proxy Settings'''. (Yes, I know you have entered the somewhere else before. Now you have to enter them again here. I don't know why. You just do.)

===PHP Settings===

These are all hidden under the '''PHPeclipse Web Development''' bit of the tree.

Under '''PHPeclipse Web Development -> Browser Preview Defaults''', turn off both checkboxes.

Under '''PHPeclipse Web Development -> PHP''', on the '''Appearance''' tab, set '''Displayed tab width''' to 4.

Under '''PHPeclipse Web Development -> PHP''', on the '''Typing''' tab, turn off all the options except '''Pasting for correct indentation''', '''Insert spaces for tab''' and '''Close PHPdocs and comments''' and '''Remove trailing spaces on editor save'''. It would be nice to turn on more of these options, but most of the rest don't work very well.

Under '''PHPeclipse Web Development -> PHP -> Formatter''', on the '''New Lines''' tab, turn on '''Clear all blank lines'''.

Under '''PHPeclipse Web Development -> PHP -> Formatter''', on the '''Style''' tab, turn off '''Indentation is represented by a tab'''.

Under '''PHPeclipse Web Development -> PHP -> Templates''', I like to define a new template to help with debugging:
;Name
:dump
;Description
:Dump a PHP variable
;Pattern
<pre>echo '<pre>'; //DONOTCOMMIT
print_r(${cursor});
echo '</pre>';</pre>
You can do other useful things with templates too.

There is a really stupid bug. Under '''PHPeclipse Web Development -> Project Defaults''', you would like to add "." to the '''Include Paths''', but you can't using the GUI. You will have to edit one of the Eclipse config files by hand. So
# Note down the path to your Eclipse profile. On Windows it will be something like '''C:/Documents and settings/XXXX/workspace''', and on Unixy systems something like '''~/workspace'''.
# Close Eclipse.
# Open the file '''net.sourceforge.phpeclipse.ui.prefs''' that is in the directory '''(your workspace)/.metadata/.plugins/org.eclipse.core.runtime/.settings''' in a text editor.
# Look for a line in the file that starts '''_php_include_paths=''' If it is not there, add it at the end.
# Change this line to say '''_php_include_paths=.'''
# Run Eclipse again.

===CVS Settings===

These are all hidden under the '''Team''' bit of the tree.

Under '''Team -> CVS -> SSH2 Connection Method''', you can set up a public/private key pair. If you do this, you won't have to keep typing your Sourceforge password when doing CVS operations. See http://sourceforge.net/docs/F02/ for the instructions of what you have to do at the Sourceforge end to make this work. That should make it clear what you have to do in Eclipse.

The rest of the ones in this section are personal preferences, but I recomment them because the default settings are very irritating.

Under '''Team''', set '''Perspectives''' to '''None'''.

Under '''Team -> CVS -> Annotate''' set '''Use Quick Diff annotate mode for local file annotations''' to '''Yes''', and '''Open perspective after a 'Show Annotations' operation''' to '''No'''.

Under '''Team -> CVS -> Label Decorations''', switch to the '''Icon Decorations''' tab and turn on all the settings, and then on the '''Text Decorations''' tab change both '''File Decoration''' and '''Folder Decoration''' to be just '''{name}'''.

===Web and XML settings===

Foreach XXX in CSS, HTML, Javascript, XML:

Under '''Web and XML -> XXX Files ->XXX Source''', choose '''Indent using spaces''' and '''indentation size''' 4.

==Checking out the Moodle code==

From the '''File''' menu, choose '''New -> Project ...''', then click '''Next >'''.

In the wizard that pops up, choose '''CVS -> Projects from CVS''', then click '''Next >'''.

Select '''Create a new repository location''', then click '''Next >'''.

Fill in
<div style="float: right; border: 1px solid orange; padding: 0 1em;">
For anonymous CVS access use
;Host
:moodle.cvs.sourceforge.net
;Repository path
:/cvsroot/moodle
;User
:anonymous
;Password
:(leave blank)
;Connection type
:pserver
</div>
;Host
:moodle.cvs.sourceforge.net
;Repository path
:/cvsroot/moodle
;User
:(your sourceforge username)
;Password
:(if you set up the SSH2 key thing in preferences, leave this blank, otherwise, type in your sourceforge password.)
;Connection type
:extssh
(CVS experts, if you are confused by that last one, know it is an Eclipse-specific thing.) Then click '''Next >'''.

On the next screen of the Wizard, choose '''Use an existing module'''. Wait a moment, then select '''moodle''' from the list. Click '''Next >'''.

On the next screen, make sure the option '''Check out as a project configured using the New Project Wizard''' is selected, then click '''Next >'''.

Click '''Refresh Tags''', then choose the branch you want. For now leave it set to '''HEAD'''.

Click '''Finish'''.

Now you will find yourself back at the start of the '''New Project''' Wizard. This is because of the option you chose three paragraphs ago. This time you should select '''PHP -> PHP Project''', then click '''Next >'''.

Make up a project name. '''moodle''' would be sensible.

Click '''Finish''', and wait while all the moodle files are checked out of CVS.

Once it has finished, it will probably ask you if you want to switch to the PHP perspective. Answer '''Yes'''.

If you also need the 1.6 stable branch, or another branch, repeat all the other steps with a few changes:
* This time you can choose '''Use and existing repository location''' instead of typing all the sourceforge CVS details again.
* Select the appropriate branch.
* Use a different project name.

==Let your development web server know where your files are==

Either by editing you web server's config files, or using a symbolic link. Make sure your webserver can see your new working set of files at a sensible URL, so you can test the code you are working on.

==Quick tour of some cool features, and remaining configuration changes==

I find the default workbench setup is pretty good. Here is a quick guide to some of the bits.

===Navigator===

To the left is the '''Navigator'''. This is a tree view of all your files. If you double-click on a file, it opens in the editor in the middle. Try opening '''course/lib.php''' now. You will notice that it comes up nicely syntax-hightlighted.

===Error highlighting===

In the middle of the file, just type any old text, for example "I like Eclipse". Obviously, this is not valid PHP syntax, and Eclipse will notice this, and put a red underline under it. Also, by the scrollbar is a ruler with a red mark in it to show the error.

You will see some yellow marks lower down the ruler. There are warnings. Click on one, and you will be taked to where that warning is in the file. Hover your mouse over the warning, and you will get a tooltip explaining what the problem might be.

Save the edited file. (Don't worry that it is broken, we'll clean up the mess later.) Notice that a red error marker is added to the file in the navigator, so you can see that there is a problem. Also, error markers are added to the course folder, and the whole project, so you could see there was an error even if the navigator tree was collapsed.

You will probably find lots of warnings that the config.php file can't be found. In the navigator, find the file '''config-dist.php'''. Do '''Copy''' then '''Paste''' and choose to call the new file '''config.php'''. Edit this new config.php as normal. You should fine that most of the include file warnings have gone now.

Notice also that there is another marker on each file icon. A little yellow cylinder on most files, but a white-on-brown star on the one you have edited. This is telling you the CVS status of each file. The brown stars are changes you have made but not checked in yet.

===Outline===

Over to the right is the Outline view. This shows a list of functions and classes defined in this file. By default, they are listed in the same order as in the file, but if you click on the '''az''' toolbar button, they are sorted into alphabetical order.

Click on the function name '''add_course_module''' in the Outline. You will see that the editor scrolls to the definition of that function.

===Code navigation===

In that function, hover the mouse pointer over the function name '''insert_record'''. After a while, the documentation for that function will appear in a big tooltip.

Hold down CTRL, move the moust pointer over the function name '''insert_record''', then click. Eclipse should load datalib.php, and scroll you to where this function is defined.

In the main Eclipse toolbar, there are forward and back arrows like in a web browser. Click back now to get back to '''course/lib.php'''.

===Open resource===

From the '''Navigate''' menu, choose '''Open Resource...'''. In the dialog that pops up, start typing a filename for instance type '''moodlel'''. In the box in the middle of the dialog, you will see it list all the files in the project whose names start that way. At the bottom is a box which lists the different folders that contain a file with that name. This can be a very quick way of opening files with fairly unique names like moodlelib.php, without having to click through the levels of the navigator tree. Of course, it is not so useful for an index.php file! Click OK now to open moodlelib.php. (It would actually work if you just did CTRL + Shift + R, moodlel, Enter.)

===Multi-file search===

Scroll down moodlelib a little bit, and double click on the name of the constant '''MOODLE_INTERNAL''' where it is defined, so that the text is selected. Then, from the '''Search''' menu, choose '''Search...'''. Notice that the '''Containing text''' box has already been filled in for you with the text you just selected. Of course you can just type text into this box without selecting it first. Notice that you can do regular expression searches, but leave that turned off for now. In the '''File name patterns''' box type '''*.css, *.html, *.inc, *.js, *.php, *.xml'''. (This is the most useful general setting for working on moodle. Eclipse will remember this setting, so you only have to enter it once.) Click '''Search'''.

The search results will appear in a new view underneath the editor. That view has a toolbar with yellow up and down arrows. Click the down arrow a few times and it will take you to the first few matches in the code, opening the relevant files as necessary.

===Synchronize view===

I think this is my favorite feature. From the '''Window''' menu, select '''Show View -> Other...'''. In the dialog that pops up, select '''Team -> Synchronize''', then click '''OK'''.

This opens the Synchronize view below the editor. The view has a toolbar. Click on the first toolbar button, which pops up the Synchronize wizard.

On the first screen, there will probably only be one option: '''CVS'''. Make sure that is selected, then click '''Next >'''.

Under '''Scope''', choose '''Workspace''', then click '''Finish'''.

Wait while it talks to the CVS server. After a while, you will see that the Synchronize view lists course/lib.php, and something called '''.project.... That is, it is listing just the files you have edited, but not checked in yet.

'''.project''' is something that belongs to Eclipse that we don't care about. So select it and bring up the context menu, and choose '''Add to .cvsignore...'''. In the dialog that pops up, choose the top option, then click '''OK'''. Then you will find the Synchronize view shows you a '''.cvsignore''' file that you aren't interested in, so add that to .cvsignore too!

If you double-click on '''course/lib.php''' here, you will see that it opens the compare editor, which is a nice graphical display of the changes in this file.

If you select a file or files here, then bring up the context menu, you will see the option to '''Commit...''' the changes. (But don't do that now!). This is the easiest way to commit things in Eclipse.

However, our changes were rubbish, so we want to undo them. So open the context menu again, and choose '''Override and Update'''. This checks a clean copy of the file out of CVS, removing our changes.

Note that the easiest way to do an ordinary CVS Update is to select the top-level project-folder in the Navigator view on the left, open the context menu, and choose '''Team -> Update'''.

That's all the really important features. I sure you can learn everything else on your own. An you could always read the built in help!

[[Category:Developer]]

Development:How groups work in Moodle

2006-08-23T20:52:15Z

Jvvw: /* Future plans? (Things I'd like to do or you can do for me!) */

'''IMPORTANT:''' This documentation does not refer to current versions of Moodle
and is here at the moment purely in order to obtain comments. Descriptions of
how groups work refer to how they hopefully work not how they will work now! This document is also written in the present tense even though it doesn't refer to the current version of Moodle. This is so I don't have to go through and change it all in a month or two's time.

=== How groups work in Moodle ===

It is possible to have groups of users in Moodle. A person with the right
permissions (generally an editting teacher or admin) can create groups for a course and add and remove users from groups. They can also create sets of groups for the course which we'll refer to as 'groupings'. Groups that belong to the course can be added to and removed from any of the groupings that have been created for the course.

If you haven't seen the interface for creating groupings and groups, I'd
recommend you go to a course in your installation of Moodle for which you have
edit access and which has some participants and follow the Groups link and take
a look (''note: you can't currently do this obviously as the code isn't released
yet!'').

=== An example ===

* Your course has five students: Alice, Bob, Charlie, David and Eve.
* You create two groupings - 'Grouping 1' and 'Grouping 2'. You create three groups for Grouping 1 called Group X, Group Y and Group Z and you create two groups in Grouping 2 called 'English student' and 'Scottish students'.
* You put Alice and Bob in Group X, Charlie and David in Group Y and Eve in Group Z.
* You put Alice and Charlie in 'English students' and Bob and Eve in 'Scottish students' (David is Welsh so we don't put him a group at all).
* You now create a wiki and a forum. You assign Grouping 1 to the wiki and Grouping 2 to the forum.
* The wiki now uses the groups Group X, Group Y and Group Z. The forum now uses the groups X, Y and Z. As David isn't in any of the groups for Grouping 2, he doesn't even see that the forum exists.

=== More details ===

Once there is at least one grouping created for a course, when an editor adds an
activity (i.e. an instance of a module) to a course they may if they wish assign one of the groupings for the
course to use with that instance of the module. A user who is not in a group for
a grouping assigned will not be able to see that the instance of the module
exists. It is also possible for the editor to specify a grouping to use for
everything for the course - this is set up in the course settings.

Each group and grouping must 'belong' to at least one course (it's possible for them to belong to more than one course, but there's no user interface to let you do this easily at the moment). Both teachers and students can belong to groups and a user can belong to more than one group. It is also possible for a group to belong to more than one grouping and for a user to belong to more than one group in a grouping.

There is a choice of various permission settings for a grouping - for instance
you can specify that students may both view and contribute to the group of which
they are a member but only view groups of which they are not members. In time
these settings wil hopefully be superceded by an extension of the roles and
permission system used elsewhere in Moodle, but at the moment they are
independent. The main types of permission that a user can have for a
particular group are 'student view', 'student contribute', 'teacher view' and
'teacher contribute', with it being up to modules to decide how to interpret
these. As we have seen, a user does not need to be a member of a group to have a
particular permission type for that group.

=== How does this differ from the way groups previously worked? ===

* Previously it was only possible to have one set of groups for a course. All activities for a course had to use the same set of groups, whereas now you can use different sets of groups for different activities.
* Previously, for a course with groups, there were two groups modes - separate and visible. With separate groups, students
could not see groups to which they did not belong, whereas with visible groups they could see groups to which they did not belong but not contribute to them. This caused a great deal of confusion when it came to teachers belonging to groups (and also
led to lots of really horrible logic in the code).
* You can now create groups automatically with a certain number of students per group randomly assigned, or with students distributed into a certain number of groups.
* If a student is not in a group for the grouping assigned for an activity, they will not be able to see that activity.
* The infrastructure supporting groups has been improved considerably so that it will make it much easier to make changes to groups in future as well as to module code. For instance, the changes to support global groups should now be fairly simple. If somebody wants to integrate groups with the roles and permissions system in some way this should also be much easier than it previously would have been.

=== Future plans? (Things I'd like to do or you can do for me!) ===

In no particular order:

* Bug fixing I guess :-)
* Global groups - I want it to be possible to set up groupings for course 1 and for these to be visible for all course on the site, but not editable or deletable. I think this code should actually be quite easy to write now and I might even do it before this code is put in, just haven't done it yet.
* A nicer user interface (that doesn't break the back button :-) Ajax separates the back and front end of the code really well, so if anyone has good ideas on this, it should be quite easy for someone else to do without having to know how the internals of the groups code work.
* Integration with roles and permissions
* Sign up sheets for groups
* Proper support for blocks and global features.
* A way for modules and blocks to declare whether they support groups or not.
* Putting in search_users functionality for group permissions as well as just members of groups.
* Cool ways to set up groups automatically for particular pedagogical reasons - things like minimising overlap with groups in another grouping, creating groups just from the users all in another group and creating groups which merge pairs of groups from another grouping.
* Allow settings for groupings which restrict users from being in more than one group, number of people per group, etc.

[[Category:Groups]]

Development:Groups documentation for module developers

2006-08-23T20:46:52Z

Jvvw: /* Support for legacy code */

== Groups in Moodle for developers==

'''IMPORTANT:''' This documentation does not refer to current versions of Moodle
and is here at the moment purely in order to obtain comments. Descriptions of
how groups work refer to how they hopefully work not how they will work now! This document is also written in the present tense even though it doesn't refer to the current version of Moodle. This is so I don't have to go through and change it all in a month or two's time.

=== How groups work in Moodle ===

There is a separate document on [[How groups work in Moodle]] which is worth reading for background especially if you are new to groups in Moodle, although most of the details aren't relevant for module developers. From a module developer's point of view, the differences aren't actually too big. The main changes is that there may be a different set of groups being used for each instance of you module in the course and that separate/visible groups have been replaced by a better system of permissions. The other big changes are all being handled by code elsewhere. There have also been some changes to the database structure for groups (for instance there is now a separate course_group table rather than courseid being a column in the groups table which may affect your code if it has been accessing the database directly for some reason).

As well as modules, there are also some blocks and global features such as blogs
and the calendar that use groups in certain ways. We'll come to those later.

It is obviously good if modules support groups in the ways that users expect!
This document is here to try and help you do that - if anything isn't clear, you
have questions or can think of improvements to how groups work in Moodle, please
post on the Groups forum on moodle.org.

=== How should modules support groups? ===

There are two main ways a module might need to support groups. There may of
course be other more unusual ways in which your module should supports groups,
but these should hopefully be the most common ones. The important thing
is to think about how people would expect your module to behave if they chose to
use groups for it.

==== From a student's point of view ====

From a student's point of view, groups are generally used as a way to enable
parallel versions of the same activity with different groups of students e.g you
might want a separate forum or wiki for each group. If your module is
collaborative in any way (which includes the ability to view the existence of
other students or their contributions) then you need to make sure that this is
supported.

As well as the obvious views of activities being separated, you will need to
make sure that things like searches return the correct results and that teachers
can view the correct groups. You may also need to make a decision as to which
teacher activity is part of the setup of the activity so is the same for every
group and needs to be performed only once, and which teacher activity is the
contribution after the activity has started and so is different for each group.

In general if you module needs to support groups in this way you will find that
the database table(s) where you store the students' contributions will probably
need an extra 'groupid' column, for instance the forum table has a groupid
column.

==== From a teacher's point of view ====

From a teacher's point of view, groups are generally used to manage different
groups of students. For instance there may be several teachers on a course each
assigned to one or more groups of students who mark the work for the groups of
students that have been assigned to them but shouldn't be able to mark the work
of the other groups. A single teacher may also want to be able to view marks for
students by group when they teach the same material to two different classes. In
general, if your module enables teachers to somehow view students' contribution,
then you need to provide this type of support. You can usually do this by
checking which students are in which group rather than needing to alter the
module's database tables in any way.

==== Dealing with users in more than one group ====

Although users may be belong to more than one group, most of the time you can
use the groups library for modules to deal with this rather than having to worry
about this yourself. There will be more about this in the next section. The time
you will probably find that you need to worry about this is when for instance
you are doing a search for contributions that a particular student is allowed to
view. In this case you will need to look for contributions for all the groups
rather than just one group.

=== The groups library for modules ===
The functions at your disposal can be found in course/groups/lib/modulelib.php -
go and have a quick look at it now. (''Again you can't yet, but look here at the [[Groups API for modules]] instead'') Here are some examples of common ways in which you might want to use
the functions in it. Note that modules don't actually need to know anything about groupings directly - the correspondence between an instance of a module and a grouping is taken care of by the library.

1) Present a user with a page containing the right information for one of the
groups that they belong to including a selector to see the equivalent page for
any other groups that they belong to. e.g. present a user with a list of
discussion for a group they belong to.

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_STUDENT_CONTRIBUTE;
groups_m_print_group_selector($cmid, $urlroot, $permissiontype);
$currentgroupid = groups_m_get_selected_group($cmid, $permissiontype);
// This is your function that you've written.
do_whizzy_module_stuff_for_group($cmid, $currentgroupid);
} else {
// Do whatever you'd normally do
}

2) Present a user with search results only for the groups that they are allowed
to view.

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_VIEW;
$groupids = groups_m_get_groups_for_user($cmid, $permissiontype);
// You might want the search funtion to check group permissions too to be
// on the safe side.
get_module_search_results_for_groups($groupids, $maybesomeotherparameters);
} else {
// Do whatever you'd normally do
}

3) Get a list of users which a teacher should be able to mark work

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_TEACHER_CONTRIBUTE;
groups_m_print_group_selector($cmid, $urlroot, $permissiontype);
$groupid = groups_m_get_selected_group($cmid, $permissiontype);
$userids = groups_m_get_members($groupid);
} else {
// Get your userids the normal way
}
// Do whatever you'd normally do with the userids.

It is still ok to use inner joins on the groups_members table in the database
for this type of functionality as obviously this is sometimes required for
performance reasons, but make sure you keep your code that queries the database
clearly separated from your other code.

=== Support for legacy code ===

The following functions should still be supported but are deprecated:

get_groups

user_group

ismember

get_group_users

get_group_students

get_group_teachers

add_user_to_group

mygroupid

groupmode

set_current_group

get_current_group

get_and_set_current_group

setup_and_print_groups

Where appropriate, if a grouping has been specified in the course setting for
use for all activities that grouping will be used in what was previously
'separate groups' mode. If no such grouping has been specified then the first
grouping created for the course that still exists will be used, again in
separate groups mode. If you want better support than this, then I'm afraid you
will need to update the code for your module!

Accessing the groups_members table directly should still work (although it is
not recommended unless you need to do an inner join on it for performance
reasons). Directly accessing the groups table may not work because the course
column has been removed.

The groupid argument in the function search_users from datalib.php will still
work, but will only give members of a group, not those with a specific
permission.

=== Blocks and other special cases ===

There is an essentially identical library for blocks as for modules, only all
the _m_'s in the function names are replaced by _b_'s.

At the moment there is no standard way to set the grouping for a block and most
blocks don't need to use groups. If you want to create a way for someone to set
up a grouping for your block then you will need to do this yourself using the
functions in the other parts of the groups library (under course/groups/lib/)
but ask if you need help. There is a new column in the block_instance table
called groupingid that you will need to set using the function
groups_set_grouping_for_block_instance. If a grouping is set for all activities
for a course then this will get automatically set however.

There are currently two 'global' features in the Moodle core - blogs and the
calendar - a quick word on those in case anyone has plug-ins that provide
similar global features.

Calendar - with the calendar a teacher can set group events when they are within
a course, so basically all they need to do is get all the groups for the course
that a teacher has a particular permission for. Then when displaying calendar
entries to users, need to know which groups a particular has view permission
for across all courses though it's a tiny bit more complicated that this because
a grouping can be used for more than one course and someone may be a student on
one course and a teacher on another.

Blog - It's possible for the admin to set a blog option that makes blogs view
access group level. This means that users can only see blogs of people that they
share a group with for some course - there's a function provided in one of the
main groups libraries to find out if two users share a group. I'm guessing that
you're mostly only wanting to use this with installations with a very small
number of teachers and at some point global groups will get used here instead.

At the moment there is generally no general support for global features, but
this will hopefully come!

== Some rationale ==

I'll probably add stuff in here as it comes up :-)

''' Why doesn't this fit in with roles and permissions? '''

Mostly at the time I started doing this development the roles and permission
code wasn't available yet! The changes to roles and permissions are big and the
changes needed to fit in with them properly need some thought and would be even
more massive than they currently are. It seemed better to get the main
improvements to groups in first and give the roles and permissions code a bit of
time to settle. It would be nice if they are integrated sensible eventually.

''' Why do I have to deal separately with the case where the module uses groups and the case where it doesn't? Isn't there a clever way to do this so I don't have to? '''

Yes, but I wanted to try and keep people's code fairly readable and make it as
easy as possible to shift current over. In practice you shouldn't really have
too much extra code this way anyhow - you can always write functions with a
groupid argument that defaults to false.

[[Category:Developer]]
[[Category:Groups]]

Development:How groups work in Moodle

2006-08-23T20:27:44Z

Jvvw:

Development:Groups documentation for module developers

2006-08-22T08:09:50Z

Jvvw:

== Groups in Moodle for developers==

'''IMPORTANT:''' This documentation does not refer to current versions of Moodle
and is here at the moment purely in order to obtain comments. Descriptions of
how groups work refer to how they hopefully work not how they will work now! This document is also written in the present tense even though it doesn't refer to the current version of Moodle. This is so I don't have to go through and change it all in a month or two's time.

=== How groups work in Moodle ===

There is a separate document on [[How groups work in Moodle]] which is worth reading for background especially if you are new to groups in Moodle, although most of the details aren't relevant for module developers. From a module developer's point of view, the differences aren't actually too big. The main changes is that there may be a different set of groups being used for each instance of you module in the course and that separate/visible groups have been replaced by a better system of permissions. The other big changes are all being handled by code elsewhere. There have also been some changes to the database structure for groups (for instance there is now a separate course_group table rather than courseid being a column in the groups table which may affect your code if it has been accessing the database directly for some reason).

As well as modules, there are also some blocks and global features such as blogs
and the calendar that use groups in certain ways. We'll come to those later.

It is obviously good if modules support groups in the ways that users expect!
This document is here to try and help you do that - if anything isn't clear, you
have questions or can think of improvements to how groups work in Moodle, please
post on the Groups forum on moodle.org.

=== How should modules support groups? ===

There are two main ways a module might need to support groups. There may of
course be other more unusual ways in which your module should supports groups,
but these should hopefully be the most common ones. The important thing
is to think about how people would expect your module to behave if they chose to
use groups for it.

==== From a student's point of view ====

From a student's point of view, groups are generally used as a way to enable
parallel versions of the same activity with different groups of students e.g you
might want a separate forum or wiki for each group. If your module is
collaborative in any way (which includes the ability to view the existence of
other students or their contributions) then you need to make sure that this is
supported.

As well as the obvious views of activities being separated, you will need to
make sure that things like searches return the correct results and that teachers
can view the correct groups. You may also need to make a decision as to which
teacher activity is part of the setup of the activity so is the same for every
group and needs to be performed only once, and which teacher activity is the
contribution after the activity has started and so is different for each group.

In general if you module needs to support groups in this way you will find that
the database table(s) where you store the students' contributions will probably
need an extra 'groupid' column, for instance the forum table has a groupid
column.

==== From a teacher's point of view ====

From a teacher's point of view, groups are generally used to manage different
groups of students. For instance there may be several teachers on a course each
assigned to one or more groups of students who mark the work for the groups of
students that have been assigned to them but shouldn't be able to mark the work
of the other groups. A single teacher may also want to be able to view marks for
students by group when they teach the same material to two different classes. In
general, if your module enables teachers to somehow view students' contribution,
then you need to provide this type of support. You can usually do this by
checking which students are in which group rather than needing to alter the
module's database tables in any way.

==== Dealing with users in more than one group ====

Although users may be belong to more than one group, most of the time you can
use the groups library for modules to deal with this rather than having to worry
about this yourself. There will be more about this in the next section. The time
you will probably find that you need to worry about this is when for instance
you are doing a search for contributions that a particular student is allowed to
view. In this case you will need to look for contributions for all the groups
rather than just one group.

=== The groups library for modules ===
The functions at your disposal can be found in course/groups/lib/modulelib.php -
go and have a quick look at it now. (''Again you can't yet, but look here at the [[Groups API for modules]] instead'') Here are some examples of common ways in which you might want to use
the functions in it. Note that modules don't actually need to know anything about groupings directly - the correspondence between an instance of a module and a grouping is taken care of by the library.

1) Present a user with a page containing the right information for one of the
groups that they belong to including a selector to see the equivalent page for
any other groups that they belong to. e.g. present a user with a list of
discussion for a group they belong to.

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_STUDENT_CONTRIBUTE;
groups_m_print_group_selector($cmid, $urlroot, $permissiontype);
$currentgroupid = groups_m_get_selected_group($cmid, $permissiontype);
// This is your function that you've written.
do_whizzy_module_stuff_for_group($cmid, $currentgroupid);
} else {
// Do whatever you'd normally do
}

2) Present a user with search results only for the groups that they are allowed
to view.

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_VIEW;
$groupids = groups_m_get_groups_for_user($cmid, $permissiontype);
// You might want the search funtion to check group permissions too to be
// on the safe side.
get_module_search_results_for_groups($groupids, $maybesomeotherparameters);
} else {
// Do whatever you'd normally do
}

3) Get a list of users which a teacher should be able to mark work

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_TEACHER_CONTRIBUTE;
groups_m_print_group_selector($cmid, $urlroot, $permissiontype);
$groupid = groups_m_get_selected_group($cmid, $permissiontype);
$userids = groups_m_get_members($groupid);
} else {
// Get your userids the normal way
}
// Do whatever you'd normally do with the userids.

It is still ok to use inner joins on the groups_members table in the database
for this type of functionality as obviously this is sometimes required for
performance reasons, but make sure you keep your code that queries the database
clearly separated from your other code.

=== Support for legacy code ===

The following functions should still be supported but are deprecated:

get_groups
user_group
ismember
get_group_users
get_group_students
get_group_teachers
add_user_to_group
mygroupid
groupmode
set_current_group
get_current_group
get_and_set_current_group
setup_and_print_groups

Where appropriate, if a grouping has been specified in the course setting for
use for all activities that grouping will be used in what was previously
'separate groups' mode. If no such grouping has been specified then the first
grouping created for the course that still exists will be used, again in
separate groups mode. If you want better support than this, then I'm afraid you
will need to update the code for your module!

Accessing the groups_members table directly should still work (although it is
not recommended unless you need to do an inner join on it for performance
reasons). Directly accessing the groups table may not work because the course
column has been removed.

The groupid argument in the function search_users from datalib.php will still
work, but will only give members of a group, not those with a specific
permission.

=== Blocks and other special cases ===

There is an essentially identical library for blocks as for modules, only all
the _m_'s in the function names are replaced by _b_'s.

At the moment there is no standard way to set the grouping for a block and most
blocks don't need to use groups. If you want to create a way for someone to set
up a grouping for your block then you will need to do this yourself using the
functions in the other parts of the groups library (under course/groups/lib/)
but ask if you need help. There is a new column in the block_instance table
called groupingid that you will need to set using the function
groups_set_grouping_for_block_instance. If a grouping is set for all activities
for a course then this will get automatically set however.

There are currently two 'global' features in the Moodle core - blogs and the
calendar - a quick word on those in case anyone has plug-ins that provide
similar global features.

Calendar - with the calendar a teacher can set group events when they are within
a course, so basically all they need to do is get all the groups for the course
that a teacher has a particular permission for. Then when displaying calendar
entries to users, need to know which groups a particular has view permission
for across all courses though it's a tiny bit more complicated that this because
a grouping can be used for more than one course and someone may be a student on
one course and a teacher on another.

Blog - It's possible for the admin to set a blog option that makes blogs view
access group level. This means that users can only see blogs of people that they
share a group with for some course - there's a function provided in one of the
main groups libraries to find out if two users share a group. I'm guessing that
you're mostly only wanting to use this with installations with a very small
number of teachers and at some point global groups will get used here instead.

At the moment there is generally no general support for global features, but
this will hopefully come!

== Some rationale ==

I'll probably add stuff in here as it comes up :-)

''' Why doesn't this fit in with roles and permissions? '''

Mostly at the time I started doing this development the roles and permission
code wasn't available yet! The changes to roles and permissions are big and the
changes needed to fit in with them properly need some thought and would be even
more massive than they currently are. It seemed better to get the main
improvements to groups in first and give the roles and permissions code a bit of
time to settle. It would be nice if they are integrated sensible eventually.

''' Why do I have to deal separately with the case where the module uses groups and the case where it doesn't? Isn't there a clever way to do this so I don't have to? '''

Yes, but I wanted to try and keep people's code fairly readable and make it as
easy as possible to shift current over. In practice you shouldn't really have
too much extra code this way anyhow - you can always write functions with a
groupid argument that defaults to false.

[[Category:Developer]]
[[Category:Groups]]

Development:How groups work in Moodle

2006-08-22T08:09:38Z

Jvvw:

'''IMPORTANT:''' This documentation does not refer to current versions of Moodle
and is here at the moment purely in order to obtain comments. Descriptions of
how groups work refer to how they hopefully work not how they will work now! This document is also written in the present tense even though it doesn't refer to the current version of Moodle. This is so I don't have to go through and change it all in a month or two's time.

=== How groups work in Moodle ===

It is possible to have groups of users in Moodle. A person with the right
permissions (generally an editting teacher or admin) can create groups for a course and add and remove users from groups. They can also create sets of groups for the course which we'll refer to as 'groupings'. Groups that belong to the course can be added to and removed from any of the groupings that have been created for the course.

If you haven't seen the interface for creating groupings and groups, I'd
recommend you go to a course in your installation of Moodle for which you have
edit access and which has some participants and follow the Groups link and take
a look (''note: you can't currently do this obviously as the code isn't released
yet!'').

Once there is at least one grouping created for a course, when an editor adds an
activity (i.e. an instance of a module) to a course they may if they wish assign one of the groupings for the
course to use with that instance of the module. A user who is not in a group for
a grouping assigned will not be able to see that the instance of the module
exists. It is also possible for the editor to specify a grouping to use for
everything for the course - this is set up in the course settings.

Each group and grouping must 'belong' to at least one course (it's possible for them to belong to more than one course, but there's no user interface to let you do this easily at the moment). Both teachers and students can belong to groups and a user can belong to more than one group. It is also possible for a group to belong to more than one grouping and for a user to belong to more than one group in a grouping.

There is a choice of various permission settings for a grouping - for instance
you can specify that students may both view and contribute to the group of which
they are a member but only view groups of which they are not members. In time
these settings wil hopefully be superceded by an extension of the roles and
permission system used elsewhere in Moodle, but at the moment they are
independent. The main types of permission that a user can have for a
particular group are 'student view', 'student contribute', 'teacher view' and
'teacher contribute', with it being up to modules to decide how to interpret
these. As we have seen, a user does not need to be a member of a group to have a
particular permission type for that group.

=== How does this differ from the way groups previously worked? ===

* Previously it was only possible to have one set of groups for a course. All activities for a course had to use the same set of groups, whereas now you can use different sets of groups for different activities.
* Previously, for a course with groups, there were two groups modes - separate and visible. With separate groups, students
could not see groups to which they did not belong, whereas with visible groups they could see groups to which they did not belong but not contribute to them. This caused a great deal of confusion when it came to teachers belonging to groups (and also
led to lots of really horrible logic in the code).
* You can now create groups automatically with a certain number of students per group randomly assigned, or with students distributed into a certain number of groups.
* If a student is not in a group for the grouping assigned for an activity, they will not be able to see that activity.
* The infrastructure supporting groups has been improved considerably so that it will make it much easier to make changes to groups in future as well as to module code. For instance, the changes to support global groups should now be fairly simple. If somebody wants to integrate groups with the roles and permissions system in some way this should also be much easier than it previously would have been.

=== Future plans? (Things I'd like to do or you can do for me!) ===

In no particular order:

* Bug fixing I guess :-)
* Global groups - I want it to be possible to set up groupings for course 1 and for these to be visible for all course on the site, but not editable or deletable. I think this code should actually be quite easy to write now and I might even do it before this code is put in, just haven't done it yet.
* A nicer user interface (that doesn't break the back button :-) Ajax separates the back and front end of the code really well, so if anyone has good ideas on this, it should be quite easy for someone else to do without having to know how the internals of the groups code work.
* Integration with roles and permissions
* Sign up sheets for groups
* Proper support for blocks and global features.
* A way for modules and blocks to declare whether they support groups or not.
* Putting in search_users functionality for group permissions as well as just members of groups.
* Cool ways to set up groups automatically for particular pedagogical reasons - things like minimising overlap with groups in another grouping, creating groups just from the users all in another group and creating groups which merge pairs of groups from another grouping.

[[Category:Groups]]

Development:How groups work in Moodle

2006-08-22T08:09:19Z

Jvvw:

'''IMPORTANT:''' This documentation does not refer to current versions of Moodle
and is here at the moment purely in order to obtain comments. Descriptions of
how groups work refer to how they hopefully work not how they will work now! This document is also written in the present tense even though it doesn't refer to the current version of Moodle. This is so I don't have to go through and change it all in a month or two's time.

=== How groups work in Moodle ===

It is possible to have groups of users in Moodle. A person with the right
permissions (generally an editting teacher or admin) can create groups for a course and add and remove users from groups. They can also create sets of groups for the course which we'll refer to as 'groupings'. Groups that belong to the course can be added to and removed from any of the groupings that have been created for the course.

If you haven't seen the interface for creating groupings and groups, I'd
recommend you go to a course in your installation of Moodle for which you have
edit access and which has some participants and follow the Groups link and take
a look (''note: you can't currently do this obviously as the code isn't released
yet!'').

Once there is at least one grouping created for a course, when an editor adds an
activity (i.e. an instance of a module) to a course they may if they wish assign one of the groupings for the
course to use with that instance of the module. A user who is not in a group for
a grouping assigned will not be able to see that the instance of the module
exists. It is also possible for the editor to specify a grouping to use for
everything for the course - this is set up in the course settings.

Each group and grouping must 'belong' to at least one course (it's possible for them to belong to more than one course, but there's no user interface to let you do this easily at the moment). Both teachers and students can belong to groups and a user can belong to more than one group. It is also possible for a group to belong to more than one grouping and for a user to belong to more than one group in a grouping.

There is a choice of various permission settings for a grouping - for instance
you can specify that students may both view and contribute to the group of which
they are a member but only view groups of which they are not members. In time
these settings wil hopefully be superceded by an extension of the roles and
permission system used elsewhere in Moodle, but at the moment they are
independent. The main types of permission that a user can have for a
particular group are 'student view', 'student contribute', 'teacher view' and
'teacher contribute', with it being up to modules to decide how to interpret
these. As we have seen, a user does not need to be a member of a group to have a
particular permission type for that group.

=== How does this differ from the way groups previously worked? ===

* Previously it was only possible to have one set of groups for a course. All activities for a course had to use the same set of groups, whereas now you can use different sets of groups for different activities.
* Previously, for a course with groups, there were two groups modes - separate and visible. With separate groups, students
could not see groups to which they did not belong, whereas with visible groups they could see groups to which they did not belong but not contribute to them. This caused a great deal of confusion when it came to teachers belonging to groups (and also
led to lots of really horrible logic in the code).
* You can now create groups automatically with a certain number of students per group randomly assigned, or with students distributed into a certain number of groups.
* If a student is not in a group for the grouping assigned for an activity, they will not be able to see that activity.
* The infrastructure supporting groups has been improved considerably so that it will make it much easier to make changes to groups in future as well as to module code. For instance, the changes to support global groups should now be fairly simple. If somebody wants to integrate groups with the roles and permissions system in some way this should also be much easier than it previously would have been.

== Future plans? (Things I'd like to do or you can do for me!) ==

In no particular order:

* Bug fixing I guess :-)
* Global groups - I want it to be possible to set up groupings for course 1 and for these to be visible for all course on the site, but not editable or deletable. I think this code should actually be quite easy to write now and I might even do it before this code is put in, just haven't done it yet.
* A nicer user interface (that doesn't break the back button :-) Ajax separates the back and front end of the code really well, so if anyone has good ideas on this, it should be quite easy for someone else to do without having to know how the internals of the groups code work.
* Integration with roles and permissions
* Sign up sheets for groups
* Proper support for blocks and global features.
* A way for modules and blocks to declare whether they support groups or not.
* Putting in search_users functionality for group permissions as well as just members of groups.
* Cool ways to set up groups automatically for particular pedagogical reasons - things like minimising overlap with groups in another grouping, creating groups just from the users all in another group and creating groups which merge pairs of groups from another grouping.

[[Category:Groups]]

Development:Groups documentation for module developers

2006-08-22T08:08:40Z

Jvvw:

== Groups in Moodle for developers==

'''IMPORTANT:''' This documentation does not refer to current versions of Moodle
and is here at the moment purely in order to obtain comments. Descriptions of
how groups work refer to how they hopefully work not how they will work now! This document is also written in the present tense even though it doesn't refer to the current version of Moodle. This is so I don't have to go through and change it all in a month or two's time.

=== How groups work in Moodle ===

There is a separate document on [[How groups work in Moodle]] which is worth reading for background especially if you are new to groups in Moodle, although most of the details aren't relevant for module developers. From a module developer's point of view, the differences aren't actually too big. The main changes is that there may be a different set of groups being used for each instance of you module in the course and that separate/visible groups have been replaced by a better system of permissions. The other big changes are all being handled by code elsewhere. There have also been some changes to the database structure for groups (for instance there is now a separate course_group table rather than courseid being a column in the groups table which may affect your code if it has been accessing the database directly for some reason).

As well as modules, there are also some blocks and global features such as blogs
and the calendar that use groups in certain ways. We'll come to those later.

It is obviously good if modules support groups in the ways that users expect!
This document is here to try and help you do that - if anything isn't clear, you
have questions or can think of improvements to how groups work in Moodle, please
post on the Groups forum on moodle.org.

=== How should modules support groups? ===

There are two main ways a module might need to support groups. There may of
course be other more unusual ways in which your module should supports groups,
but these should hopefully be the most common ones. The important thing
is to think about how people would expect your module to behave if they chose to
use groups for it.

==== From a student's point of view ====

From a student's point of view, groups are generally used as a way to enable
parallel versions of the same activity with different groups of students e.g you
might want a separate forum or wiki for each group. If your module is
collaborative in any way (which includes the ability to view the existence of
other students or their contributions) then you need to make sure that this is
supported.

As well as the obvious views of activities being separated, you will need to
make sure that things like searches return the correct results and that teachers
can view the correct groups. You may also need to make a decision as to which
teacher activity is part of the setup of the activity so is the same for every
group and needs to be performed only once, and which teacher activity is the
contribution after the activity has started and so is different for each group.

In general if you module needs to support groups in this way you will find that
the database table(s) where you store the students' contributions will probably
need an extra 'groupid' column, for instance the forum table has a groupid
column.

==== From a teacher's point of view ====

From a teacher's point of view, groups are generally used to manage different
groups of students. For instance there may be several teachers on a course each
assigned to one or more groups of students who mark the work for the groups of
students that have been assigned to them but shouldn't be able to mark the work
of the other groups. A single teacher may also want to be able to view marks for
students by group when they teach the same material to two different classes. In
general, if your module enables teachers to somehow view students' contribution,
then you need to provide this type of support. You can usually do this by
checking which students are in which group rather than needing to alter the
module's database tables in any way.

==== Dealing with users in more than one group ====

Although users may be belong to more than one group, most of the time you can
use the groups library for modules to deal with this rather than having to worry
about this yourself. There will be more about this in the next section. The time
you will probably find that you need to worry about this is when for instance
you are doing a search for contributions that a particular student is allowed to
view. In this case you will need to look for contributions for all the groups
rather than just one group.

=== The groups library for modules ===
The functions at your disposal can be found in course/groups/lib/modulelib.php -
go and have a quick look at it now. (''Again you can't yet, but look here at the [[Groups API for modules]] instead'') Here are some examples of common ways in which you might want to use
the functions in it. Note that modules don't actually need to know anything about groupings directly - the correspondence between an instance of a module and a grouping is taken care of by the library.

1) Present a user with a page containing the right information for one of the
groups that they belong to including a selector to see the equivalent page for
any other groups that they belong to. e.g. present a user with a list of
discussion for a group they belong to.

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_STUDENT_CONTRIBUTE;
groups_m_print_group_selector($cmid, $urlroot, $permissiontype);
$currentgroupid = groups_m_get_selected_group($cmid, $permissiontype);
// This is your function that you've written.
do_whizzy_module_stuff_for_group($cmid, $currentgroupid);
} else {
// Do whatever you'd normally do
}

2) Present a user with search results only for the groups that they are allowed
to view.

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_VIEW;
$groupids = groups_m_get_groups_for_user($cmid, $permissiontype);
// You might want the search funtion to check group permissions too to be
// on the safe side.
get_module_search_results_for_groups($groupids, $maybesomeotherparameters);
} else {
// Do whatever you'd normally do
}

3) Get a list of users which a teacher should be able to mark work

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_TEACHER_CONTRIBUTE;
groups_m_print_group_selector($cmid, $urlroot, $permissiontype);
$groupid = groups_m_get_selected_group($cmid, $permissiontype);
$userids = groups_m_get_members($groupid);
} else {
// Get your userids the normal way
}
// Do whatever you'd normally do with the userids.

It is still ok to use inner joins on the groups_members table in the database
for this type of functionality as obviously this is sometimes required for
performance reasons, but make sure you keep your code that queries the database
clearly separated from your other code.

=== Support for legacy code ===

The following functions should still be supported but are deprecated:

get_groups
user_group
ismember
get_group_users
get_group_students
get_group_teachers
add_user_to_group
mygroupid
groupmode
set_current_group
get_current_group
get_and_set_current_group
setup_and_print_groups

Where appropriate, if a grouping has been specified in the course setting for
use for all activities that grouping will be used in what was previously
'separate groups' mode. If no such grouping has been specified then the first
grouping created for the course that still exists will be used, again in
separate groups mode. If you want better support than this, then I'm afraid you
will need to update the code for your module!

Accessing the groups_members table directly should still work (although it is
not recommended unless you need to do an inner join on it for performance
reasons). Directly accessing the groups table may not work because the course
column has been removed.

The groupid argument in the function search_users from datalib.php will still
work, but will only give members of a group, not those with a specific
permission.

=== Blocks and other special cases ===

There is an essentially identical library for blocks as for modules, only all
the _m_'s in the function names are replaced by _b_'s.

At the moment there is no standard way to set the grouping for a block and most
blocks don't need to use groups. If you want to create a way for someone to set
up a grouping for your block then you will need to do this yourself using the
functions in the other parts of the groups library (under course/groups/lib/)
but ask if you need help. There is a new column in the block_instance table
called groupingid that you will need to set using the function
groups_set_grouping_for_block_instance. If a grouping is set for all activities
for a course then this will get automatically set however.

There are currently two 'global' features in the Moodle core - blogs and the
calendar - a quick word on those in case anyone has plug-ins that provide
similar global features.

Calendar - with the calendar a teacher can set group events when they are within
a course, so basically all they need to do is get all the groups for the course
that a teacher has a particular permission for. Then when displaying calendar
entries to users, need to know which groups a particular has view permission
for across all courses though it's a tiny bit more complicated that this because
a grouping can be used for more than one course and someone may be a student on
one course and a teacher on another.

Blog - It's possible for the admin to set a blog option that makes blogs view
access group level. This means that users can only see blogs of people that they
share a group with for some course - there's a function provided in one of the
main groups libraries to find out if two users share a group. I'm guessing that
you're mostly only wanting to use this with installations with a very small
number of teachers and at some point global groups will get used here instead.

At the moment there is generally no general support for global features, but
this will hopefully come!

== Some rationale ==

I'll probably add stuff in here as it comes up :-)

''' Why doesn't this fit in with roles and permissions? '''

Mostly at the time I started doing this development the roles and permission
code wasn't available yet! The changes to roles and permissions are big and the
changes needed to fit in with them properly need some thought and would be even
more massive than they currently are. It seemed better to get the main
improvements to groups in first and give the roles and permissions code a bit of
time to settle. It would be nice if they are integrated sensible eventually.

''' Why do I have to deal separately with the case where the module uses groups and the case where it doesn't? Isn't there a clever way to do this so I don't have to? '''

Yes, but I wanted to try and keep people's code fairly readable and make it as
easy as possible to shift current over. In practice you shouldn't really have
too much extra code this way anyhow - you can always write functions with a
groupid argument that defaults to false.

== Future plans? (Things I'd like to do or you can do for me!) ==

In no particular order:

* Bug fixing I guess :-)
* Global groups - I want it to be possible to set up groupings for course 1 and for these to be visible for all course on the site, but not editable or deletable. I think this code should actually be quite easy to write now and I might even do it before this code is put in, just haven't done it yet.
* A nicer user interface (that doesn't break the back button :-) Ajax separates the back and front end of the code really well, so if anyone has good ideas on this, it should be quite easy for someone else to do without having to know how the internals of the groups code work.
* Integration with roles and permissions
* Sign up sheets for groups
* Proper support for blocks and global features.
* A way for modules and blocks to declare whether they support groups or not.
* Putting in search_users functionality for group permissions as well as just members of groups.
* Cool ways to set up groups automatically for particular pedagogical reasons - things like minimising overlap with groups in another grouping, creating groups just from the users all in another group and creating groups which merge pairs of groups from another grouping.

[[Category:Developer]]
[[Category:Groups]]

Development:Groups documentation for module developers

2006-08-22T07:59:51Z

Jvvw:

== Groups in Moodle for developers==

'''IMPORTANT:''' This documentation does not refer to current versions of Moodle
and is here at the moment purely in order to obtain comments. Descriptions of
how groups work refer to how they hopefully work not how they will work now! This document is also written in the present tense even though it doesn't refer to the current version of Moodle. This is so I don't have to go through and change it all in a month or two's time.

=== How groups work in Moodle ===

There is a separate document on [[How groups work in Moodle]] which is worth reading for background especially if you are new to groups in Moodle, although most of the details aren't relevant for module developers. From a module developer's point of view, the differences aren't actually too big. The main changes is that there may be a different set of groups being used for each instance of you module in the course and that separate/visible groups have been replaced by a better system of permissions. The other big changes are all being handled by code elsewhere. There have also been some changes to the database structure for groups (for instance there is now a separate course_group table rather than courseid being a column in the groups table which may affect your code if it has been accessing the database directly for some reason).

=== How should modules support groups? ===

There are two main ways a module might need to support groups. There may of
course be other more unusual ways in which your module should supports groups,
but these should hopefully be the most common ones. The important thing
is to think about how people would expect your module to behave if they chose to
use groups for it.

==== From a student's point of view ====

From a student's point of view, groups are generally used as a way to enable
parallel versions of the same activity with different groups of students e.g you
might want a separate forum or wiki for each group. If your module is
collaborative in any way (which includes the ability to view the existence of
other students or their contributions) then you need to make sure that this is
supported.

As well as the obvious views of activities being separated, you will need to
make sure that things like searches return the correct results and that teachers
can view the correct groups. You may also need to make a decision as to which
teacher activity is part of the setup of the activity so is the same for every
group and needs to be performed only once, and which teacher activity is the
contribution after the activity has started and so is different for each group.

In general if you module needs to support groups in this way you will find that
the database table(s) where you store the students' contributions will probably
need an extra 'groupid' column, for instance the forum table has a groupid
column.

==== From a teacher's point of view ====

From a teacher's point of view, groups are generally used to manage different
groups of students. For instance there may be several teachers on a course each
assigned to one or more groups of students who mark the work for the groups of
students that have been assigned to them but shouldn't be able to mark the work
of the other groups. A single teacher may also want to be able to view marks for
students by group when they teach the same material to two different classes. In
general, if your module enables teachers to somehow view students' contribution,
then you need to provide this type of support. You can usually do this by
checking which students are in which group rather than needing to alter the
module's database tables in any way.

==== Dealing with users in more than one group ====

Although users may be belong to more than one group, most of the time you can
use the groups library for modules to deal with this rather than having to worry
about this yourself. There will be more about this in the next section. The time
you will probably find that you need to worry about this is when for instance
you are doing a search for contributions that a particular student is allowed to
view. In this case you will need to look for contributions for all the groups
rather than just one group.

=== The groups library for modules ===
The functions at your disposal can be found in course/groups/lib/modulelib.php -
go and have a quick look at it now. (''Again you can't yet, but look here at the [[Groups API for modules]] instead'') Here are some examples of common ways in which you might want to use
the functions in it. Note that modules don't actually need to know anything about groupings directly - the correspondence between an instance of a module and a grouping is taken care of by the library.

1) Present a user with a page containing the right information for one of the
groups that they belong to including a selector to see the equivalent page for
any other groups that they belong to. e.g. present a user with a list of
discussion for a group they belong to.

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_STUDENT_CONTRIBUTE;
groups_m_print_group_selector($cmid, $urlroot, $permissiontype);
$currentgroupid = groups_m_get_selected_group($cmid, $permissiontype);
// This is your function that you've written.
do_whizzy_module_stuff_for_group($cmid, $currentgroupid);
} else {
// Do whatever you'd normally do
}

2) Present a user with search results only for the groups that they are allowed
to view.

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_VIEW;
$groupids = groups_m_get_groups_for_user($cmid, $permissiontype);
// You might want the search funtion to check group permissions too to be
// on the safe side.
get_module_search_results_for_groups($groupids, $maybesomeotherparameters);
} else {
// Do whatever you'd normally do
}

3) Get a list of users which a teacher should be able to mark work

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_TEACHER_CONTRIBUTE;
groups_m_print_group_selector($cmid, $urlroot, $permissiontype);
$groupid = groups_m_get_selected_group($cmid, $permissiontype);
$userids = groups_m_get_members($groupid);
} else {
// Get your userids the normal way
}
// Do whatever you'd normally do with the userids.

It is still ok to use inner joins on the groups_members table in the database
for this type of functionality as obviously this is sometimes required for
performance reasons, but make sure you keep your code that queries the database
clearly separated from your other code.

=== Support for legacy code ===

The following functions should still be supported but are deprecated:

get_groups
user_group
ismember
get_group_users
get_group_students
get_group_teachers
add_user_to_group
mygroupid
groupmode
set_current_group
get_current_group
get_and_set_current_group
setup_and_print_groups

Where appropriate, if a grouping has been specified in the course setting for
use for all activities that grouping will be used in what was previously
'separate groups' mode. If no such grouping has been specified then the first
grouping created for the course that still exists will be used, again in
separate groups mode. If you want better support than this, then I'm afraid you
will need to update the code for your module!

Accessing the groups_members table directly should still work (although it is
not recommended unless you need to do an inner join on it for performance
reasons). Directly accessing the groups table may not work because the course
column has been removed.

The groupid argument in the function search_users from datalib.php will still
work, but will only give members of a group, not those with a specific
permission.

=== Blocks and other special cases ===

There is an essentially identical library for blocks as for modules, only all
the _m_'s in the function names are replaced by _b_'s.

At the moment there is no standard way to set the grouping for a block and most
blocks don't need to use groups. If you want to create a way for someone to set
up a grouping for your block then you will need to do this yourself using the
functions in the other parts of the groups library (under course/groups/lib/)
but ask if you need help. There is a new column in the block_instance table
called groupingid that you will need to set using the function
groups_set_grouping_for_block_instance. If a grouping is set for all activities
for a course then this will get automatically set however.

There are currently two 'global' features in the Moodle core - blogs and the
calendar - a quick word on those in case anyone has plug-ins that provide
similar global features.

Calendar - with the calendar a teacher can set group events when they are within
a course, so basically all they need to do is get all the groups for the course
that a teacher has a particular permission for. Then when displaying calendar
entries to users, need to know which groups a particular has view permission
for across all courses though it's a tiny bit more complicated that this because
a grouping can be used for more than one course and someone may be a student on
one course and a teacher on another.

Blog - It's possible for the admin to set a blog option that makes blogs view
access group level. This means that users can only see blogs of people that they
share a group with for some course - there's a function provided in one of the
main groups libraries to find out if two users share a group. I'm guessing that
you're mostly only wanting to use this with installations with a very small
number of teachers and at some point global groups will get used here instead.

At the moment there is generally no general support for global features, but
this will hopefully come!

== Some rationale ==

I'll probably add stuff in here as it comes up :-)

''' Why doesn't this fit in with roles and permissions? '''

Mostly at the time I started doing this development the roles and permission
code wasn't available yet! The changes to roles and permissions are big and the
changes needed to fit in with them properly need some thought and would be even
more massive than they currently are. It seemed better to get the main
improvements to groups in first and give the roles and permissions code a bit of
time to settle. It would be nice if they are integrated sensible eventually.

''' Why do I have to deal separately with the case where the module uses groups and the case where it doesn't? Isn't there a clever way to do this so I don't have to? '''

Yes, but I wanted to try and keep people's code fairly readable and make it as
easy as possible to shift current over. In practice you shouldn't really have
too much extra code this way anyhow - you can always write functions with a
groupid argument that defaults to false.

== Future plans? (Things I'd like to do or you can do for me!) ==

In no particular order:

* Bug fixing I guess :-)
* Global groups - I want it to be possible to set up groupings for course 1 and for these to be visible for all course on the site, but not editable or deletable. I think this code should actually be quite easy to write now and I might even do it before this code is put in, just haven't done it yet.
* A nicer user interface (that doesn't break the back button :-) Ajax separates the back and front end of the code really well, so if anyone has good ideas on this, it should be quite easy for someone else to do without having to know how the internals of the groups code work.
* Integration with roles and permissions
* Sign up sheets for groups
* Proper support for blocks and global features.
* A way for modules and blocks to declare whether they support groups or not.
* Putting in search_users functionality for group permissions as well as just members of groups.
* Cool ways to set up groups automatically for particular pedagogical reasons - things like minimising overlap with groups in another grouping, creating groups just from the users all in another group and creating groups which merge pairs of groups from another grouping.

[[Category:Developer]]
[[Category:Groups]]

Development:How groups work in Moodle

2006-08-22T07:50:51Z

Jvvw:

'''IMPORTANT:''' This documentation does not refer to current versions of Moodle
and is here at the moment purely in order to obtain comments. Descriptions of
how groups work refer to how they hopefully work not how they will work now! This document is also written in the present tense even though it doesn't refer to the current version of Moodle. This is so I don't have to go through and change it all in a month or two's time.

=== How groups work in Moodle ===

It is possible to have groups of users in Moodle. A person with the right
permissions (generally an editting teacher or admin) can create groups for a course and add and remove users from groups. They can also create sets of groups for the course which we'll refer to as 'groupings'. Groups that belong to the course can be added to and removed from any of the groupings that have been created for the course.

If you haven't seen the interface for creating groupings and groups, I'd
recommend you go to a course in your installation of Moodle for which you have
edit access and which has some participants and follow the Groups link and take
a look (''note: you can't currently do this obviously as the code isn't released
yet!'').

Once there is at least one grouping created for a course, when an editor adds an
activity (i.e. an instance of a module) to a course they may if they wish assign one of the groupings for the
course to use with that instance of the module. A user who is not in a group for
a grouping assigned will not be able to see that the instance of the module
exists. It is also possible for the editor to specify a grouping to use for
everything for the course - this is set up in the course settings.

Each group and grouping must 'belong' to at least one course (it's possible for them to belong to more than one course, but there's no user interface to let you do this easily at the moment). Both teachers and students can belong to groups and a user can belong to more than one group. It is also possible for a group to belong to more than one grouping.

There is a choice of various permission settings for a grouping - for instance
you can specify that students may both view and contribute to the group of which
they are a member but only view groups of which they are not members. In time
these settings wil hopefully be superceded by an extension of the roles and
permission system used elsewhere in Moodle, but at the moment they are
independent. The main types of permission that a user can have for a
particular group are 'student view', 'student contribute', 'teacher view' and
'teacher contribute', with it being up to modules to decide how to interpret
these. As we have seen, a user does not need to be a member of a group to have a
particular permission type for that group.

As well as modules, there are also some blocks and global features such as blogs
and the calendar that use groups in certain ways. We'll come to those later.

It is obviously good if modules support groups in the ways that users expect!
This document is here to try and help you do that - if anything isn't clear, you
have questions or can think of improvements to how groups work in Moodle, please
post on the Groups forum on moodle.org.

=== How does this differ from the way groups previously worked? ===

The biggest difference is that previously it was only possible to have one set of groups for a course. All activities for a course had to use the same set of groups, whereas now you can use different sets of groups for different activities. This is the main reason that the API needed to change.

Also, previously, for a course with groups, there were two groups modes - separate and visible. With separate groups, students
could not see groups to which they did not belong, whereas with visible groups they could see groups to which they did not belong but not contribute to them. This caused a great deal of confusion when it came to teachers belonging to groups and also
led to lots of really horrible logic in module code trying to work out who could view or contribute to an activity. This is why the separate/visible groups modes have been replaced by a clearer and more granular permissions system.

Another big difference that isn't obviously visible is there are now tables in the database for course_groups and courses_groupings, whereas previous the groups table had a courseid column. This made it very difficult to use the same group for more than one course. This should now be much easier. However this obviously affects any code that used to access the groups table directly.

There are also improvements to the user interface for creating groups, though these aren't specifically relevant to module developers.

Development:Groups documentation for module developers

2006-08-22T07:50:15Z

Jvvw: /* How groups work in Moodle */

== Groups in Moodle for developers==

'''IMPORTANT:''' This documentation does not refer to current versions of Moodle
and is here at the moment purely in order to obtain comments. Descriptions of
how groups work refer to how they hopefully work not how they will work now! This document is also written in the present tense even though it doesn't refer to the current version of Moodle. This is so I don't have to go through and change it all in a month or two's time.

=== How groups work in Moodle ===

It is possible to have groups of users in Moodle. A person with the right
permissions (generally an editting teacher or admin) can create groups for a course and add and remove users from groups. They can also create sets of groups for the course which we'll refer to as 'groupings'. Groups that belong to the course can be added to and removed from any of the groupings that have been created for the course.

If you haven't seen the interface for creating groupings and groups, I'd
recommend you go to a course in your installation of Moodle for which you have
edit access and which has some participants and follow the Groups link and take
a look (''note: you can't currently do this obviously as the code isn't released
yet!'').

Once there is at least one grouping created for a course, when an editor adds an
activity (i.e. an instance of a module) to a course they may if they wish assign one of the groupings for the
course to use with that instance of the module. A user who is not in a group for
a grouping assigned will not be able to see that the instance of the module
exists. It is also possible for the editor to specify a grouping to use for
everything for the course - this is set up in the course settings.

Each group and grouping must 'belong' to at least one course (it's possible for them to belong to more than one course, but there's no user interface to let you do this easily at the moment). Both teachers and students can belong to groups and a user can belong to more than one group. It is also possible for a group to belong to more than one grouping.

There is a choice of various permission settings for a grouping - for instance
you can specify that students may both view and contribute to the group of which
they are a member but only view groups of which they are not members. In time
these settings wil hopefully be superceded by an extension of the roles and
permission system used elsewhere in Moodle, but at the moment they are
independent. The main types of permission that a user can have for a
particular group are 'student view', 'student contribute', 'teacher view' and
'teacher contribute', with it being up to modules to decide how to interpret
these. As we have seen, a user does not need to be a member of a group to have a
particular permission type for that group.

As well as modules, there are also some blocks and global features such as blogs
and the calendar that use groups in certain ways. We'll come to those later.

It is obviously good if modules support groups in the ways that users expect!
This document is here to try and help you do that - if anything isn't clear, you
have questions or can think of improvements to how groups work in Moodle, please
post on the Groups forum on moodle.org.

=== How does this differ from the way groups previously worked? ===

The biggest difference is that previously it was only possible to have one set of groups for a course. All activities for a course had to use the same set of groups, whereas now you can use different sets of groups for different activities. This is the main reason that the API needed to change.

Also, previously, for a course with groups, there were two groups modes - separate and visible. With separate groups, students
could not see groups to which they did not belong, whereas with visible groups they could see groups to which they did not belong but not contribute to them. This caused a great deal of confusion when it came to teachers belonging to groups and also
led to lots of really horrible logic in module code trying to work out who could view or contribute to an activity. This is why the separate/visible groups modes have been replaced by a clearer and more granular permissions system.

Another big difference that isn't obviously visible is there are now tables in the database for course_groups and courses_groupings, whereas previous the groups table had a courseid column. This made it very difficult to use the same group for more than one course. This should now be much easier. However this obviously affects any code that used to access the groups table directly.

There are also improvements to the user interface for creating groups, though these aren't specifically relevant to module developers.

=== How should modules support groups? ===

There are two main ways a module might need to support groups. There may of
course be other more unusual ways in which your module should supports groups,
but these should hopefully be the most common ones. The important thing
is to think about how people would expect your module to behave if they chose to
use groups for it.

==== From a student's point of view ====

From a student's point of view, groups are generally used as a way to enable
parallel versions of the same activity with different groups of students e.g you
might want a separate forum or wiki for each group. If your module is
collaborative in any way (which includes the ability to view the existence of
other students or their contributions) then you need to make sure that this is
supported.

As well as the obvious views of activities being separated, you will need to
make sure that things like searches return the correct results and that teachers
can view the correct groups. You may also need to make a decision as to which
teacher activity is part of the setup of the activity so is the same for every
group and needs to be performed only once, and which teacher activity is the
contribution after the activity has started and so is different for each group.

In general if you module needs to support groups in this way you will find that
the database table(s) where you store the students' contributions will probably
need an extra 'groupid' column, for instance the forum table has a groupid
column.

==== From a teacher's point of view ====

From a teacher's point of view, groups are generally used to manage different
groups of students. For instance there may be several teachers on a course each
assigned to one or more groups of students who mark the work for the groups of
students that have been assigned to them but shouldn't be able to mark the work
of the other groups. A single teacher may also want to be able to view marks for
students by group when they teach the same material to two different classes. In
general, if your module enables teachers to somehow view students' contribution,
then you need to provide this type of support. You can usually do this by
checking which students are in which group rather than needing to alter the
module's database tables in any way.

==== Dealing with users in more than one group ====

Although users may be belong to more than one group, most of the time you can
use the groups library for modules to deal with this rather than having to worry
about this yourself. There will be more about this in the next section. The time
you will probably find that you need to worry about this is when for instance
you are doing a search for contributions that a particular student is allowed to
view. In this case you will need to look for contributions for all the groups
rather than just one group.

=== The groups library for modules ===
The functions at your disposal can be found in course/groups/lib/modulelib.php -
go and have a quick look at it now. (''Again you can't yet, but look here at the [[Groups API for modules]] instead'') Here are some examples of common ways in which you might want to use
the functions in it. Note that modules don't actually need to know anything about groupings directly - the correspondence between an instance of a module and a grouping is taken care of by the library.

1) Present a user with a page containing the right information for one of the
groups that they belong to including a selector to see the equivalent page for
any other groups that they belong to. e.g. present a user with a list of
discussion for a group they belong to.

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_STUDENT_CONTRIBUTE;
groups_m_print_group_selector($cmid, $urlroot, $permissiontype);
$currentgroupid = groups_m_get_selected_group($cmid, $permissiontype);
// This is your function that you've written.
do_whizzy_module_stuff_for_group($cmid, $currentgroupid);
} else {
// Do whatever you'd normally do
}

2) Present a user with search results only for the groups that they are allowed
to view.

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_VIEW;
$groupids = groups_m_get_groups_for_user($cmid, $permissiontype);
// You might want the search funtion to check group permissions too to be
// on the safe side.
get_module_search_results_for_groups($groupids, $maybesomeotherparameters);
} else {
// Do whatever you'd normally do
}

3) Get a list of users which a teacher should be able to mark work

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_TEACHER_CONTRIBUTE;
groups_m_print_group_selector($cmid, $urlroot, $permissiontype);
$groupid = groups_m_get_selected_group($cmid, $permissiontype);
$userids = groups_m_get_members($groupid);
} else {
// Get your userids the normal way
}
// Do whatever you'd normally do with the userids.

It is still ok to use inner joins on the groups_members table in the database
for this type of functionality as obviously this is sometimes required for
performance reasons, but make sure you keep your code that queries the database
clearly separated from your other code.

=== Support for legacy code ===

The following functions should still be supported but are deprecated:

get_groups
user_group
ismember
get_group_users
get_group_students
get_group_teachers
add_user_to_group
mygroupid
groupmode
set_current_group
get_current_group
get_and_set_current_group
setup_and_print_groups

Where appropriate, if a grouping has been specified in the course setting for
use for all activities that grouping will be used in what was previously
'separate groups' mode. If no such grouping has been specified then the first
grouping created for the course that still exists will be used, again in
separate groups mode. If you want better support than this, then I'm afraid you
will need to update the code for your module!

Accessing the groups_members table directly should still work (although it is
not recommended unless you need to do an inner join on it for performance
reasons). Directly accessing the groups table may not work because the course
column has been removed.

The groupid argument in the function search_users from datalib.php will still
work, but will only give members of a group, not those with a specific
permission.

=== Blocks and other special cases ===

There is an essentially identical library for blocks as for modules, only all
the _m_'s in the function names are replaced by _b_'s.

At the moment there is no standard way to set the grouping for a block and most
blocks don't need to use groups. If you want to create a way for someone to set
up a grouping for your block then you will need to do this yourself using the
functions in the other parts of the groups library (under course/groups/lib/)
but ask if you need help. There is a new column in the block_instance table
called groupingid that you will need to set using the function
groups_set_grouping_for_block_instance. If a grouping is set for all activities
for a course then this will get automatically set however.

There are currently two 'global' features in the Moodle core - blogs and the
calendar - a quick word on those in case anyone has plug-ins that provide
similar global features.

Calendar - with the calendar a teacher can set group events when they are within
a course, so basically all they need to do is get all the groups for the course
that a teacher has a particular permission for. Then when displaying calendar
entries to users, need to know which groups a particular has view permission
for across all courses though it's a tiny bit more complicated that this because
a grouping can be used for more than one course and someone may be a student on
one course and a teacher on another.

Blog - It's possible for the admin to set a blog option that makes blogs view
access group level. This means that users can only see blogs of people that they
share a group with for some course - there's a function provided in one of the
main groups libraries to find out if two users share a group. I'm guessing that
you're mostly only wanting to use this with installations with a very small
number of teachers and at some point global groups will get used here instead.

At the moment there is generally no general support for global features, but
this will hopefully come!

== Some rationale ==

I'll probably add stuff in here as it comes up :-)

''' Why doesn't this fit in with roles and permissions? '''

Mostly at the time I started doing this development the roles and permission
code wasn't available yet! The changes to roles and permissions are big and the
changes needed to fit in with them properly need some thought and would be even
more massive than they currently are. It seemed better to get the main
improvements to groups in first and give the roles and permissions code a bit of
time to settle. It would be nice if they are integrated sensible eventually.

''' Why do I have to deal separately with the case where the module uses groups and the case where it doesn't? Isn't there a clever way to do this so I don't have to? '''

Yes, but I wanted to try and keep people's code fairly readable and make it as
easy as possible to shift current over. In practice you shouldn't really have
too much extra code this way anyhow - you can always write functions with a
groupid argument that defaults to false.

== Future plans? (Things I'd like to do or you can do for me!) ==

In no particular order:

* Bug fixing I guess :-)
* Global groups - I want it to be possible to set up groupings for course 1 and for these to be visible for all course on the site, but not editable or deletable. I think this code should actually be quite easy to write now and I might even do it before this code is put in, just haven't done it yet.
* A nicer user interface (that doesn't break the back button :-) Ajax separates the back and front end of the code really well, so if anyone has good ideas on this, it should be quite easy for someone else to do without having to know how the internals of the groups code work.
* Integration with roles and permissions
* Sign up sheets for groups
* Proper support for blocks and global features.
* A way for modules and blocks to declare whether they support groups or not.
* Putting in search_users functionality for group permissions as well as just members of groups.
* Cool ways to set up groups automatically for particular pedagogical reasons - things like minimising overlap with groups in another grouping, creating groups just from the users all in another group and creating groups which merge pairs of groups from another grouping.

[[Category:Developer]]
[[Category:Groups]]

Development:Groups documentation for module developers

2006-08-22T07:49:58Z

Jvvw:

== Groups in Moodle for developers==

'''IMPORTANT:''' This documentation does not refer to current versions of Moodle
and is here at the moment purely in order to obtain comments. Descriptions of
how groups work refer to how they hopefully work not how they will work now! This document is also written in the present tense even though it doesn't refer to the current version of Moodle. This is so I don't have to go through and change it all in a month or two's time.

=== How groups work in Moodle ===

[[How groups work in Moodle]]

It is possible to have groups of users in Moodle. A person with the right
permissions (generally an editting teacher or admin) can create groups for a course and add and remove users from groups. They can also create sets of groups for the course which we'll refer to as 'groupings'. Groups that belong to the course can be added to and removed from any of the groupings that have been created for the course.

If you haven't seen the interface for creating groupings and groups, I'd
recommend you go to a course in your installation of Moodle for which you have
edit access and which has some participants and follow the Groups link and take
a look (''note: you can't currently do this obviously as the code isn't released
yet!'').

Once there is at least one grouping created for a course, when an editor adds an
activity (i.e. an instance of a module) to a course they may if they wish assign one of the groupings for the
course to use with that instance of the module. A user who is not in a group for
a grouping assigned will not be able to see that the instance of the module
exists. It is also possible for the editor to specify a grouping to use for
everything for the course - this is set up in the course settings.

Each group and grouping must 'belong' to at least one course (it's possible for them to belong to more than one course, but there's no user interface to let you do this easily at the moment). Both teachers and students can belong to groups and a user can belong to more than one group. It is also possible for a group to belong to more than one grouping.

There is a choice of various permission settings for a grouping - for instance
you can specify that students may both view and contribute to the group of which
they are a member but only view groups of which they are not members. In time
these settings wil hopefully be superceded by an extension of the roles and
permission system used elsewhere in Moodle, but at the moment they are
independent. The main types of permission that a user can have for a
particular group are 'student view', 'student contribute', 'teacher view' and
'teacher contribute', with it being up to modules to decide how to interpret
these. As we have seen, a user does not need to be a member of a group to have a
particular permission type for that group.

As well as modules, there are also some blocks and global features such as blogs
and the calendar that use groups in certain ways. We'll come to those later.

It is obviously good if modules support groups in the ways that users expect!
This document is here to try and help you do that - if anything isn't clear, you
have questions or can think of improvements to how groups work in Moodle, please
post on the Groups forum on moodle.org.

=== How does this differ from the way groups previously worked? ===

The biggest difference is that previously it was only possible to have one set of groups for a course. All activities for a course had to use the same set of groups, whereas now you can use different sets of groups for different activities. This is the main reason that the API needed to change.

Also, previously, for a course with groups, there were two groups modes - separate and visible. With separate groups, students
could not see groups to which they did not belong, whereas with visible groups they could see groups to which they did not belong but not contribute to them. This caused a great deal of confusion when it came to teachers belonging to groups and also
led to lots of really horrible logic in module code trying to work out who could view or contribute to an activity. This is why the separate/visible groups modes have been replaced by a clearer and more granular permissions system.

Another big difference that isn't obviously visible is there are now tables in the database for course_groups and courses_groupings, whereas previous the groups table had a courseid column. This made it very difficult to use the same group for more than one course. This should now be much easier. However this obviously affects any code that used to access the groups table directly.

There are also improvements to the user interface for creating groups, though these aren't specifically relevant to module developers.

=== How should modules support groups? ===

There are two main ways a module might need to support groups. There may of
course be other more unusual ways in which your module should supports groups,
but these should hopefully be the most common ones. The important thing
is to think about how people would expect your module to behave if they chose to
use groups for it.

==== From a student's point of view ====

From a student's point of view, groups are generally used as a way to enable
parallel versions of the same activity with different groups of students e.g you
might want a separate forum or wiki for each group. If your module is
collaborative in any way (which includes the ability to view the existence of
other students or their contributions) then you need to make sure that this is
supported.

As well as the obvious views of activities being separated, you will need to
make sure that things like searches return the correct results and that teachers
can view the correct groups. You may also need to make a decision as to which
teacher activity is part of the setup of the activity so is the same for every
group and needs to be performed only once, and which teacher activity is the
contribution after the activity has started and so is different for each group.

In general if you module needs to support groups in this way you will find that
the database table(s) where you store the students' contributions will probably
need an extra 'groupid' column, for instance the forum table has a groupid
column.

==== From a teacher's point of view ====

From a teacher's point of view, groups are generally used to manage different
groups of students. For instance there may be several teachers on a course each
assigned to one or more groups of students who mark the work for the groups of
students that have been assigned to them but shouldn't be able to mark the work
of the other groups. A single teacher may also want to be able to view marks for
students by group when they teach the same material to two different classes. In
general, if your module enables teachers to somehow view students' contribution,
then you need to provide this type of support. You can usually do this by
checking which students are in which group rather than needing to alter the
module's database tables in any way.

==== Dealing with users in more than one group ====

Although users may be belong to more than one group, most of the time you can
use the groups library for modules to deal with this rather than having to worry
about this yourself. There will be more about this in the next section. The time
you will probably find that you need to worry about this is when for instance
you are doing a search for contributions that a particular student is allowed to
view. In this case you will need to look for contributions for all the groups
rather than just one group.

=== The groups library for modules ===
The functions at your disposal can be found in course/groups/lib/modulelib.php -
go and have a quick look at it now. (''Again you can't yet, but look here at the [[Groups API for modules]] instead'') Here are some examples of common ways in which you might want to use
the functions in it. Note that modules don't actually need to know anything about groupings directly - the correspondence between an instance of a module and a grouping is taken care of by the library.

1) Present a user with a page containing the right information for one of the
groups that they belong to including a selector to see the equivalent page for
any other groups that they belong to. e.g. present a user with a list of
discussion for a group they belong to.

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_STUDENT_CONTRIBUTE;
groups_m_print_group_selector($cmid, $urlroot, $permissiontype);
$currentgroupid = groups_m_get_selected_group($cmid, $permissiontype);
// This is your function that you've written.
do_whizzy_module_stuff_for_group($cmid, $currentgroupid);
} else {
// Do whatever you'd normally do
}

2) Present a user with search results only for the groups that they are allowed
to view.

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_VIEW;
$groupids = groups_m_get_groups_for_user($cmid, $permissiontype);
// You might want the search funtion to check group permissions too to be
// on the safe side.
get_module_search_results_for_groups($groupids, $maybesomeotherparameters);
} else {
// Do whatever you'd normally do
}

3) Get a list of users which a teacher should be able to mark work

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_TEACHER_CONTRIBUTE;
groups_m_print_group_selector($cmid, $urlroot, $permissiontype);
$groupid = groups_m_get_selected_group($cmid, $permissiontype);
$userids = groups_m_get_members($groupid);
} else {
// Get your userids the normal way
}
// Do whatever you'd normally do with the userids.

It is still ok to use inner joins on the groups_members table in the database
for this type of functionality as obviously this is sometimes required for
performance reasons, but make sure you keep your code that queries the database
clearly separated from your other code.

=== Support for legacy code ===

The following functions should still be supported but are deprecated:

get_groups
user_group
ismember
get_group_users
get_group_students
get_group_teachers
add_user_to_group
mygroupid
groupmode
set_current_group
get_current_group
get_and_set_current_group
setup_and_print_groups

Where appropriate, if a grouping has been specified in the course setting for
use for all activities that grouping will be used in what was previously
'separate groups' mode. If no such grouping has been specified then the first
grouping created for the course that still exists will be used, again in
separate groups mode. If you want better support than this, then I'm afraid you
will need to update the code for your module!

Accessing the groups_members table directly should still work (although it is
not recommended unless you need to do an inner join on it for performance
reasons). Directly accessing the groups table may not work because the course
column has been removed.

The groupid argument in the function search_users from datalib.php will still
work, but will only give members of a group, not those with a specific
permission.

=== Blocks and other special cases ===

There is an essentially identical library for blocks as for modules, only all
the _m_'s in the function names are replaced by _b_'s.

At the moment there is no standard way to set the grouping for a block and most
blocks don't need to use groups. If you want to create a way for someone to set
up a grouping for your block then you will need to do this yourself using the
functions in the other parts of the groups library (under course/groups/lib/)
but ask if you need help. There is a new column in the block_instance table
called groupingid that you will need to set using the function
groups_set_grouping_for_block_instance. If a grouping is set for all activities
for a course then this will get automatically set however.

There are currently two 'global' features in the Moodle core - blogs and the
calendar - a quick word on those in case anyone has plug-ins that provide
similar global features.

Calendar - with the calendar a teacher can set group events when they are within
a course, so basically all they need to do is get all the groups for the course
that a teacher has a particular permission for. Then when displaying calendar
entries to users, need to know which groups a particular has view permission
for across all courses though it's a tiny bit more complicated that this because
a grouping can be used for more than one course and someone may be a student on
one course and a teacher on another.

Blog - It's possible for the admin to set a blog option that makes blogs view
access group level. This means that users can only see blogs of people that they
share a group with for some course - there's a function provided in one of the
main groups libraries to find out if two users share a group. I'm guessing that
you're mostly only wanting to use this with installations with a very small
number of teachers and at some point global groups will get used here instead.

At the moment there is generally no general support for global features, but
this will hopefully come!

== Some rationale ==

I'll probably add stuff in here as it comes up :-)

''' Why doesn't this fit in with roles and permissions? '''

Mostly at the time I started doing this development the roles and permission
code wasn't available yet! The changes to roles and permissions are big and the
changes needed to fit in with them properly need some thought and would be even
more massive than they currently are. It seemed better to get the main
improvements to groups in first and give the roles and permissions code a bit of
time to settle. It would be nice if they are integrated sensible eventually.

''' Why do I have to deal separately with the case where the module uses groups and the case where it doesn't? Isn't there a clever way to do this so I don't have to? '''

Yes, but I wanted to try and keep people's code fairly readable and make it as
easy as possible to shift current over. In practice you shouldn't really have
too much extra code this way anyhow - you can always write functions with a
groupid argument that defaults to false.

== Future plans? (Things I'd like to do or you can do for me!) ==

In no particular order:

* Bug fixing I guess :-)
* Global groups - I want it to be possible to set up groupings for course 1 and for these to be visible for all course on the site, but not editable or deletable. I think this code should actually be quite easy to write now and I might even do it before this code is put in, just haven't done it yet.
* A nicer user interface (that doesn't break the back button :-) Ajax separates the back and front end of the code really well, so if anyone has good ideas on this, it should be quite easy for someone else to do without having to know how the internals of the groups code work.
* Integration with roles and permissions
* Sign up sheets for groups
* Proper support for blocks and global features.
* A way for modules and blocks to declare whether they support groups or not.
* Putting in search_users functionality for group permissions as well as just members of groups.
* Cool ways to set up groups automatically for particular pedagogical reasons - things like minimising overlap with groups in another grouping, creating groups just from the users all in another group and creating groups which merge pairs of groups from another grouping.

[[Category:Developer]]
[[Category:Groups]]

Development:Groups documentation for module developers

2006-08-21T11:30:27Z

Jvvw: /* The groups library for modules */

== Groups in Moodle for developers==

'''IMPORTANT:''' This documentation does not refer to current versions of Moodle
and is here at the moment purely in order to obtain comments. Descriptions of
how groups work refer to how they hopefully work not how they will work now! This document is also written in the present tense even though it doesn't refer to the current version of Moodle. This is so I don't have to go through and change it all in a month or two's time.

=== How groups work in Moodle ===

It is possible to have groups of users in Moodle. A person with the right
permissions (generally an editting teacher or admin) can create groups for a course and add and remove users from groups. They can also create sets of groups for the course which we'll refer to as 'groupings'. Groups that belong to the course can be added to and removed from any of the groupings that have been created for the course.

If you haven't seen the interface for creating groupings and groups, I'd
recommend you go to a course in your installation of Moodle for which you have
edit access and which has some participants and follow the Groups link and take
a look (''note: you can't currently do this obviously as the code isn't released
yet!'').

Once there is at least one grouping created for a course, when an editor adds an
activity (i.e. an instance of a module) to a course they may if they wish assign one of the groupings for the
course to use with that instance of the module. A user who is not in a group for
a grouping assigned will not be able to see that the instance of the module
exists. It is also possible for the editor to specify a grouping to use for
everything for the course - this is set up in the course settings.

Each group and grouping must 'belong' to at least one course (it's possible for them to belong to more than one course, but there's no user interface to let you do this easily at the moment). Both teachers and students can belong to groups and a user can belong to more than one group. It is also possible for a group to belong to more than one grouping.

There is a choice of various permission settings for a grouping - for instance
you can specify that students may both view and contribute to the group of which
they are a member but only view groups of which they are not members. In time
these settings wil hopefully be superceded by an extension of the roles and
permission system used elsewhere in Moodle, but at the moment they are
independent. The main types of permission that a user can have for a
particular group are 'student view', 'student contribute', 'teacher view' and
'teacher contribute', with it being up to modules to decide how to interpret
these. As we have seen, a user does not need to be a member of a group to have a
particular permission type for that group.

As well as modules, there are also some blocks and global features such as blogs
and the calendar that use groups in certain ways. We'll come to those later.

It is obviously good if modules support groups in the ways that users expect!
This document is here to try and help you do that - if anything isn't clear, you
have questions or can think of improvements to how groups work in Moodle, please
post on the Groups forum on moodle.org.

=== How does this differ from the way groups previously worked? ===

The biggest difference is that previously it was only possible to have one set of groups for a course. All activities for a course had to use the same set of groups, whereas now you can use different sets of groups for different activities. This is the main reason that the API needed to change.

Also, previously, for a course with groups, there were two groups modes - separate and visible. With separate groups, students
could not see groups to which they did not belong, whereas with visible groups they could see groups to which they did not belong but not contribute to them. This caused a great deal of confusion when it came to teachers belonging to groups and also
led to lots of really horrible logic in module code trying to work out who could view or contribute to an activity. This is why the separate/visible groups modes have been replaced by a clearer and more granular permissions system.

Another big difference that isn't obviously visible is there are now tables in the database for course_groups and courses_groupings, whereas previous the groups table had a courseid column. This made it very difficult to use the same group for more than one course. This should now be much easier. However this obviously affects any code that used to access the groups table directly.

There are also improvements to the user interface for creating groups, though these aren't specifically relevant to module developers.

=== How should modules support groups? ===

There are two main ways a module might need to support groups. There may of
course be other more unusual ways in which your module should supports groups,
but these should hopefully be the most common ones. The important thing
is to think about how people would expect your module to behave if they chose to
use groups for it.

==== From a student's point of view ====

From a student's point of view, groups are generally used as a way to enable
parallel versions of the same activity with different groups of students e.g you
might want a separate forum or wiki for each group. If your module is
collaborative in any way (which includes the ability to view the existence of
other students or their contributions) then you need to make sure that this is
supported.

As well as the obvious views of activities being separated, you will need to
make sure that things like searches return the correct results and that teachers
can view the correct groups. You may also need to make a decision as to which
teacher activity is part of the setup of the activity so is the same for every
group and needs to be performed only once, and which teacher activity is the
contribution after the activity has started and so is different for each group.

In general if you module needs to support groups in this way you will find that
the database table(s) where you store the students' contributions will probably
need an extra 'groupid' column, for instance the forum table has a groupid
column.

==== From a teacher's point of view ====

From a teacher's point of view, groups are generally used to manage different
groups of students. For instance there may be several teachers on a course each
assigned to one or more groups of students who mark the work for the groups of
students that have been assigned to them but shouldn't be able to mark the work
of the other groups. A single teacher may also want to be able to view marks for
students by group when they teach the same material to two different classes. In
general, if your module enables teachers to somehow view students' contribution,
then you need to provide this type of support. You can usually do this by
checking which students are in which group rather than needing to alter the
module's database tables in any way.

==== Dealing with users in more than one group ====

Although users may be belong to more than one group, most of the time you can
use the groups library for modules to deal with this rather than having to worry
about this yourself. There will be more about this in the next section. The time
you will probably find that you need to worry about this is when for instance
you are doing a search for contributions that a particular student is allowed to
view. In this case you will need to look for contributions for all the groups
rather than just one group.

=== The groups library for modules ===
The functions at your disposal can be found in course/groups/lib/modulelib.php -
go and have a quick look at it now. (''Again you can't yet, but look here at the [[Groups API for modules]] instead'') Here are some examples of common ways in which you might want to use
the functions in it. Note that modules don't actually need to know anything about groupings directly - the correspondence between an instance of a module and a grouping is taken care of by the library.

1) Present a user with a page containing the right information for one of the
groups that they belong to including a selector to see the equivalent page for
any other groups that they belong to. e.g. present a user with a list of
discussion for a group they belong to.

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_STUDENT_CONTRIBUTE;
groups_m_print_group_selector($cmid, $urlroot, $permissiontype);
$currentgroupid = groups_m_get_selected_group($cmid, $permissiontype);
// This is your function that you've written.
do_whizzy_module_stuff_for_group($cmid, $currentgroupid);
} else {
// Do whatever you'd normally do
}

2) Present a user with search results only for the groups that they are allowed
to view.

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_VIEW;
$groupids = groups_m_get_groups_for_user($cmid, $permissiontype);
// You might want the search funtion to check group permissions too to be
// on the safe side.
get_module_search_results_for_groups($groupids, $maybesomeotherparameters);
} else {
// Do whatever you'd normally do
}

3) Get a list of users which a teacher should be able to mark work

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_TEACHER_CONTRIBUTE;
groups_m_print_group_selector($cmid, $urlroot, $permissiontype);
$groupid = groups_m_get_selected_group($cmid, $permissiontype);
$userids = groups_m_get_members($groupid);
} else {
// Get your userids the normal way
}
// Do whatever you'd normally do with the userids.

It is still ok to use inner joins on the groups_members table in the database
for this type of functionality as obviously this is sometimes required for
performance reasons, but make sure you keep your code that queries the database
clearly separated from your other code.

=== Support for legacy code ===

The following functions should still be supported but are deprecated:

get_groups
user_group
ismember
get_group_users
get_group_students
get_group_teachers
add_user_to_group
mygroupid
groupmode
set_current_group
get_current_group
get_and_set_current_group
setup_and_print_groups

Where appropriate, if a grouping has been specified in the course setting for
use for all activities that grouping will be used in what was previously
'separate groups' mode. If no such grouping has been specified then the first
grouping created for the course that still exists will be used, again in
separate groups mode. If you want better support than this, then I'm afraid you
will need to update the code for your module!

Accessing the groups_members table directly should still work (although it is
not recommended unless you need to do an inner join on it for performance
reasons). Directly accessing the groups table may not work because the course
column has been removed.

The groupid argument in the function search_users from datalib.php will still
work, but will only give members of a group, not those with a specific
permission.

=== Blocks and other special cases ===

There is an essentially identical library for blocks as for modules, only all
the _m_'s in the function names are replaced by _b_'s.

At the moment there is no standard way to set the grouping for a block and most
blocks don't need to use groups. If you want to create a way for someone to set
up a grouping for your block then you will need to do this yourself using the
functions in the other parts of the groups library (under course/groups/lib/)
but ask if you need help. There is a new column in the block_instance table
called groupingid that you will need to set using the function
groups_set_grouping_for_block_instance. If a grouping is set for all activities
for a course then this will get automatically set however.

There are currently two 'global' features in the Moodle core - blogs and the
calendar - a quick word on those in case anyone has plug-ins that provide
similar global features.

Calendar - with the calendar a teacher can set group events when they are within
a course, so basically all they need to do is get all the groups for the course
that a teacher has a particular permission for. Then when displaying calendar
entries to users, need to know which groups a particular has view permission
for across all courses though it's a tiny bit more complicated that this because
a grouping can be used for more than one course and someone may be a student on
one course and a teacher on another.

Blog - It's possible for the admin to set a blog option that makes blogs view
access group level. This means that users can only see blogs of people that they
share a group with for some course - there's a function provided in one of the
main groups libraries to find out if two users share a group. I'm guessing that
you're mostly only wanting to use this with installations with a very small
number of teachers and at some point global groups will get used here instead.

At the moment there is generally no general support for global features, but
this will hopefully come!

== Some rationale ==

I'll probably add stuff in here as it comes up :-)

''' Why doesn't this fit in with roles and permissions? '''

Mostly at the time I started doing this development the roles and permission
code wasn't available yet! The changes to roles and permissions are big and the
changes needed to fit in with them properly need some thought and would be even
more massive than they currently are. It seemed better to get the main
improvements to groups in first and give the roles and permissions code a bit of
time to settle. It would be nice if they are integrated sensible eventually.

''' Why do I have to deal separately with the case where the module uses groups and the case where it doesn't? Isn't there a clever way to do this so I don't have to? '''

Yes, but I wanted to try and keep people's code fairly readable and make it as
easy as possible to shift current over. In practice you shouldn't really have
too much extra code this way anyhow - you can always write functions with a
groupid argument that defaults to false.

== Future plans? (Things I'd like to do or you can do for me!) ==

In no particular order:

* Bug fixing I guess :-)
* Global groups - I want it to be possible to set up groupings for course 1 and for these to be visible for all course on the site, but not editable or deletable. I think this code should actually be quite easy to write now and I might even do it before this code is put in, just haven't done it yet.
* A nicer user interface (that doesn't break the back button :-) Ajax separates the back and front end of the code really well, so if anyone has good ideas on this, it should be quite easy for someone else to do without having to know how the internals of the groups code work.
* Integration with roles and permissions
* Sign up sheets for groups
* Proper support for blocks and global features.
* A way for modules and blocks to declare whether they support groups or not.
* Putting in search_users functionality for group permissions as well as just members of groups.
* Cool ways to set up groups automatically for particular pedagogical reasons - things like minimising overlap with groups in another grouping, creating groups just from the users all in another group and creating groups which merge pairs of groups from another grouping.

Development:Groups documentation for module developers

2006-08-21T11:30:08Z

Jvvw: /* The groups library for modules */

== Groups in Moodle for developers==

'''IMPORTANT:''' This documentation does not refer to current versions of Moodle
and is here at the moment purely in order to obtain comments. Descriptions of
how groups work refer to how they hopefully work not how they will work now! This document is also written in the present tense even though it doesn't refer to the current version of Moodle. This is so I don't have to go through and change it all in a month or two's time.

=== How groups work in Moodle ===

It is possible to have groups of users in Moodle. A person with the right
permissions (generally an editting teacher or admin) can create groups for a course and add and remove users from groups. They can also create sets of groups for the course which we'll refer to as 'groupings'. Groups that belong to the course can be added to and removed from any of the groupings that have been created for the course.

If you haven't seen the interface for creating groupings and groups, I'd
recommend you go to a course in your installation of Moodle for which you have
edit access and which has some participants and follow the Groups link and take
a look (''note: you can't currently do this obviously as the code isn't released
yet!'').

Once there is at least one grouping created for a course, when an editor adds an
activity (i.e. an instance of a module) to a course they may if they wish assign one of the groupings for the
course to use with that instance of the module. A user who is not in a group for
a grouping assigned will not be able to see that the instance of the module
exists. It is also possible for the editor to specify a grouping to use for
everything for the course - this is set up in the course settings.

Each group and grouping must 'belong' to at least one course (it's possible for them to belong to more than one course, but there's no user interface to let you do this easily at the moment). Both teachers and students can belong to groups and a user can belong to more than one group. It is also possible for a group to belong to more than one grouping.

There is a choice of various permission settings for a grouping - for instance
you can specify that students may both view and contribute to the group of which
they are a member but only view groups of which they are not members. In time
these settings wil hopefully be superceded by an extension of the roles and
permission system used elsewhere in Moodle, but at the moment they are
independent. The main types of permission that a user can have for a
particular group are 'student view', 'student contribute', 'teacher view' and
'teacher contribute', with it being up to modules to decide how to interpret
these. As we have seen, a user does not need to be a member of a group to have a
particular permission type for that group.

As well as modules, there are also some blocks and global features such as blogs
and the calendar that use groups in certain ways. We'll come to those later.

It is obviously good if modules support groups in the ways that users expect!
This document is here to try and help you do that - if anything isn't clear, you
have questions or can think of improvements to how groups work in Moodle, please
post on the Groups forum on moodle.org.

=== How does this differ from the way groups previously worked? ===

The biggest difference is that previously it was only possible to have one set of groups for a course. All activities for a course had to use the same set of groups, whereas now you can use different sets of groups for different activities. This is the main reason that the API needed to change.

Also, previously, for a course with groups, there were two groups modes - separate and visible. With separate groups, students
could not see groups to which they did not belong, whereas with visible groups they could see groups to which they did not belong but not contribute to them. This caused a great deal of confusion when it came to teachers belonging to groups and also
led to lots of really horrible logic in module code trying to work out who could view or contribute to an activity. This is why the separate/visible groups modes have been replaced by a clearer and more granular permissions system.

Another big difference that isn't obviously visible is there are now tables in the database for course_groups and courses_groupings, whereas previous the groups table had a courseid column. This made it very difficult to use the same group for more than one course. This should now be much easier. However this obviously affects any code that used to access the groups table directly.

There are also improvements to the user interface for creating groups, though these aren't specifically relevant to module developers.

=== How should modules support groups? ===

There are two main ways a module might need to support groups. There may of
course be other more unusual ways in which your module should supports groups,
but these should hopefully be the most common ones. The important thing
is to think about how people would expect your module to behave if they chose to
use groups for it.

==== From a student's point of view ====

From a student's point of view, groups are generally used as a way to enable
parallel versions of the same activity with different groups of students e.g you
might want a separate forum or wiki for each group. If your module is
collaborative in any way (which includes the ability to view the existence of
other students or their contributions) then you need to make sure that this is
supported.

As well as the obvious views of activities being separated, you will need to
make sure that things like searches return the correct results and that teachers
can view the correct groups. You may also need to make a decision as to which
teacher activity is part of the setup of the activity so is the same for every
group and needs to be performed only once, and which teacher activity is the
contribution after the activity has started and so is different for each group.

In general if you module needs to support groups in this way you will find that
the database table(s) where you store the students' contributions will probably
need an extra 'groupid' column, for instance the forum table has a groupid
column.

==== From a teacher's point of view ====

From a teacher's point of view, groups are generally used to manage different
groups of students. For instance there may be several teachers on a course each
assigned to one or more groups of students who mark the work for the groups of
students that have been assigned to them but shouldn't be able to mark the work
of the other groups. A single teacher may also want to be able to view marks for
students by group when they teach the same material to two different classes. In
general, if your module enables teachers to somehow view students' contribution,
then you need to provide this type of support. You can usually do this by
checking which students are in which group rather than needing to alter the
module's database tables in any way.

==== Dealing with users in more than one group ====

Although users may be belong to more than one group, most of the time you can
use the groups library for modules to deal with this rather than having to worry
about this yourself. There will be more about this in the next section. The time
you will probably find that you need to worry about this is when for instance
you are doing a search for contributions that a particular student is allowed to
view. In this case you will need to look for contributions for all the groups
rather than just one group.

=== The groups library for modules ===
The functions at your disposal can be found in course/groups/lib/modulelib.php -
go and have a quick look at it now. (''Again you can't yet, but look here
at the'' [[Groups API for modules]] ''instead'') Here are some examples of common ways in which you might want to use
the functions in it. Note that modules don't actually need to know anything about groupings directly - the correspondence between an instance of a module and a grouping is taken care of by the library.

1) Present a user with a page containing the right information for one of the
groups that they belong to including a selector to see the equivalent page for
any other groups that they belong to. e.g. present a user with a list of
discussion for a group they belong to.

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_STUDENT_CONTRIBUTE;
groups_m_print_group_selector($cmid, $urlroot, $permissiontype);
$currentgroupid = groups_m_get_selected_group($cmid, $permissiontype);
// This is your function that you've written.
do_whizzy_module_stuff_for_group($cmid, $currentgroupid);
} else {
// Do whatever you'd normally do
}

2) Present a user with search results only for the groups that they are allowed
to view.

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_VIEW;
$groupids = groups_m_get_groups_for_user($cmid, $permissiontype);
// You might want the search funtion to check group permissions too to be
// on the safe side.
get_module_search_results_for_groups($groupids, $maybesomeotherparameters);
} else {
// Do whatever you'd normally do
}

3) Get a list of users which a teacher should be able to mark work

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_TEACHER_CONTRIBUTE;
groups_m_print_group_selector($cmid, $urlroot, $permissiontype);
$groupid = groups_m_get_selected_group($cmid, $permissiontype);
$userids = groups_m_get_members($groupid);
} else {
// Get your userids the normal way
}
// Do whatever you'd normally do with the userids.

It is still ok to use inner joins on the groups_members table in the database
for this type of functionality as obviously this is sometimes required for
performance reasons, but make sure you keep your code that queries the database
clearly separated from your other code.

=== Support for legacy code ===

The following functions should still be supported but are deprecated:

get_groups
user_group
ismember
get_group_users
get_group_students
get_group_teachers
add_user_to_group
mygroupid
groupmode
set_current_group
get_current_group
get_and_set_current_group
setup_and_print_groups

Where appropriate, if a grouping has been specified in the course setting for
use for all activities that grouping will be used in what was previously
'separate groups' mode. If no such grouping has been specified then the first
grouping created for the course that still exists will be used, again in
separate groups mode. If you want better support than this, then I'm afraid you
will need to update the code for your module!

Accessing the groups_members table directly should still work (although it is
not recommended unless you need to do an inner join on it for performance
reasons). Directly accessing the groups table may not work because the course
column has been removed.

The groupid argument in the function search_users from datalib.php will still
work, but will only give members of a group, not those with a specific
permission.

=== Blocks and other special cases ===

There is an essentially identical library for blocks as for modules, only all
the _m_'s in the function names are replaced by _b_'s.

At the moment there is no standard way to set the grouping for a block and most
blocks don't need to use groups. If you want to create a way for someone to set
up a grouping for your block then you will need to do this yourself using the
functions in the other parts of the groups library (under course/groups/lib/)
but ask if you need help. There is a new column in the block_instance table
called groupingid that you will need to set using the function
groups_set_grouping_for_block_instance. If a grouping is set for all activities
for a course then this will get automatically set however.

There are currently two 'global' features in the Moodle core - blogs and the
calendar - a quick word on those in case anyone has plug-ins that provide
similar global features.

Calendar - with the calendar a teacher can set group events when they are within
a course, so basically all they need to do is get all the groups for the course
that a teacher has a particular permission for. Then when displaying calendar
entries to users, need to know which groups a particular has view permission
for across all courses though it's a tiny bit more complicated that this because
a grouping can be used for more than one course and someone may be a student on
one course and a teacher on another.

Blog - It's possible for the admin to set a blog option that makes blogs view
access group level. This means that users can only see blogs of people that they
share a group with for some course - there's a function provided in one of the
main groups libraries to find out if two users share a group. I'm guessing that
you're mostly only wanting to use this with installations with a very small
number of teachers and at some point global groups will get used here instead.

At the moment there is generally no general support for global features, but
this will hopefully come!

== Some rationale ==

I'll probably add stuff in here as it comes up :-)

''' Why doesn't this fit in with roles and permissions? '''

Mostly at the time I started doing this development the roles and permission
code wasn't available yet! The changes to roles and permissions are big and the
changes needed to fit in with them properly need some thought and would be even
more massive than they currently are. It seemed better to get the main
improvements to groups in first and give the roles and permissions code a bit of
time to settle. It would be nice if they are integrated sensible eventually.

''' Why do I have to deal separately with the case where the module uses groups and the case where it doesn't? Isn't there a clever way to do this so I don't have to? '''

Yes, but I wanted to try and keep people's code fairly readable and make it as
easy as possible to shift current over. In practice you shouldn't really have
too much extra code this way anyhow - you can always write functions with a
groupid argument that defaults to false.

== Future plans? (Things I'd like to do or you can do for me!) ==

In no particular order:

* Bug fixing I guess :-)
* Global groups - I want it to be possible to set up groupings for course 1 and for these to be visible for all course on the site, but not editable or deletable. I think this code should actually be quite easy to write now and I might even do it before this code is put in, just haven't done it yet.
* A nicer user interface (that doesn't break the back button :-) Ajax separates the back and front end of the code really well, so if anyone has good ideas on this, it should be quite easy for someone else to do without having to know how the internals of the groups code work.
* Integration with roles and permissions
* Sign up sheets for groups
* Proper support for blocks and global features.
* A way for modules and blocks to declare whether they support groups or not.
* Putting in search_users functionality for group permissions as well as just members of groups.
* Cool ways to set up groups automatically for particular pedagogical reasons - things like minimising overlap with groups in another grouping, creating groups just from the users all in another group and creating groups which merge pairs of groups from another grouping.

Development:Groups documentation for module developers

2006-08-21T11:29:53Z

Jvvw: /* The groups library for modules */

== Groups in Moodle for developers==

'''IMPORTANT:''' This documentation does not refer to current versions of Moodle
and is here at the moment purely in order to obtain comments. Descriptions of
how groups work refer to how they hopefully work not how they will work now! This document is also written in the present tense even though it doesn't refer to the current version of Moodle. This is so I don't have to go through and change it all in a month or two's time.

=== How groups work in Moodle ===

It is possible to have groups of users in Moodle. A person with the right
permissions (generally an editting teacher or admin) can create groups for a course and add and remove users from groups. They can also create sets of groups for the course which we'll refer to as 'groupings'. Groups that belong to the course can be added to and removed from any of the groupings that have been created for the course.

If you haven't seen the interface for creating groupings and groups, I'd
recommend you go to a course in your installation of Moodle for which you have
edit access and which has some participants and follow the Groups link and take
a look (''note: you can't currently do this obviously as the code isn't released
yet!'').

Once there is at least one grouping created for a course, when an editor adds an
activity (i.e. an instance of a module) to a course they may if they wish assign one of the groupings for the
course to use with that instance of the module. A user who is not in a group for
a grouping assigned will not be able to see that the instance of the module
exists. It is also possible for the editor to specify a grouping to use for
everything for the course - this is set up in the course settings.

Each group and grouping must 'belong' to at least one course (it's possible for them to belong to more than one course, but there's no user interface to let you do this easily at the moment). Both teachers and students can belong to groups and a user can belong to more than one group. It is also possible for a group to belong to more than one grouping.

There is a choice of various permission settings for a grouping - for instance
you can specify that students may both view and contribute to the group of which
they are a member but only view groups of which they are not members. In time
these settings wil hopefully be superceded by an extension of the roles and
permission system used elsewhere in Moodle, but at the moment they are
independent. The main types of permission that a user can have for a
particular group are 'student view', 'student contribute', 'teacher view' and
'teacher contribute', with it being up to modules to decide how to interpret
these. As we have seen, a user does not need to be a member of a group to have a
particular permission type for that group.

As well as modules, there are also some blocks and global features such as blogs
and the calendar that use groups in certain ways. We'll come to those later.

It is obviously good if modules support groups in the ways that users expect!
This document is here to try and help you do that - if anything isn't clear, you
have questions or can think of improvements to how groups work in Moodle, please
post on the Groups forum on moodle.org.

=== How does this differ from the way groups previously worked? ===

The biggest difference is that previously it was only possible to have one set of groups for a course. All activities for a course had to use the same set of groups, whereas now you can use different sets of groups for different activities. This is the main reason that the API needed to change.

Also, previously, for a course with groups, there were two groups modes - separate and visible. With separate groups, students
could not see groups to which they did not belong, whereas with visible groups they could see groups to which they did not belong but not contribute to them. This caused a great deal of confusion when it came to teachers belonging to groups and also
led to lots of really horrible logic in module code trying to work out who could view or contribute to an activity. This is why the separate/visible groups modes have been replaced by a clearer and more granular permissions system.

Another big difference that isn't obviously visible is there are now tables in the database for course_groups and courses_groupings, whereas previous the groups table had a courseid column. This made it very difficult to use the same group for more than one course. This should now be much easier. However this obviously affects any code that used to access the groups table directly.

There are also improvements to the user interface for creating groups, though these aren't specifically relevant to module developers.

=== How should modules support groups? ===

There are two main ways a module might need to support groups. There may of
course be other more unusual ways in which your module should supports groups,
but these should hopefully be the most common ones. The important thing
is to think about how people would expect your module to behave if they chose to
use groups for it.

==== From a student's point of view ====

From a student's point of view, groups are generally used as a way to enable
parallel versions of the same activity with different groups of students e.g you
might want a separate forum or wiki for each group. If your module is
collaborative in any way (which includes the ability to view the existence of
other students or their contributions) then you need to make sure that this is
supported.

As well as the obvious views of activities being separated, you will need to
make sure that things like searches return the correct results and that teachers
can view the correct groups. You may also need to make a decision as to which
teacher activity is part of the setup of the activity so is the same for every
group and needs to be performed only once, and which teacher activity is the
contribution after the activity has started and so is different for each group.

In general if you module needs to support groups in this way you will find that
the database table(s) where you store the students' contributions will probably
need an extra 'groupid' column, for instance the forum table has a groupid
column.

==== From a teacher's point of view ====

From a teacher's point of view, groups are generally used to manage different
groups of students. For instance there may be several teachers on a course each
assigned to one or more groups of students who mark the work for the groups of
students that have been assigned to them but shouldn't be able to mark the work
of the other groups. A single teacher may also want to be able to view marks for
students by group when they teach the same material to two different classes. In
general, if your module enables teachers to somehow view students' contribution,
then you need to provide this type of support. You can usually do this by
checking which students are in which group rather than needing to alter the
module's database tables in any way.

==== Dealing with users in more than one group ====

Although users may be belong to more than one group, most of the time you can
use the groups library for modules to deal with this rather than having to worry
about this yourself. There will be more about this in the next section. The time
you will probably find that you need to worry about this is when for instance
you are doing a search for contributions that a particular student is allowed to
view. In this case you will need to look for contributions for all the groups
rather than just one group.

=== The groups library for modules ===
The functions at your disposal can be found in course/groups/lib/modulelib.php -
go and have a quick look at it now. (''Again you can't yet, but look here
at the [[Groups API for modules]] instead'') Here are some examples of common ways in which you might want to use
the functions in it. Note that modules don't actually need to know anything about groupings directly - the correspondence between an instance of a module and a grouping is taken care of by the library.

1) Present a user with a page containing the right information for one of the
groups that they belong to including a selector to see the equivalent page for
any other groups that they belong to. e.g. present a user with a list of
discussion for a group they belong to.

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_STUDENT_CONTRIBUTE;
groups_m_print_group_selector($cmid, $urlroot, $permissiontype);
$currentgroupid = groups_m_get_selected_group($cmid, $permissiontype);
// This is your function that you've written.
do_whizzy_module_stuff_for_group($cmid, $currentgroupid);
} else {
// Do whatever you'd normally do
}

2) Present a user with search results only for the groups that they are allowed
to view.

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_VIEW;
$groupids = groups_m_get_groups_for_user($cmid, $permissiontype);
// You might want the search funtion to check group permissions too to be
// on the safe side.
get_module_search_results_for_groups($groupids, $maybesomeotherparameters);
} else {
// Do whatever you'd normally do
}

3) Get a list of users which a teacher should be able to mark work

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_TEACHER_CONTRIBUTE;
groups_m_print_group_selector($cmid, $urlroot, $permissiontype);
$groupid = groups_m_get_selected_group($cmid, $permissiontype);
$userids = groups_m_get_members($groupid);
} else {
// Get your userids the normal way
}
// Do whatever you'd normally do with the userids.

It is still ok to use inner joins on the groups_members table in the database
for this type of functionality as obviously this is sometimes required for
performance reasons, but make sure you keep your code that queries the database
clearly separated from your other code.

=== Support for legacy code ===

The following functions should still be supported but are deprecated:

get_groups
user_group
ismember
get_group_users
get_group_students
get_group_teachers
add_user_to_group
mygroupid
groupmode
set_current_group
get_current_group
get_and_set_current_group
setup_and_print_groups

Where appropriate, if a grouping has been specified in the course setting for
use for all activities that grouping will be used in what was previously
'separate groups' mode. If no such grouping has been specified then the first
grouping created for the course that still exists will be used, again in
separate groups mode. If you want better support than this, then I'm afraid you
will need to update the code for your module!

Accessing the groups_members table directly should still work (although it is
not recommended unless you need to do an inner join on it for performance
reasons). Directly accessing the groups table may not work because the course
column has been removed.

The groupid argument in the function search_users from datalib.php will still
work, but will only give members of a group, not those with a specific
permission.

=== Blocks and other special cases ===

There is an essentially identical library for blocks as for modules, only all
the _m_'s in the function names are replaced by _b_'s.

At the moment there is no standard way to set the grouping for a block and most
blocks don't need to use groups. If you want to create a way for someone to set
up a grouping for your block then you will need to do this yourself using the
functions in the other parts of the groups library (under course/groups/lib/)
but ask if you need help. There is a new column in the block_instance table
called groupingid that you will need to set using the function
groups_set_grouping_for_block_instance. If a grouping is set for all activities
for a course then this will get automatically set however.

There are currently two 'global' features in the Moodle core - blogs and the
calendar - a quick word on those in case anyone has plug-ins that provide
similar global features.

Calendar - with the calendar a teacher can set group events when they are within
a course, so basically all they need to do is get all the groups for the course
that a teacher has a particular permission for. Then when displaying calendar
entries to users, need to know which groups a particular has view permission
for across all courses though it's a tiny bit more complicated that this because
a grouping can be used for more than one course and someone may be a student on
one course and a teacher on another.

Blog - It's possible for the admin to set a blog option that makes blogs view
access group level. This means that users can only see blogs of people that they
share a group with for some course - there's a function provided in one of the
main groups libraries to find out if two users share a group. I'm guessing that
you're mostly only wanting to use this with installations with a very small
number of teachers and at some point global groups will get used here instead.

At the moment there is generally no general support for global features, but
this will hopefully come!

== Some rationale ==

I'll probably add stuff in here as it comes up :-)

''' Why doesn't this fit in with roles and permissions? '''

Mostly at the time I started doing this development the roles and permission
code wasn't available yet! The changes to roles and permissions are big and the
changes needed to fit in with them properly need some thought and would be even
more massive than they currently are. It seemed better to get the main
improvements to groups in first and give the roles and permissions code a bit of
time to settle. It would be nice if they are integrated sensible eventually.

''' Why do I have to deal separately with the case where the module uses groups and the case where it doesn't? Isn't there a clever way to do this so I don't have to? '''

Yes, but I wanted to try and keep people's code fairly readable and make it as
easy as possible to shift current over. In practice you shouldn't really have
too much extra code this way anyhow - you can always write functions with a
groupid argument that defaults to false.

== Future plans? (Things I'd like to do or you can do for me!) ==

In no particular order:

* Bug fixing I guess :-)
* Global groups - I want it to be possible to set up groupings for course 1 and for these to be visible for all course on the site, but not editable or deletable. I think this code should actually be quite easy to write now and I might even do it before this code is put in, just haven't done it yet.
* A nicer user interface (that doesn't break the back button :-) Ajax separates the back and front end of the code really well, so if anyone has good ideas on this, it should be quite easy for someone else to do without having to know how the internals of the groups code work.
* Integration with roles and permissions
* Sign up sheets for groups
* Proper support for blocks and global features.
* A way for modules and blocks to declare whether they support groups or not.
* Putting in search_users functionality for group permissions as well as just members of groups.
* Cool ways to set up groups automatically for particular pedagogical reasons - things like minimising overlap with groups in another grouping, creating groups just from the users all in another group and creating groups which merge pairs of groups from another grouping.

Development:Groups documentation for module developers

2006-08-21T11:28:10Z

Jvvw: /* How does this differ from the way groups previously worked? */

== Groups in Moodle for developers==

'''IMPORTANT:''' This documentation does not refer to current versions of Moodle
and is here at the moment purely in order to obtain comments. Descriptions of
how groups work refer to how they hopefully work not how they will work now! This document is also written in the present tense even though it doesn't refer to the current version of Moodle. This is so I don't have to go through and change it all in a month or two's time.

=== How groups work in Moodle ===

It is possible to have groups of users in Moodle. A person with the right
permissions (generally an editting teacher or admin) can create groups for a course and add and remove users from groups. They can also create sets of groups for the course which we'll refer to as 'groupings'. Groups that belong to the course can be added to and removed from any of the groupings that have been created for the course.

If you haven't seen the interface for creating groupings and groups, I'd
recommend you go to a course in your installation of Moodle for which you have
edit access and which has some participants and follow the Groups link and take
a look (''note: you can't currently do this obviously as the code isn't released
yet!'').

Once there is at least one grouping created for a course, when an editor adds an
activity (i.e. an instance of a module) to a course they may if they wish assign one of the groupings for the
course to use with that instance of the module. A user who is not in a group for
a grouping assigned will not be able to see that the instance of the module
exists. It is also possible for the editor to specify a grouping to use for
everything for the course - this is set up in the course settings.

Each group and grouping must 'belong' to at least one course (it's possible for them to belong to more than one course, but there's no user interface to let you do this easily at the moment). Both teachers and students can belong to groups and a user can belong to more than one group. It is also possible for a group to belong to more than one grouping.

There is a choice of various permission settings for a grouping - for instance
you can specify that students may both view and contribute to the group of which
they are a member but only view groups of which they are not members. In time
these settings wil hopefully be superceded by an extension of the roles and
permission system used elsewhere in Moodle, but at the moment they are
independent. The main types of permission that a user can have for a
particular group are 'student view', 'student contribute', 'teacher view' and
'teacher contribute', with it being up to modules to decide how to interpret
these. As we have seen, a user does not need to be a member of a group to have a
particular permission type for that group.

As well as modules, there are also some blocks and global features such as blogs
and the calendar that use groups in certain ways. We'll come to those later.

It is obviously good if modules support groups in the ways that users expect!
This document is here to try and help you do that - if anything isn't clear, you
have questions or can think of improvements to how groups work in Moodle, please
post on the Groups forum on moodle.org.

=== How does this differ from the way groups previously worked? ===

The biggest difference is that previously it was only possible to have one set of groups for a course. All activities for a course had to use the same set of groups, whereas now you can use different sets of groups for different activities. This is the main reason that the API needed to change.

Also, previously, for a course with groups, there were two groups modes - separate and visible. With separate groups, students
could not see groups to which they did not belong, whereas with visible groups they could see groups to which they did not belong but not contribute to them. This caused a great deal of confusion when it came to teachers belonging to groups and also
led to lots of really horrible logic in module code trying to work out who could view or contribute to an activity. This is why the separate/visible groups modes have been replaced by a clearer and more granular permissions system.

Another big difference that isn't obviously visible is there are now tables in the database for course_groups and courses_groupings, whereas previous the groups table had a courseid column. This made it very difficult to use the same group for more than one course. This should now be much easier. However this obviously affects any code that used to access the groups table directly.

There are also improvements to the user interface for creating groups, though these aren't specifically relevant to module developers.

=== How should modules support groups? ===

There are two main ways a module might need to support groups. There may of
course be other more unusual ways in which your module should supports groups,
but these should hopefully be the most common ones. The important thing
is to think about how people would expect your module to behave if they chose to
use groups for it.

==== From a student's point of view ====

From a student's point of view, groups are generally used as a way to enable
parallel versions of the same activity with different groups of students e.g you
might want a separate forum or wiki for each group. If your module is
collaborative in any way (which includes the ability to view the existence of
other students or their contributions) then you need to make sure that this is
supported.

As well as the obvious views of activities being separated, you will need to
make sure that things like searches return the correct results and that teachers
can view the correct groups. You may also need to make a decision as to which
teacher activity is part of the setup of the activity so is the same for every
group and needs to be performed only once, and which teacher activity is the
contribution after the activity has started and so is different for each group.

In general if you module needs to support groups in this way you will find that
the database table(s) where you store the students' contributions will probably
need an extra 'groupid' column, for instance the forum table has a groupid
column.

==== From a teacher's point of view ====

From a teacher's point of view, groups are generally used to manage different
groups of students. For instance there may be several teachers on a course each
assigned to one or more groups of students who mark the work for the groups of
students that have been assigned to them but shouldn't be able to mark the work
of the other groups. A single teacher may also want to be able to view marks for
students by group when they teach the same material to two different classes. In
general, if your module enables teachers to somehow view students' contribution,
then you need to provide this type of support. You can usually do this by
checking which students are in which group rather than needing to alter the
module's database tables in any way.

==== Dealing with users in more than one group ====

Although users may be belong to more than one group, most of the time you can
use the groups library for modules to deal with this rather than having to worry
about this yourself. There will be more about this in the next section. The time
you will probably find that you need to worry about this is when for instance
you are doing a search for contributions that a particular student is allowed to
view. In this case you will need to look for contributions for all the groups
rather than just one group.

=== The groups library for modules ===
The functions at your disposal can be found in course/groups/lib/modulelib.php -
go and have a quick look at it now. (''Again you can't yet, but look here
at the [[Groups API for modules]] instead'') Here are some examples of common ways in which you might want to use
the functions in it.

1) Present a user with a page containing the right information for one of the
groups that they belong to including a selector to see the equivalent page for
any other groups that they belong to. e.g. present a user with a list of
discussion for a group they belong to.

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_STUDENT_CONTRIBUTE;
groups_m_print_group_selector($cmid, $urlroot, $permissiontype);
$currentgroupid = groups_m_get_selected_group($cmid, $permissiontype);
// This is your function that you've written.
do_whizzy_module_stuff_for_group($cmid, $currentgroupid);
} else {
// Do whatever you'd normally do
}

2) Present a user with search results only for the groups that they are allowed
to view.

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_VIEW;
$groupids = groups_m_get_groups_for_user($cmid, $permissiontype);
// You might want the search funtion to check group permissions too to be
// on the safe side.
get_module_search_results_for_groups($groupids, $maybesomeotherparameters);
} else {
// Do whatever you'd normally do
}

3) Get a list of users which a teacher should be able to mark work

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_TEACHER_CONTRIBUTE;
groups_m_print_group_selector($cmid, $urlroot, $permissiontype);
$groupid = groups_m_get_selected_group($cmid, $permissiontype);
$userids = groups_m_get_members($groupid);
} else {
// Get your userids the normal way
}
// Do whatever you'd normally do with the userids.

It is still ok to use inner joins on the groups_members table in the database
for this type of functionality as obviously this is sometimes required for
performance reasons, but make sure you keep your code that queries the database
clearly separated from your other code.

=== Support for legacy code ===

The following functions should still be supported but are deprecated:

get_groups
user_group
ismember
get_group_users
get_group_students
get_group_teachers
add_user_to_group
mygroupid
groupmode
set_current_group
get_current_group
get_and_set_current_group
setup_and_print_groups

Where appropriate, if a grouping has been specified in the course setting for
use for all activities that grouping will be used in what was previously
'separate groups' mode. If no such grouping has been specified then the first
grouping created for the course that still exists will be used, again in
separate groups mode. If you want better support than this, then I'm afraid you
will need to update the code for your module!

Accessing the groups_members table directly should still work (although it is
not recommended unless you need to do an inner join on it for performance
reasons). Directly accessing the groups table may not work because the course
column has been removed.

The groupid argument in the function search_users from datalib.php will still
work, but will only give members of a group, not those with a specific
permission.

=== Blocks and other special cases ===

There is an essentially identical library for blocks as for modules, only all
the _m_'s in the function names are replaced by _b_'s.

At the moment there is no standard way to set the grouping for a block and most
blocks don't need to use groups. If you want to create a way for someone to set
up a grouping for your block then you will need to do this yourself using the
functions in the other parts of the groups library (under course/groups/lib/)
but ask if you need help. There is a new column in the block_instance table
called groupingid that you will need to set using the function
groups_set_grouping_for_block_instance. If a grouping is set for all activities
for a course then this will get automatically set however.

There are currently two 'global' features in the Moodle core - blogs and the
calendar - a quick word on those in case anyone has plug-ins that provide
similar global features.

Calendar - with the calendar a teacher can set group events when they are within
a course, so basically all they need to do is get all the groups for the course
that a teacher has a particular permission for. Then when displaying calendar
entries to users, need to know which groups a particular has view permission
for across all courses though it's a tiny bit more complicated that this because
a grouping can be used for more than one course and someone may be a student on
one course and a teacher on another.

Blog - It's possible for the admin to set a blog option that makes blogs view
access group level. This means that users can only see blogs of people that they
share a group with for some course - there's a function provided in one of the
main groups libraries to find out if two users share a group. I'm guessing that
you're mostly only wanting to use this with installations with a very small
number of teachers and at some point global groups will get used here instead.

At the moment there is generally no general support for global features, but
this will hopefully come!

== Some rationale ==

I'll probably add stuff in here as it comes up :-)

''' Why doesn't this fit in with roles and permissions? '''

Mostly at the time I started doing this development the roles and permission
code wasn't available yet! The changes to roles and permissions are big and the
changes needed to fit in with them properly need some thought and would be even
more massive than they currently are. It seemed better to get the main
improvements to groups in first and give the roles and permissions code a bit of
time to settle. It would be nice if they are integrated sensible eventually.

''' Why do I have to deal separately with the case where the module uses groups and the case where it doesn't? Isn't there a clever way to do this so I don't have to? '''

Yes, but I wanted to try and keep people's code fairly readable and make it as
easy as possible to shift current over. In practice you shouldn't really have
too much extra code this way anyhow - you can always write functions with a
groupid argument that defaults to false.

== Future plans? (Things I'd like to do or you can do for me!) ==

In no particular order:

* Bug fixing I guess :-)
* Global groups - I want it to be possible to set up groupings for course 1 and for these to be visible for all course on the site, but not editable or deletable. I think this code should actually be quite easy to write now and I might even do it before this code is put in, just haven't done it yet.
* A nicer user interface (that doesn't break the back button :-) Ajax separates the back and front end of the code really well, so if anyone has good ideas on this, it should be quite easy for someone else to do without having to know how the internals of the groups code work.
* Integration with roles and permissions
* Sign up sheets for groups
* Proper support for blocks and global features.
* A way for modules and blocks to declare whether they support groups or not.
* Putting in search_users functionality for group permissions as well as just members of groups.
* Cool ways to set up groups automatically for particular pedagogical reasons - things like minimising overlap with groups in another grouping, creating groups just from the users all in another group and creating groups which merge pairs of groups from another grouping.

Development:Groups documentation for module developers

2006-08-21T11:24:11Z

Jvvw: /* How groups work in Moodle */

== Groups in Moodle for developers==

'''IMPORTANT:''' This documentation does not refer to current versions of Moodle
and is here at the moment purely in order to obtain comments. Descriptions of
how groups work refer to how they hopefully work not how they will work now! This document is also written in the present tense even though it doesn't refer to the current version of Moodle. This is so I don't have to go through and change it all in a month or two's time.

=== How groups work in Moodle ===

It is possible to have groups of users in Moodle. A person with the right
permissions (generally an editting teacher or admin) can create groups for a course and add and remove users from groups. They can also create sets of groups for the course which we'll refer to as 'groupings'. Groups that belong to the course can be added to and removed from any of the groupings that have been created for the course.

If you haven't seen the interface for creating groupings and groups, I'd
recommend you go to a course in your installation of Moodle for which you have
edit access and which has some participants and follow the Groups link and take
a look (''note: you can't currently do this obviously as the code isn't released
yet!'').

Once there is at least one grouping created for a course, when an editor adds an
activity (i.e. an instance of a module) to a course they may if they wish assign one of the groupings for the
course to use with that instance of the module. A user who is not in a group for
a grouping assigned will not be able to see that the instance of the module
exists. It is also possible for the editor to specify a grouping to use for
everything for the course - this is set up in the course settings.

Each group and grouping must 'belong' to at least one course (it's possible for them to belong to more than one course, but there's no user interface to let you do this easily at the moment). Both teachers and students can belong to groups and a user can belong to more than one group. It is also possible for a group to belong to more than one grouping.

There is a choice of various permission settings for a grouping - for instance
you can specify that students may both view and contribute to the group of which
they are a member but only view groups of which they are not members. In time
these settings wil hopefully be superceded by an extension of the roles and
permission system used elsewhere in Moodle, but at the moment they are
independent. The main types of permission that a user can have for a
particular group are 'student view', 'student contribute', 'teacher view' and
'teacher contribute', with it being up to modules to decide how to interpret
these. As we have seen, a user does not need to be a member of a group to have a
particular permission type for that group.

As well as modules, there are also some blocks and global features such as blogs
and the calendar that use groups in certain ways. We'll come to those later.

It is obviously good if modules support groups in the ways that users expect!
This document is here to try and help you do that - if anything isn't clear, you
have questions or can think of improvements to how groups work in Moodle, please
post on the Groups forum on moodle.org.

=== How does this differ from the way groups previously worked? ===

The biggest difference is that previously it was only possible to have one set of groups for a course. All activities for a course had to use the same set of groups. This is the main reason that the API needed to change.

Also, previously, for a course with groups, there were two groups modes - separate and visible. With separate groups, students
could not see groups to which they did not belong, whereas with visible groups they could see groups to which they did not belong but not contribute to them. This caused a great deal of confusion when it came to teachers belonging to groups and also
led to lots of really horrible logic in module code trying to work out who could view or contribute to an activity. This is why the separate/visible groups modes have been replaced by a more granular and flexible permissions system.

Another big difference that isn't visible is there are now tables in the database for course_groups and courses_groupings, whereas previous the groups table had a courseid column. This made it very difficult to use the same group for more than one course. This should now be much easier. However this obviously affects code that used to access the groups table directly.

There are also improvements to the user interface for creating groups, though these aren't specifically relevant to module developers.

=== How should modules support groups? ===

There are two main ways a module might need to support groups. There may of
course be other more unusual ways in which your module should supports groups,
but these should hopefully be the most common ones. The important thing
is to think about how people would expect your module to behave if they chose to
use groups for it.

==== From a student's point of view ====

From a student's point of view, groups are generally used as a way to enable
parallel versions of the same activity with different groups of students e.g you
might want a separate forum or wiki for each group. If your module is
collaborative in any way (which includes the ability to view the existence of
other students or their contributions) then you need to make sure that this is
supported.

As well as the obvious views of activities being separated, you will need to
make sure that things like searches return the correct results and that teachers
can view the correct groups. You may also need to make a decision as to which
teacher activity is part of the setup of the activity so is the same for every
group and needs to be performed only once, and which teacher activity is the
contribution after the activity has started and so is different for each group.

In general if you module needs to support groups in this way you will find that
the database table(s) where you store the students' contributions will probably
need an extra 'groupid' column, for instance the forum table has a groupid
column.

==== From a teacher's point of view ====

From a teacher's point of view, groups are generally used to manage different
groups of students. For instance there may be several teachers on a course each
assigned to one or more groups of students who mark the work for the groups of
students that have been assigned to them but shouldn't be able to mark the work
of the other groups. A single teacher may also want to be able to view marks for
students by group when they teach the same material to two different classes. In
general, if your module enables teachers to somehow view students' contribution,
then you need to provide this type of support. You can usually do this by
checking which students are in which group rather than needing to alter the
module's database tables in any way.

==== Dealing with users in more than one group ====

Although users may be belong to more than one group, most of the time you can
use the groups library for modules to deal with this rather than having to worry
about this yourself. There will be more about this in the next section. The time
you will probably find that you need to worry about this is when for instance
you are doing a search for contributions that a particular student is allowed to
view. In this case you will need to look for contributions for all the groups
rather than just one group.

=== The groups library for modules ===
The functions at your disposal can be found in course/groups/lib/modulelib.php -
go and have a quick look at it now. (''Again you can't yet, but look here
at the [[Groups API for modules]] instead'') Here are some examples of common ways in which you might want to use
the functions in it.

1) Present a user with a page containing the right information for one of the
groups that they belong to including a selector to see the equivalent page for
any other groups that they belong to. e.g. present a user with a list of
discussion for a group they belong to.

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_STUDENT_CONTRIBUTE;
groups_m_print_group_selector($cmid, $urlroot, $permissiontype);
$currentgroupid = groups_m_get_selected_group($cmid, $permissiontype);
// This is your function that you've written.
do_whizzy_module_stuff_for_group($cmid, $currentgroupid);
} else {
// Do whatever you'd normally do
}

2) Present a user with search results only for the groups that they are allowed
to view.

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_VIEW;
$groupids = groups_m_get_groups_for_user($cmid, $permissiontype);
// You might want the search funtion to check group permissions too to be
// on the safe side.
get_module_search_results_for_groups($groupids, $maybesomeotherparameters);
} else {
// Do whatever you'd normally do
}

3) Get a list of users which a teacher should be able to mark work

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_TEACHER_CONTRIBUTE;
groups_m_print_group_selector($cmid, $urlroot, $permissiontype);
$groupid = groups_m_get_selected_group($cmid, $permissiontype);
$userids = groups_m_get_members($groupid);
} else {
// Get your userids the normal way
}
// Do whatever you'd normally do with the userids.

It is still ok to use inner joins on the groups_members table in the database
for this type of functionality as obviously this is sometimes required for
performance reasons, but make sure you keep your code that queries the database
clearly separated from your other code.

=== Support for legacy code ===

The following functions should still be supported but are deprecated:

get_groups
user_group
ismember
get_group_users
get_group_students
get_group_teachers
add_user_to_group
mygroupid
groupmode
set_current_group
get_current_group
get_and_set_current_group
setup_and_print_groups

Where appropriate, if a grouping has been specified in the course setting for
use for all activities that grouping will be used in what was previously
'separate groups' mode. If no such grouping has been specified then the first
grouping created for the course that still exists will be used, again in
separate groups mode. If you want better support than this, then I'm afraid you
will need to update the code for your module!

Accessing the groups_members table directly should still work (although it is
not recommended unless you need to do an inner join on it for performance
reasons). Directly accessing the groups table may not work because the course
column has been removed.

The groupid argument in the function search_users from datalib.php will still
work, but will only give members of a group, not those with a specific
permission.

=== Blocks and other special cases ===

There is an essentially identical library for blocks as for modules, only all
the _m_'s in the function names are replaced by _b_'s.

At the moment there is no standard way to set the grouping for a block and most
blocks don't need to use groups. If you want to create a way for someone to set
up a grouping for your block then you will need to do this yourself using the
functions in the other parts of the groups library (under course/groups/lib/)
but ask if you need help. There is a new column in the block_instance table
called groupingid that you will need to set using the function
groups_set_grouping_for_block_instance. If a grouping is set for all activities
for a course then this will get automatically set however.

There are currently two 'global' features in the Moodle core - blogs and the
calendar - a quick word on those in case anyone has plug-ins that provide
similar global features.

Calendar - with the calendar a teacher can set group events when they are within
a course, so basically all they need to do is get all the groups for the course
that a teacher has a particular permission for. Then when displaying calendar
entries to users, need to know which groups a particular has view permission
for across all courses though it's a tiny bit more complicated that this because
a grouping can be used for more than one course and someone may be a student on
one course and a teacher on another.

Blog - It's possible for the admin to set a blog option that makes blogs view
access group level. This means that users can only see blogs of people that they
share a group with for some course - there's a function provided in one of the
main groups libraries to find out if two users share a group. I'm guessing that
you're mostly only wanting to use this with installations with a very small
number of teachers and at some point global groups will get used here instead.

At the moment there is generally no general support for global features, but
this will hopefully come!

== Some rationale ==

I'll probably add stuff in here as it comes up :-)

''' Why doesn't this fit in with roles and permissions? '''

Mostly at the time I started doing this development the roles and permission
code wasn't available yet! The changes to roles and permissions are big and the
changes needed to fit in with them properly need some thought and would be even
more massive than they currently are. It seemed better to get the main
improvements to groups in first and give the roles and permissions code a bit of
time to settle. It would be nice if they are integrated sensible eventually.

''' Why do I have to deal separately with the case where the module uses groups and the case where it doesn't? Isn't there a clever way to do this so I don't have to? '''

Yes, but I wanted to try and keep people's code fairly readable and make it as
easy as possible to shift current over. In practice you shouldn't really have
too much extra code this way anyhow - you can always write functions with a
groupid argument that defaults to false.

== Future plans? (Things I'd like to do or you can do for me!) ==

In no particular order:

* Bug fixing I guess :-)
* Global groups - I want it to be possible to set up groupings for course 1 and for these to be visible for all course on the site, but not editable or deletable. I think this code should actually be quite easy to write now and I might even do it before this code is put in, just haven't done it yet.
* A nicer user interface (that doesn't break the back button :-) Ajax separates the back and front end of the code really well, so if anyone has good ideas on this, it should be quite easy for someone else to do without having to know how the internals of the groups code work.
* Integration with roles and permissions
* Sign up sheets for groups
* Proper support for blocks and global features.
* A way for modules and blocks to declare whether they support groups or not.
* Putting in search_users functionality for group permissions as well as just members of groups.
* Cool ways to set up groups automatically for particular pedagogical reasons - things like minimising overlap with groups in another grouping, creating groups just from the users all in another group and creating groups which merge pairs of groups from another grouping.

Development:Groups documentation for module developers

2006-08-21T11:23:02Z

Jvvw: /* How groups work in Moodle */

== Groups in Moodle for developers==

'''IMPORTANT:''' This documentation does not refer to current versions of Moodle
and is here at the moment purely in order to obtain comments. Descriptions of
how groups work refer to how they hopefully work not how they will work now! This document is also written in the present tense even though it doesn't refer to the current version of Moodle. This is so I don't have to go through and change it all in a month or two's time.

=== How groups work in Moodle ===

It is possible to have groups of users in Moodle. A person with the right
permissions (generally an editting teacher or admin) can create groups for a course and add and remove users from groups. They can also create sets of groups for the course which we'll refer to as 'groupings'. Groups that belong to the course can be added to and removed from any of the groupings that have been created for the course.

If you haven't seen the interface for creating groupings and groups, I'd
recommend you go to a course in your installation of Moodle for which you have
edit access and which has some participants and follow the Groups link and take
a look (''note: you can't currently do this obviously as the code isn't released
yet!'').

Once there is at least one grouping created for a course, when an editor adds an
instance of a module they may if they wish assign one of the groupings for the
course to use with that instance of the module. A user who is not in a group for
a grouping assigned will not be able to see that the instance of the module
exists. It is also possible for the editor to specify a grouping to use for
everything for the course - this is set up in the course settings.

Each group and grouping must 'belong' to at least one course (it's possible for them to belong to more than one course, but there's no user interface to let you do this easily at the moment). Both teachers and students can belong to groups and a user can belong to more than one group. It is also possible for a group to belong to more than one grouping.

There is a choice of various permission settings for a grouping - for instance
you can specify that students may both view and contribute to the group of which
they are a member but only view groups of which they are not members. In time
these settings wil hopefully be superceded by an extension of the roles and
permission system used elsewhere in Moodle, but at the moment they are
independent. The main types of permission that a user can have for a
particular group are 'student view', 'student contribute', 'teacher view' and
'teacher contribute', with it being up to modules to decide how to interpret
these. As we have seen, a user does not need to be a member of a group to have a
particular permission type for that group.

As well as modules, there are also some blocks and global features such as blogs
and the calendar that use groups in certain ways. We'll come to those later.

It is obviously good if modules support groups in the ways that users expect!
This document is here to try and help you do that - if anything isn't clear, you
have questions or can think of improvements to how groups work in Moodle, please
post on the Groups forum on moodle.org.

=== How does this differ from the way groups previously worked? ===

The biggest difference is that previously it was only possible to have one set of groups for a course. All activities for a course had to use the same set of groups. This is the main reason that the API needed to change.

Also, previously, for a course with groups, there were two groups modes - separate and visible. With separate groups, students
could not see groups to which they did not belong, whereas with visible groups they could see groups to which they did not belong but not contribute to them. This caused a great deal of confusion when it came to teachers belonging to groups and also
led to lots of really horrible logic in module code trying to work out who could view or contribute to an activity. This is why the separate/visible groups modes have been replaced by a more granular and flexible permissions system.

Another big difference that isn't visible is there are now tables in the database for course_groups and courses_groupings, whereas previous the groups table had a courseid column. This made it very difficult to use the same group for more than one course. This should now be much easier. However this obviously affects code that used to access the groups table directly.

There are also improvements to the user interface for creating groups, though these aren't specifically relevant to module developers.

=== How should modules support groups? ===

There are two main ways a module might need to support groups. There may of
course be other more unusual ways in which your module should supports groups,
but these should hopefully be the most common ones. The important thing
is to think about how people would expect your module to behave if they chose to
use groups for it.

==== From a student's point of view ====

From a student's point of view, groups are generally used as a way to enable
parallel versions of the same activity with different groups of students e.g you
might want a separate forum or wiki for each group. If your module is
collaborative in any way (which includes the ability to view the existence of
other students or their contributions) then you need to make sure that this is
supported.

As well as the obvious views of activities being separated, you will need to
make sure that things like searches return the correct results and that teachers
can view the correct groups. You may also need to make a decision as to which
teacher activity is part of the setup of the activity so is the same for every
group and needs to be performed only once, and which teacher activity is the
contribution after the activity has started and so is different for each group.

In general if you module needs to support groups in this way you will find that
the database table(s) where you store the students' contributions will probably
need an extra 'groupid' column, for instance the forum table has a groupid
column.

==== From a teacher's point of view ====

From a teacher's point of view, groups are generally used to manage different
groups of students. For instance there may be several teachers on a course each
assigned to one or more groups of students who mark the work for the groups of
students that have been assigned to them but shouldn't be able to mark the work
of the other groups. A single teacher may also want to be able to view marks for
students by group when they teach the same material to two different classes. In
general, if your module enables teachers to somehow view students' contribution,
then you need to provide this type of support. You can usually do this by
checking which students are in which group rather than needing to alter the
module's database tables in any way.

==== Dealing with users in more than one group ====

Although users may be belong to more than one group, most of the time you can
use the groups library for modules to deal with this rather than having to worry
about this yourself. There will be more about this in the next section. The time
you will probably find that you need to worry about this is when for instance
you are doing a search for contributions that a particular student is allowed to
view. In this case you will need to look for contributions for all the groups
rather than just one group.

=== The groups library for modules ===
The functions at your disposal can be found in course/groups/lib/modulelib.php -
go and have a quick look at it now. (''Again you can't yet, but look here
at the [[Groups API for modules]] instead'') Here are some examples of common ways in which you might want to use
the functions in it.

1) Present a user with a page containing the right information for one of the
groups that they belong to including a selector to see the equivalent page for
any other groups that they belong to. e.g. present a user with a list of
discussion for a group they belong to.

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_STUDENT_CONTRIBUTE;
groups_m_print_group_selector($cmid, $urlroot, $permissiontype);
$currentgroupid = groups_m_get_selected_group($cmid, $permissiontype);
// This is your function that you've written.
do_whizzy_module_stuff_for_group($cmid, $currentgroupid);
} else {
// Do whatever you'd normally do
}

2) Present a user with search results only for the groups that they are allowed
to view.

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_VIEW;
$groupids = groups_m_get_groups_for_user($cmid, $permissiontype);
// You might want the search funtion to check group permissions too to be
// on the safe side.
get_module_search_results_for_groups($groupids, $maybesomeotherparameters);
} else {
// Do whatever you'd normally do
}

3) Get a list of users which a teacher should be able to mark work

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_TEACHER_CONTRIBUTE;
groups_m_print_group_selector($cmid, $urlroot, $permissiontype);
$groupid = groups_m_get_selected_group($cmid, $permissiontype);
$userids = groups_m_get_members($groupid);
} else {
// Get your userids the normal way
}
// Do whatever you'd normally do with the userids.

It is still ok to use inner joins on the groups_members table in the database
for this type of functionality as obviously this is sometimes required for
performance reasons, but make sure you keep your code that queries the database
clearly separated from your other code.

=== Support for legacy code ===

The following functions should still be supported but are deprecated:

get_groups
user_group
ismember
get_group_users
get_group_students
get_group_teachers
add_user_to_group
mygroupid
groupmode
set_current_group
get_current_group
get_and_set_current_group
setup_and_print_groups

Where appropriate, if a grouping has been specified in the course setting for
use for all activities that grouping will be used in what was previously
'separate groups' mode. If no such grouping has been specified then the first
grouping created for the course that still exists will be used, again in
separate groups mode. If you want better support than this, then I'm afraid you
will need to update the code for your module!

Accessing the groups_members table directly should still work (although it is
not recommended unless you need to do an inner join on it for performance
reasons). Directly accessing the groups table may not work because the course
column has been removed.

The groupid argument in the function search_users from datalib.php will still
work, but will only give members of a group, not those with a specific
permission.

=== Blocks and other special cases ===

There is an essentially identical library for blocks as for modules, only all
the _m_'s in the function names are replaced by _b_'s.

At the moment there is no standard way to set the grouping for a block and most
blocks don't need to use groups. If you want to create a way for someone to set
up a grouping for your block then you will need to do this yourself using the
functions in the other parts of the groups library (under course/groups/lib/)
but ask if you need help. There is a new column in the block_instance table
called groupingid that you will need to set using the function
groups_set_grouping_for_block_instance. If a grouping is set for all activities
for a course then this will get automatically set however.

There are currently two 'global' features in the Moodle core - blogs and the
calendar - a quick word on those in case anyone has plug-ins that provide
similar global features.

Calendar - with the calendar a teacher can set group events when they are within
a course, so basically all they need to do is get all the groups for the course
that a teacher has a particular permission for. Then when displaying calendar
entries to users, need to know which groups a particular has view permission
for across all courses though it's a tiny bit more complicated that this because
a grouping can be used for more than one course and someone may be a student on
one course and a teacher on another.

Blog - It's possible for the admin to set a blog option that makes blogs view
access group level. This means that users can only see blogs of people that they
share a group with for some course - there's a function provided in one of the
main groups libraries to find out if two users share a group. I'm guessing that
you're mostly only wanting to use this with installations with a very small
number of teachers and at some point global groups will get used here instead.

At the moment there is generally no general support for global features, but
this will hopefully come!

== Some rationale ==

I'll probably add stuff in here as it comes up :-)

''' Why doesn't this fit in with roles and permissions? '''

Mostly at the time I started doing this development the roles and permission
code wasn't available yet! The changes to roles and permissions are big and the
changes needed to fit in with them properly need some thought and would be even
more massive than they currently are. It seemed better to get the main
improvements to groups in first and give the roles and permissions code a bit of
time to settle. It would be nice if they are integrated sensible eventually.

''' Why do I have to deal separately with the case where the module uses groups and the case where it doesn't? Isn't there a clever way to do this so I don't have to? '''

Yes, but I wanted to try and keep people's code fairly readable and make it as
easy as possible to shift current over. In practice you shouldn't really have
too much extra code this way anyhow - you can always write functions with a
groupid argument that defaults to false.

== Future plans? (Things I'd like to do or you can do for me!) ==

In no particular order:

* Bug fixing I guess :-)
* Global groups - I want it to be possible to set up groupings for course 1 and for these to be visible for all course on the site, but not editable or deletable. I think this code should actually be quite easy to write now and I might even do it before this code is put in, just haven't done it yet.
* A nicer user interface (that doesn't break the back button :-) Ajax separates the back and front end of the code really well, so if anyone has good ideas on this, it should be quite easy for someone else to do without having to know how the internals of the groups code work.
* Integration with roles and permissions
* Sign up sheets for groups
* Proper support for blocks and global features.
* A way for modules and blocks to declare whether they support groups or not.
* Putting in search_users functionality for group permissions as well as just members of groups.
* Cool ways to set up groups automatically for particular pedagogical reasons - things like minimising overlap with groups in another grouping, creating groups just from the users all in another group and creating groups which merge pairs of groups from another grouping.

Development:Groups documentation for module developers

2006-08-21T11:22:35Z

Jvvw: /* How groups work in Moodle */

== Groups in Moodle for developers==

'''IMPORTANT:''' This documentation does not refer to current versions of Moodle
and is here at the moment purely in order to obtain comments. Descriptions of
how groups work refer to how they hopefully work not how they will work now! This document is also written in the present tense even though it doesn't refer to the current version of Moodle. This is so I don't have to go through and change it all in a month or two's time.

=== How groups work in Moodle ===

It is possible to have groups of users in Moodle. A person with the right
permissions (generally an editting teacher or admin) can create groups for a course and add and remove users from groups. They can also create sets of groups for the course which we'll refer to as 'groupings'. Groups that belong to the course can be added to and removed from any of the groupings that have been created for the course.

Each group and grouping must 'belong' to at least one course (it's possible for them to belong to more than one course, but there's no user interface to let you do this easily at the moment). Both teachers and students can belong to groups and a user can belong to more than one group. It is also possible for a group to belong to more than one grouping.

If you haven't seen the interface for creating groupings and groups, I'd
recommend you go to a course in your installation of Moodle for which you have
edit access and which has some participants and follow the Groups link and take
a look (''note: you can't currently do this obviously as the code isn't released
yet!'').

Once there is at least one grouping created for a course, when an editor adds an
instance of a module they may if they wish assign one of the groupings for the
course to use with that instance of the module. A user who is not in a group for
a grouping assigned will not be able to see that the instance of the module
exists. It is also possible for the editor to specify a grouping to use for
everything for the course - this is set up in the course settings.

There is a choice of various permission settings for a grouping - for instance
you can specify that students may both view and contribute to the group of which
they are a member but only view groups of which they are not members. In time
these settings wil hopefully be superceded by an extension of the roles and
permission system used elsewhere in Moodle, but at the moment they are
independent. The main types of permission that a user can have for a
particular group are 'student view', 'student contribute', 'teacher view' and
'teacher contribute', with it being up to modules to decide how to interpret
these. As we have seen, a user does not need to be a member of a group to have a
particular permission type for that group.

As well as modules, there are also some blocks and global features such as blogs
and the calendar that use groups in certain ways. We'll come to those later.

It is obviously good if modules support groups in the ways that users expect!
This document is here to try and help you do that - if anything isn't clear, you
have questions or can think of improvements to how groups work in Moodle, please
post on the Groups forum on moodle.org.

=== How does this differ from the way groups previously worked? ===

The biggest difference is that previously it was only possible to have one set of groups for a course. All activities for a course had to use the same set of groups. This is the main reason that the API needed to change.

Also, previously, for a course with groups, there were two groups modes - separate and visible. With separate groups, students
could not see groups to which they did not belong, whereas with visible groups they could see groups to which they did not belong but not contribute to them. This caused a great deal of confusion when it came to teachers belonging to groups and also
led to lots of really horrible logic in module code trying to work out who could view or contribute to an activity. This is why the separate/visible groups modes have been replaced by a more granular and flexible permissions system.

Another big difference that isn't visible is there are now tables in the database for course_groups and courses_groupings, whereas previous the groups table had a courseid column. This made it very difficult to use the same group for more than one course. This should now be much easier. However this obviously affects code that used to access the groups table directly.

There are also improvements to the user interface for creating groups, though these aren't specifically relevant to module developers.

=== How should modules support groups? ===

There are two main ways a module might need to support groups. There may of
course be other more unusual ways in which your module should supports groups,
but these should hopefully be the most common ones. The important thing
is to think about how people would expect your module to behave if they chose to
use groups for it.

==== From a student's point of view ====

From a student's point of view, groups are generally used as a way to enable
parallel versions of the same activity with different groups of students e.g you
might want a separate forum or wiki for each group. If your module is
collaborative in any way (which includes the ability to view the existence of
other students or their contributions) then you need to make sure that this is
supported.

As well as the obvious views of activities being separated, you will need to
make sure that things like searches return the correct results and that teachers
can view the correct groups. You may also need to make a decision as to which
teacher activity is part of the setup of the activity so is the same for every
group and needs to be performed only once, and which teacher activity is the
contribution after the activity has started and so is different for each group.

In general if you module needs to support groups in this way you will find that
the database table(s) where you store the students' contributions will probably
need an extra 'groupid' column, for instance the forum table has a groupid
column.

==== From a teacher's point of view ====

From a teacher's point of view, groups are generally used to manage different
groups of students. For instance there may be several teachers on a course each
assigned to one or more groups of students who mark the work for the groups of
students that have been assigned to them but shouldn't be able to mark the work
of the other groups. A single teacher may also want to be able to view marks for
students by group when they teach the same material to two different classes. In
general, if your module enables teachers to somehow view students' contribution,
then you need to provide this type of support. You can usually do this by
checking which students are in which group rather than needing to alter the
module's database tables in any way.

==== Dealing with users in more than one group ====

Although users may be belong to more than one group, most of the time you can
use the groups library for modules to deal with this rather than having to worry
about this yourself. There will be more about this in the next section. The time
you will probably find that you need to worry about this is when for instance
you are doing a search for contributions that a particular student is allowed to
view. In this case you will need to look for contributions for all the groups
rather than just one group.

=== The groups library for modules ===
The functions at your disposal can be found in course/groups/lib/modulelib.php -
go and have a quick look at it now. (''Again you can't yet, but look here
at the [[Groups API for modules]] instead'') Here are some examples of common ways in which you might want to use
the functions in it.

1) Present a user with a page containing the right information for one of the
groups that they belong to including a selector to see the equivalent page for
any other groups that they belong to. e.g. present a user with a list of
discussion for a group they belong to.

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_STUDENT_CONTRIBUTE;
groups_m_print_group_selector($cmid, $urlroot, $permissiontype);
$currentgroupid = groups_m_get_selected_group($cmid, $permissiontype);
// This is your function that you've written.
do_whizzy_module_stuff_for_group($cmid, $currentgroupid);
} else {
// Do whatever you'd normally do
}

2) Present a user with search results only for the groups that they are allowed
to view.

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_VIEW;
$groupids = groups_m_get_groups_for_user($cmid, $permissiontype);
// You might want the search funtion to check group permissions too to be
// on the safe side.
get_module_search_results_for_groups($groupids, $maybesomeotherparameters);
} else {
// Do whatever you'd normally do
}

3) Get a list of users which a teacher should be able to mark work

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_TEACHER_CONTRIBUTE;
groups_m_print_group_selector($cmid, $urlroot, $permissiontype);
$groupid = groups_m_get_selected_group($cmid, $permissiontype);
$userids = groups_m_get_members($groupid);
} else {
// Get your userids the normal way
}
// Do whatever you'd normally do with the userids.

It is still ok to use inner joins on the groups_members table in the database
for this type of functionality as obviously this is sometimes required for
performance reasons, but make sure you keep your code that queries the database
clearly separated from your other code.

=== Support for legacy code ===

The following functions should still be supported but are deprecated:

get_groups
user_group
ismember
get_group_users
get_group_students
get_group_teachers
add_user_to_group
mygroupid
groupmode
set_current_group
get_current_group
get_and_set_current_group
setup_and_print_groups

Where appropriate, if a grouping has been specified in the course setting for
use for all activities that grouping will be used in what was previously
'separate groups' mode. If no such grouping has been specified then the first
grouping created for the course that still exists will be used, again in
separate groups mode. If you want better support than this, then I'm afraid you
will need to update the code for your module!

Accessing the groups_members table directly should still work (although it is
not recommended unless you need to do an inner join on it for performance
reasons). Directly accessing the groups table may not work because the course
column has been removed.

The groupid argument in the function search_users from datalib.php will still
work, but will only give members of a group, not those with a specific
permission.

=== Blocks and other special cases ===

There is an essentially identical library for blocks as for modules, only all
the _m_'s in the function names are replaced by _b_'s.

At the moment there is no standard way to set the grouping for a block and most
blocks don't need to use groups. If you want to create a way for someone to set
up a grouping for your block then you will need to do this yourself using the
functions in the other parts of the groups library (under course/groups/lib/)
but ask if you need help. There is a new column in the block_instance table
called groupingid that you will need to set using the function
groups_set_grouping_for_block_instance. If a grouping is set for all activities
for a course then this will get automatically set however.

There are currently two 'global' features in the Moodle core - blogs and the
calendar - a quick word on those in case anyone has plug-ins that provide
similar global features.

Calendar - with the calendar a teacher can set group events when they are within
a course, so basically all they need to do is get all the groups for the course
that a teacher has a particular permission for. Then when displaying calendar
entries to users, need to know which groups a particular has view permission
for across all courses though it's a tiny bit more complicated that this because
a grouping can be used for more than one course and someone may be a student on
one course and a teacher on another.

Blog - It's possible for the admin to set a blog option that makes blogs view
access group level. This means that users can only see blogs of people that they
share a group with for some course - there's a function provided in one of the
main groups libraries to find out if two users share a group. I'm guessing that
you're mostly only wanting to use this with installations with a very small
number of teachers and at some point global groups will get used here instead.

At the moment there is generally no general support for global features, but
this will hopefully come!

== Some rationale ==

I'll probably add stuff in here as it comes up :-)

''' Why doesn't this fit in with roles and permissions? '''

Mostly at the time I started doing this development the roles and permission
code wasn't available yet! The changes to roles and permissions are big and the
changes needed to fit in with them properly need some thought and would be even
more massive than they currently are. It seemed better to get the main
improvements to groups in first and give the roles and permissions code a bit of
time to settle. It would be nice if they are integrated sensible eventually.

''' Why do I have to deal separately with the case where the module uses groups and the case where it doesn't? Isn't there a clever way to do this so I don't have to? '''

Yes, but I wanted to try and keep people's code fairly readable and make it as
easy as possible to shift current over. In practice you shouldn't really have
too much extra code this way anyhow - you can always write functions with a
groupid argument that defaults to false.

== Future plans? (Things I'd like to do or you can do for me!) ==

In no particular order:

* Bug fixing I guess :-)
* Global groups - I want it to be possible to set up groupings for course 1 and for these to be visible for all course on the site, but not editable or deletable. I think this code should actually be quite easy to write now and I might even do it before this code is put in, just haven't done it yet.
* A nicer user interface (that doesn't break the back button :-) Ajax separates the back and front end of the code really well, so if anyone has good ideas on this, it should be quite easy for someone else to do without having to know how the internals of the groups code work.
* Integration with roles and permissions
* Sign up sheets for groups
* Proper support for blocks and global features.
* A way for modules and blocks to declare whether they support groups or not.
* Putting in search_users functionality for group permissions as well as just members of groups.
* Cool ways to set up groups automatically for particular pedagogical reasons - things like minimising overlap with groups in another grouping, creating groups just from the users all in another group and creating groups which merge pairs of groups from another grouping.

Development:Groups documentation for module developers

2006-08-21T11:22:00Z

Jvvw: /* Groups in Moodle for developers */

== Groups in Moodle for developers==

'''IMPORTANT:''' This documentation does not refer to current versions of Moodle
and is here at the moment purely in order to obtain comments. Descriptions of
how groups work refer to how they hopefully work not how they will work now! This document is also written in the present tense even though it doesn't refer to the current version of Moodle. This is so I don't have to go through and change it all in a month or two's time.

=== How groups work in Moodle ===

It is possible to have groups of users in Moodle. A person with the right
permissions (generally an editting teacher or admin) can create groups for a course and add and remove users from groups. They can also create sets of groups for the course which we'll refer to as 'groupings'. Groups that belong to the course can be added to and removed from any of the groupings that have been created for the course. Each group and grouping must 'belong' to at least one course (it's possible for them to belong to more than one course, but there's no user interface to let you do this easily at the moment).

Both teachers and students can belong to groups and a user can belong
to more than one group. It is also possible for a group to belong to more than
one grouping.

If you haven't seen the interface for creating groupings and groups, I'd
recommend you go to a course in your installation of Moodle for which you have
edit access and which has some participants and follow the Groups link and take
a look (''note: you can't currently do this obviously as the code isn't released
yet!'').

Once there is at least one grouping created for a course, when an editor adds an
instance of a module they may if they wish assign one of the groupings for the
course to use with that instance of the module. A user who is not in a group for
a grouping assigned will not be able to see that the instance of the module
exists. It is also possible for the editor to specify a grouping to use for
everything for the course - this is set up in the course settings.

There is a choice of various permission settings for a grouping - for instance
you can specify that students may both view and contribute to the group of which
they are a member but only view groups of which they are not members. In time
these settings wil hopefully be superceded by an extension of the roles and
permission system used elsewhere in Moodle, but at the moment they are
independent. The main types of permission that a user can have for a
particular group are 'student view', 'student contribute', 'teacher view' and
'teacher contribute', with it being up to modules to decide how to interpret
these. As we have seen, a user does not need to be a member of a group to have a
particular permission type for that group.

As well as modules, there are also some blocks and global features such as blogs
and the calendar that use groups in certain ways. We'll come to those later.

It is obviously good if modules support groups in the ways that users expect!
This document is here to try and help you do that - if anything isn't clear, you
have questions or can think of improvements to how groups work in Moodle, please
post on the Groups forum on moodle.org.

=== How does this differ from the way groups previously worked? ===

The biggest difference is that previously it was only possible to have one set of groups for a course. All activities for a course had to use the same set of groups. This is the main reason that the API needed to change.

Also, previously, for a course with groups, there were two groups modes - separate and visible. With separate groups, students
could not see groups to which they did not belong, whereas with visible groups they could see groups to which they did not belong but not contribute to them. This caused a great deal of confusion when it came to teachers belonging to groups and also
led to lots of really horrible logic in module code trying to work out who could view or contribute to an activity. This is why the separate/visible groups modes have been replaced by a more granular and flexible permissions system.

Another big difference that isn't visible is there are now tables in the database for course_groups and courses_groupings, whereas previous the groups table had a courseid column. This made it very difficult to use the same group for more than one course. This should now be much easier. However this obviously affects code that used to access the groups table directly.

There are also improvements to the user interface for creating groups, though these aren't specifically relevant to module developers.

=== How should modules support groups? ===

There are two main ways a module might need to support groups. There may of
course be other more unusual ways in which your module should supports groups,
but these should hopefully be the most common ones. The important thing
is to think about how people would expect your module to behave if they chose to
use groups for it.

==== From a student's point of view ====

From a student's point of view, groups are generally used as a way to enable
parallel versions of the same activity with different groups of students e.g you
might want a separate forum or wiki for each group. If your module is
collaborative in any way (which includes the ability to view the existence of
other students or their contributions) then you need to make sure that this is
supported.

As well as the obvious views of activities being separated, you will need to
make sure that things like searches return the correct results and that teachers
can view the correct groups. You may also need to make a decision as to which
teacher activity is part of the setup of the activity so is the same for every
group and needs to be performed only once, and which teacher activity is the
contribution after the activity has started and so is different for each group.

In general if you module needs to support groups in this way you will find that
the database table(s) where you store the students' contributions will probably
need an extra 'groupid' column, for instance the forum table has a groupid
column.

==== From a teacher's point of view ====

From a teacher's point of view, groups are generally used to manage different
groups of students. For instance there may be several teachers on a course each
assigned to one or more groups of students who mark the work for the groups of
students that have been assigned to them but shouldn't be able to mark the work
of the other groups. A single teacher may also want to be able to view marks for
students by group when they teach the same material to two different classes. In
general, if your module enables teachers to somehow view students' contribution,
then you need to provide this type of support. You can usually do this by
checking which students are in which group rather than needing to alter the
module's database tables in any way.

==== Dealing with users in more than one group ====

Although users may be belong to more than one group, most of the time you can
use the groups library for modules to deal with this rather than having to worry
about this yourself. There will be more about this in the next section. The time
you will probably find that you need to worry about this is when for instance
you are doing a search for contributions that a particular student is allowed to
view. In this case you will need to look for contributions for all the groups
rather than just one group.

=== The groups library for modules ===
The functions at your disposal can be found in course/groups/lib/modulelib.php -
go and have a quick look at it now. (''Again you can't yet, but look here
at the [[Groups API for modules]] instead'') Here are some examples of common ways in which you might want to use
the functions in it.

1) Present a user with a page containing the right information for one of the
groups that they belong to including a selector to see the equivalent page for
any other groups that they belong to. e.g. present a user with a list of
discussion for a group they belong to.

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_STUDENT_CONTRIBUTE;
groups_m_print_group_selector($cmid, $urlroot, $permissiontype);
$currentgroupid = groups_m_get_selected_group($cmid, $permissiontype);
// This is your function that you've written.
do_whizzy_module_stuff_for_group($cmid, $currentgroupid);
} else {
// Do whatever you'd normally do
}

2) Present a user with search results only for the groups that they are allowed
to view.

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_VIEW;
$groupids = groups_m_get_groups_for_user($cmid, $permissiontype);
// You might want the search funtion to check group permissions too to be
// on the safe side.
get_module_search_results_for_groups($groupids, $maybesomeotherparameters);
} else {
// Do whatever you'd normally do
}

3) Get a list of users which a teacher should be able to mark work

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_TEACHER_CONTRIBUTE;
groups_m_print_group_selector($cmid, $urlroot, $permissiontype);
$groupid = groups_m_get_selected_group($cmid, $permissiontype);
$userids = groups_m_get_members($groupid);
} else {
// Get your userids the normal way
}
// Do whatever you'd normally do with the userids.

It is still ok to use inner joins on the groups_members table in the database
for this type of functionality as obviously this is sometimes required for
performance reasons, but make sure you keep your code that queries the database
clearly separated from your other code.

=== Support for legacy code ===

The following functions should still be supported but are deprecated:

get_groups
user_group
ismember
get_group_users
get_group_students
get_group_teachers
add_user_to_group
mygroupid
groupmode
set_current_group
get_current_group
get_and_set_current_group
setup_and_print_groups

Where appropriate, if a grouping has been specified in the course setting for
use for all activities that grouping will be used in what was previously
'separate groups' mode. If no such grouping has been specified then the first
grouping created for the course that still exists will be used, again in
separate groups mode. If you want better support than this, then I'm afraid you
will need to update the code for your module!

Accessing the groups_members table directly should still work (although it is
not recommended unless you need to do an inner join on it for performance
reasons). Directly accessing the groups table may not work because the course
column has been removed.

The groupid argument in the function search_users from datalib.php will still
work, but will only give members of a group, not those with a specific
permission.

=== Blocks and other special cases ===

There is an essentially identical library for blocks as for modules, only all
the _m_'s in the function names are replaced by _b_'s.

At the moment there is no standard way to set the grouping for a block and most
blocks don't need to use groups. If you want to create a way for someone to set
up a grouping for your block then you will need to do this yourself using the
functions in the other parts of the groups library (under course/groups/lib/)
but ask if you need help. There is a new column in the block_instance table
called groupingid that you will need to set using the function
groups_set_grouping_for_block_instance. If a grouping is set for all activities
for a course then this will get automatically set however.

There are currently two 'global' features in the Moodle core - blogs and the
calendar - a quick word on those in case anyone has plug-ins that provide
similar global features.

Calendar - with the calendar a teacher can set group events when they are within
a course, so basically all they need to do is get all the groups for the course
that a teacher has a particular permission for. Then when displaying calendar
entries to users, need to know which groups a particular has view permission
for across all courses though it's a tiny bit more complicated that this because
a grouping can be used for more than one course and someone may be a student on
one course and a teacher on another.

Blog - It's possible for the admin to set a blog option that makes blogs view
access group level. This means that users can only see blogs of people that they
share a group with for some course - there's a function provided in one of the
main groups libraries to find out if two users share a group. I'm guessing that
you're mostly only wanting to use this with installations with a very small
number of teachers and at some point global groups will get used here instead.

At the moment there is generally no general support for global features, but
this will hopefully come!

== Some rationale ==

I'll probably add stuff in here as it comes up :-)

''' Why doesn't this fit in with roles and permissions? '''

Mostly at the time I started doing this development the roles and permission
code wasn't available yet! The changes to roles and permissions are big and the
changes needed to fit in with them properly need some thought and would be even
more massive than they currently are. It seemed better to get the main
improvements to groups in first and give the roles and permissions code a bit of
time to settle. It would be nice if they are integrated sensible eventually.

''' Why do I have to deal separately with the case where the module uses groups and the case where it doesn't? Isn't there a clever way to do this so I don't have to? '''

Yes, but I wanted to try and keep people's code fairly readable and make it as
easy as possible to shift current over. In practice you shouldn't really have
too much extra code this way anyhow - you can always write functions with a
groupid argument that defaults to false.

== Future plans? (Things I'd like to do or you can do for me!) ==

In no particular order:

* Bug fixing I guess :-)
* Global groups - I want it to be possible to set up groupings for course 1 and for these to be visible for all course on the site, but not editable or deletable. I think this code should actually be quite easy to write now and I might even do it before this code is put in, just haven't done it yet.
* A nicer user interface (that doesn't break the back button :-) Ajax separates the back and front end of the code really well, so if anyone has good ideas on this, it should be quite easy for someone else to do without having to know how the internals of the groups code work.
* Integration with roles and permissions
* Sign up sheets for groups
* Proper support for blocks and global features.
* A way for modules and blocks to declare whether they support groups or not.
* Putting in search_users functionality for group permissions as well as just members of groups.
* Cool ways to set up groups automatically for particular pedagogical reasons - things like minimising overlap with groups in another grouping, creating groups just from the users all in another group and creating groups which merge pairs of groups from another grouping.

Development:Groups documentation for module developers

2006-08-21T11:19:51Z

Jvvw: /* How groups work in Moodle */

== Groups in Moodle for developers==

'''IMPORTANT:''' This documentation does not refer to current versions of Moodle
and is here at the moment purely in order to obtain comments. Descriptions of
how groups work refer to how they hopefully work not how they will work now! This document is also written in the present tense even though it doesn't refer to the current version of Moodle. This is so I don't have to go through and change it all!

=== How groups work in Moodle ===

It is possible to have groups of users in Moodle. A person with the right
permissions (generally an editting teacher or admin) can create groups for a course and add and remove users from groups. They can also create sets of groups for the course which we'll refer to as 'groupings'. Groups that belong to the course can be added to and removed from any of the groupings that have been created for the course. Each group and grouping must 'belong' to at least one course (it's possible for them to belong to more than one course, but there's no user interface to let you do this easily at the moment).

Both teachers and students can belong to groups and a user can belong
to more than one group. It is also possible for a group to belong to more than
one grouping.

If you haven't seen the interface for creating groupings and groups, I'd
recommend you go to a course in your installation of Moodle for which you have
edit access and which has some participants and follow the Groups link and take
a look (''note: you can't currently do this obviously as the code isn't released
yet!'').

There is a choice of various permission settings for a grouping - for instance
you can specify that students may both view and contribute to the group of which
they are a member but only view groups of which they are not members. In time
these settings wil hopefully be superceded by an extension of the roles and
permission system used elsewhere in Moodle, but at the moment they are
independent. The main types of permission that a user can have for a
particular group are 'student view', 'student contribute', 'teacher view' and
'teacher contribute', with it being up to modules to decide how to interpret
these. As we have seen, a user does not need to be a member of a group to have a
particular permission type for that group.

Once there is at least one grouping created for a course, when an editor adds an
instance of a module they may if they wish assign one of the groupings for the
course to use with that instance of the module. A user who is not in a group for
a grouping assigned will not be able to see that the instance of the module
exists. It is also possible for the editor to specify a grouping to use for
everything for the course - this is set up in the course settings.

As well as modules, there are also some blocks and global features such as blogs
and the calendar that use groups in certain ways. We'll come to those later.

It is obviously good if modules support groups in the ways that users expect!
This document is here to try and help you do that - if anything isn't clear, you
have questions or can think of improvements to how groups work in Moodle, please
post on the Groups forum on moodle.org.

=== How does this differ from the way groups previously worked? ===

The biggest difference is that previously it was only possible to have one set of groups for a course. All activities for a course had to use the same set of groups. This is the main reason that the API needed to change.

Also, previously, for a course with groups, there were two groups modes - separate and visible. With separate groups, students
could not see groups to which they did not belong, whereas with visible groups they could see groups to which they did not belong but not contribute to them. This caused a great deal of confusion when it came to teachers belonging to groups and also
led to lots of really horrible logic in module code trying to work out who could view or contribute to an activity. This is why the separate/visible groups modes have been replaced by a more granular and flexible permissions system.

Another big difference that isn't visible is there are now tables in the database for course_groups and courses_groupings, whereas previous the groups table had a courseid column. This made it very difficult to use the same group for more than one course. This should now be much easier. However this obviously affects code that used to access the groups table directly.

There are also improvements to the user interface for creating groups, though these aren't specifically relevant to module developers.

=== How should modules support groups? ===

There are two main ways a module might need to support groups. There may of
course be other more unusual ways in which your module should supports groups,
but these should hopefully be the most common ones. The important thing
is to think about how people would expect your module to behave if they chose to
use groups for it.

==== From a student's point of view ====

From a student's point of view, groups are generally used as a way to enable
parallel versions of the same activity with different groups of students e.g you
might want a separate forum or wiki for each group. If your module is
collaborative in any way (which includes the ability to view the existence of
other students or their contributions) then you need to make sure that this is
supported.

As well as the obvious views of activities being separated, you will need to
make sure that things like searches return the correct results and that teachers
can view the correct groups. You may also need to make a decision as to which
teacher activity is part of the setup of the activity so is the same for every
group and needs to be performed only once, and which teacher activity is the
contribution after the activity has started and so is different for each group.

In general if you module needs to support groups in this way you will find that
the database table(s) where you store the students' contributions will probably
need an extra 'groupid' column, for instance the forum table has a groupid
column.

==== From a teacher's point of view ====

From a teacher's point of view, groups are generally used to manage different
groups of students. For instance there may be several teachers on a course each
assigned to one or more groups of students who mark the work for the groups of
students that have been assigned to them but shouldn't be able to mark the work
of the other groups. A single teacher may also want to be able to view marks for
students by group when they teach the same material to two different classes. In
general, if your module enables teachers to somehow view students' contribution,
then you need to provide this type of support. You can usually do this by
checking which students are in which group rather than needing to alter the
module's database tables in any way.

==== Dealing with users in more than one group ====

Although users may be belong to more than one group, most of the time you can
use the groups library for modules to deal with this rather than having to worry
about this yourself. There will be more about this in the next section. The time
you will probably find that you need to worry about this is when for instance
you are doing a search for contributions that a particular student is allowed to
view. In this case you will need to look for contributions for all the groups
rather than just one group.

=== The groups library for modules ===
The functions at your disposal can be found in course/groups/lib/modulelib.php -
go and have a quick look at it now. (''Again you can't yet, but look here
at the [[Groups API for modules]] instead'') Here are some examples of common ways in which you might want to use
the functions in it.

1) Present a user with a page containing the right information for one of the
groups that they belong to including a selector to see the equivalent page for
any other groups that they belong to. e.g. present a user with a list of
discussion for a group they belong to.

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_STUDENT_CONTRIBUTE;
groups_m_print_group_selector($cmid, $urlroot, $permissiontype);
$currentgroupid = groups_m_get_selected_group($cmid, $permissiontype);
// This is your function that you've written.
do_whizzy_module_stuff_for_group($cmid, $currentgroupid);
} else {
// Do whatever you'd normally do
}

2) Present a user with search results only for the groups that they are allowed
to view.

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_VIEW;
$groupids = groups_m_get_groups_for_user($cmid, $permissiontype);
// You might want the search funtion to check group permissions too to be
// on the safe side.
get_module_search_results_for_groups($groupids, $maybesomeotherparameters);
} else {
// Do whatever you'd normally do
}

3) Get a list of users which a teacher should be able to mark work

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_TEACHER_CONTRIBUTE;
groups_m_print_group_selector($cmid, $urlroot, $permissiontype);
$groupid = groups_m_get_selected_group($cmid, $permissiontype);
$userids = groups_m_get_members($groupid);
} else {
// Get your userids the normal way
}
// Do whatever you'd normally do with the userids.

It is still ok to use inner joins on the groups_members table in the database
for this type of functionality as obviously this is sometimes required for
performance reasons, but make sure you keep your code that queries the database
clearly separated from your other code.

=== Support for legacy code ===

The following functions should still be supported but are deprecated:

get_groups
user_group
ismember
get_group_users
get_group_students
get_group_teachers
add_user_to_group
mygroupid
groupmode
set_current_group
get_current_group
get_and_set_current_group
setup_and_print_groups

Where appropriate, if a grouping has been specified in the course setting for
use for all activities that grouping will be used in what was previously
'separate groups' mode. If no such grouping has been specified then the first
grouping created for the course that still exists will be used, again in
separate groups mode. If you want better support than this, then I'm afraid you
will need to update the code for your module!

Accessing the groups_members table directly should still work (although it is
not recommended unless you need to do an inner join on it for performance
reasons). Directly accessing the groups table may not work because the course
column has been removed.

The groupid argument in the function search_users from datalib.php will still
work, but will only give members of a group, not those with a specific
permission.

=== Blocks and other special cases ===

There is an essentially identical library for blocks as for modules, only all
the _m_'s in the function names are replaced by _b_'s.

At the moment there is no standard way to set the grouping for a block and most
blocks don't need to use groups. If you want to create a way for someone to set
up a grouping for your block then you will need to do this yourself using the
functions in the other parts of the groups library (under course/groups/lib/)
but ask if you need help. There is a new column in the block_instance table
called groupingid that you will need to set using the function
groups_set_grouping_for_block_instance. If a grouping is set for all activities
for a course then this will get automatically set however.

There are currently two 'global' features in the Moodle core - blogs and the
calendar - a quick word on those in case anyone has plug-ins that provide
similar global features.

Calendar - with the calendar a teacher can set group events when they are within
a course, so basically all they need to do is get all the groups for the course
that a teacher has a particular permission for. Then when displaying calendar
entries to users, need to know which groups a particular has view permission
for across all courses though it's a tiny bit more complicated that this because
a grouping can be used for more than one course and someone may be a student on
one course and a teacher on another.

Blog - It's possible for the admin to set a blog option that makes blogs view
access group level. This means that users can only see blogs of people that they
share a group with for some course - there's a function provided in one of the
main groups libraries to find out if two users share a group. I'm guessing that
you're mostly only wanting to use this with installations with a very small
number of teachers and at some point global groups will get used here instead.

At the moment there is generally no general support for global features, but
this will hopefully come!

== Some rationale ==

I'll probably add stuff in here as it comes up :-)

''' Why doesn't this fit in with roles and permissions? '''

Mostly at the time I started doing this development the roles and permission
code wasn't available yet! The changes to roles and permissions are big and the
changes needed to fit in with them properly need some thought and would be even
more massive than they currently are. It seemed better to get the main
improvements to groups in first and give the roles and permissions code a bit of
time to settle. It would be nice if they are integrated sensible eventually.

''' Why do I have to deal separately with the case where the module uses groups and the case where it doesn't? Isn't there a clever way to do this so I don't have to? '''

Yes, but I wanted to try and keep people's code fairly readable and make it as
easy as possible to shift current over. In practice you shouldn't really have
too much extra code this way anyhow - you can always write functions with a
groupid argument that defaults to false.

== Future plans? (Things I'd like to do or you can do for me!) ==

In no particular order:

* Bug fixing I guess :-)
* Global groups - I want it to be possible to set up groupings for course 1 and for these to be visible for all course on the site, but not editable or deletable. I think this code should actually be quite easy to write now and I might even do it before this code is put in, just haven't done it yet.
* A nicer user interface (that doesn't break the back button :-) Ajax separates the back and front end of the code really well, so if anyone has good ideas on this, it should be quite easy for someone else to do without having to know how the internals of the groups code work.
* Integration with roles and permissions
* Sign up sheets for groups
* Proper support for blocks and global features.
* A way for modules and blocks to declare whether they support groups or not.
* Putting in search_users functionality for group permissions as well as just members of groups.
* Cool ways to set up groups automatically for particular pedagogical reasons - things like minimising overlap with groups in another grouping, creating groups just from the users all in another group and creating groups which merge pairs of groups from another grouping.

Development:Groups documentation for module developers

2006-08-21T11:18:00Z

Jvvw: /* How groups work in Moodle */

== Groups in Moodle for developers==

'''IMPORTANT:''' This documentation does not refer to current versions of Moodle
and is here at the moment purely in order to obtain comments. Descriptions of
how groups work refer to how they hopefully work not how they will work now! This document is also written in the present tense even though it doesn't refer to the current version of Moodle. This is so I don't have to go through and change it all!

=== How groups work in Moodle ===

It is possible to have groups of users in Moodle. A person with the right
permissions (generally an editting teacher or admin) can create sets of groups known as groupings for a course and then add and remove users from groups. Each
group and grouping must 'belong' to at least one course (it's possible for them to belong to more than one course, but there's no user interface to let you do this easily at the moment).

Both teachers and students can belong to groups and a user can belong
to more than one group. It is also possible for a group to belong to more than
one grouping.
If you haven't seen the interface for creating groupings and groups, I'd
recommend you go to a course in your installation of Moodle for which you have
edit access and which has some participants and follow the Groups link and take
a look (''note: you can't currently do this obviously as the code isn't released
yet!'').

There is a choice of various permission settings for a grouping - for instance
you can specify that students may both view and contribute to the group of which
they are a member but only view groups of which they are not members. In time
these settings wil hopefully be superceded by an extension of the roles and
permission system used elsewhere in Moodle, but at the moment they are
independent. The main types of permission that a user can have for a
particular group are 'student view', 'student contribute', 'teacher view' and
'teacher contribute', with it being up to modules to decide how to interpret
these. As we have seen, a user does not need to be a member of a group to have a
particular permission type for that group.

Once there is at least one grouping created for a course, when an editor adds an
instance of a module they may if they wish assign one of the groupings for the
course to use with that instance of the module. A user who is not in a group for
a grouping assigned will not be able to see that the instance of the module
exists. It is also possible for the editor to specify a grouping to use for
everything for the course - this is set up in the course settings.

As well as modules, there are also some blocks and global features such as blogs
and the calendar that use groups in certain ways. We'll come to those later.

It is obviously good if modules support groups in the ways that users expect!
This document is here to try and help you do that - if anything isn't clear, you
have questions or can think of improvements to how groups work in Moodle, please
post on the Groups forum on moodle.org.

=== How does this differ from the way groups previously worked? ===

The biggest difference is that previously it was only possible to have one set of groups for a course. All activities for a course had to use the same set of groups. This is the main reason that the API needed to change.

Also, previously, for a course with groups, there were two groups modes - separate and visible. With separate groups, students
could not see groups to which they did not belong, whereas with visible groups they could see groups to which they did not belong but not contribute to them. This caused a great deal of confusion when it came to teachers belonging to groups and also
led to lots of really horrible logic in module code trying to work out who could view or contribute to an activity. This is why the separate/visible groups modes have been replaced by a more granular and flexible permissions system.

Another big difference that isn't visible is there are now tables in the database for course_groups and courses_groupings, whereas previous the groups table had a courseid column. This made it very difficult to use the same group for more than one course. This should now be much easier. However this obviously affects code that used to access the groups table directly.

There are also improvements to the user interface for creating groups, though these aren't specifically relevant to module developers.

=== How should modules support groups? ===

There are two main ways a module might need to support groups. There may of
course be other more unusual ways in which your module should supports groups,
but these should hopefully be the most common ones. The important thing
is to think about how people would expect your module to behave if they chose to
use groups for it.

==== From a student's point of view ====

From a student's point of view, groups are generally used as a way to enable
parallel versions of the same activity with different groups of students e.g you
might want a separate forum or wiki for each group. If your module is
collaborative in any way (which includes the ability to view the existence of
other students or their contributions) then you need to make sure that this is
supported.

As well as the obvious views of activities being separated, you will need to
make sure that things like searches return the correct results and that teachers
can view the correct groups. You may also need to make a decision as to which
teacher activity is part of the setup of the activity so is the same for every
group and needs to be performed only once, and which teacher activity is the
contribution after the activity has started and so is different for each group.

In general if you module needs to support groups in this way you will find that
the database table(s) where you store the students' contributions will probably
need an extra 'groupid' column, for instance the forum table has a groupid
column.

==== From a teacher's point of view ====

From a teacher's point of view, groups are generally used to manage different
groups of students. For instance there may be several teachers on a course each
assigned to one or more groups of students who mark the work for the groups of
students that have been assigned to them but shouldn't be able to mark the work
of the other groups. A single teacher may also want to be able to view marks for
students by group when they teach the same material to two different classes. In
general, if your module enables teachers to somehow view students' contribution,
then you need to provide this type of support. You can usually do this by
checking which students are in which group rather than needing to alter the
module's database tables in any way.

==== Dealing with users in more than one group ====

Although users may be belong to more than one group, most of the time you can
use the groups library for modules to deal with this rather than having to worry
about this yourself. There will be more about this in the next section. The time
you will probably find that you need to worry about this is when for instance
you are doing a search for contributions that a particular student is allowed to
view. In this case you will need to look for contributions for all the groups
rather than just one group.

=== The groups library for modules ===
The functions at your disposal can be found in course/groups/lib/modulelib.php -
go and have a quick look at it now. (''Again you can't yet, but look here
at the [[Groups API for modules]] instead'') Here are some examples of common ways in which you might want to use
the functions in it.

1) Present a user with a page containing the right information for one of the
groups that they belong to including a selector to see the equivalent page for
any other groups that they belong to. e.g. present a user with a list of
discussion for a group they belong to.

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_STUDENT_CONTRIBUTE;
groups_m_print_group_selector($cmid, $urlroot, $permissiontype);
$currentgroupid = groups_m_get_selected_group($cmid, $permissiontype);
// This is your function that you've written.
do_whizzy_module_stuff_for_group($cmid, $currentgroupid);
} else {
// Do whatever you'd normally do
}

2) Present a user with search results only for the groups that they are allowed
to view.

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_VIEW;
$groupids = groups_m_get_groups_for_user($cmid, $permissiontype);
// You might want the search funtion to check group permissions too to be
// on the safe side.
get_module_search_results_for_groups($groupids, $maybesomeotherparameters);
} else {
// Do whatever you'd normally do
}

3) Get a list of users which a teacher should be able to mark work

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_TEACHER_CONTRIBUTE;
groups_m_print_group_selector($cmid, $urlroot, $permissiontype);
$groupid = groups_m_get_selected_group($cmid, $permissiontype);
$userids = groups_m_get_members($groupid);
} else {
// Get your userids the normal way
}
// Do whatever you'd normally do with the userids.

It is still ok to use inner joins on the groups_members table in the database
for this type of functionality as obviously this is sometimes required for
performance reasons, but make sure you keep your code that queries the database
clearly separated from your other code.

=== Support for legacy code ===

The following functions should still be supported but are deprecated:

get_groups
user_group
ismember
get_group_users
get_group_students
get_group_teachers
add_user_to_group
mygroupid
groupmode
set_current_group
get_current_group
get_and_set_current_group
setup_and_print_groups

Where appropriate, if a grouping has been specified in the course setting for
use for all activities that grouping will be used in what was previously
'separate groups' mode. If no such grouping has been specified then the first
grouping created for the course that still exists will be used, again in
separate groups mode. If you want better support than this, then I'm afraid you
will need to update the code for your module!

Accessing the groups_members table directly should still work (although it is
not recommended unless you need to do an inner join on it for performance
reasons). Directly accessing the groups table may not work because the course
column has been removed.

The groupid argument in the function search_users from datalib.php will still
work, but will only give members of a group, not those with a specific
permission.

=== Blocks and other special cases ===

There is an essentially identical library for blocks as for modules, only all
the _m_'s in the function names are replaced by _b_'s.

At the moment there is no standard way to set the grouping for a block and most
blocks don't need to use groups. If you want to create a way for someone to set
up a grouping for your block then you will need to do this yourself using the
functions in the other parts of the groups library (under course/groups/lib/)
but ask if you need help. There is a new column in the block_instance table
called groupingid that you will need to set using the function
groups_set_grouping_for_block_instance. If a grouping is set for all activities
for a course then this will get automatically set however.

There are currently two 'global' features in the Moodle core - blogs and the
calendar - a quick word on those in case anyone has plug-ins that provide
similar global features.

Calendar - with the calendar a teacher can set group events when they are within
a course, so basically all they need to do is get all the groups for the course
that a teacher has a particular permission for. Then when displaying calendar
entries to users, need to know which groups a particular has view permission
for across all courses though it's a tiny bit more complicated that this because
a grouping can be used for more than one course and someone may be a student on
one course and a teacher on another.

Blog - It's possible for the admin to set a blog option that makes blogs view
access group level. This means that users can only see blogs of people that they
share a group with for some course - there's a function provided in one of the
main groups libraries to find out if two users share a group. I'm guessing that
you're mostly only wanting to use this with installations with a very small
number of teachers and at some point global groups will get used here instead.

At the moment there is generally no general support for global features, but
this will hopefully come!

== Some rationale ==

I'll probably add stuff in here as it comes up :-)

''' Why doesn't this fit in with roles and permissions? '''

Mostly at the time I started doing this development the roles and permission
code wasn't available yet! The changes to roles and permissions are big and the
changes needed to fit in with them properly need some thought and would be even
more massive than they currently are. It seemed better to get the main
improvements to groups in first and give the roles and permissions code a bit of
time to settle. It would be nice if they are integrated sensible eventually.

''' Why do I have to deal separately with the case where the module uses groups and the case where it doesn't? Isn't there a clever way to do this so I don't have to? '''

Yes, but I wanted to try and keep people's code fairly readable and make it as
easy as possible to shift current over. In practice you shouldn't really have
too much extra code this way anyhow - you can always write functions with a
groupid argument that defaults to false.

== Future plans? (Things I'd like to do or you can do for me!) ==

In no particular order:

* Bug fixing I guess :-)
* Global groups - I want it to be possible to set up groupings for course 1 and for these to be visible for all course on the site, but not editable or deletable. I think this code should actually be quite easy to write now and I might even do it before this code is put in, just haven't done it yet.
* A nicer user interface (that doesn't break the back button :-) Ajax separates the back and front end of the code really well, so if anyone has good ideas on this, it should be quite easy for someone else to do without having to know how the internals of the groups code work.
* Integration with roles and permissions
* Sign up sheets for groups
* Proper support for blocks and global features.
* A way for modules and blocks to declare whether they support groups or not.
* Putting in search_users functionality for group permissions as well as just members of groups.
* Cool ways to set up groups automatically for particular pedagogical reasons - things like minimising overlap with groups in another grouping, creating groups just from the users all in another group and creating groups which merge pairs of groups from another grouping.

Development:Groups documentation for module developers

2006-08-21T11:17:26Z

Jvvw: /* Groups in Moodle for developers */

== Groups in Moodle for developers==

'''IMPORTANT:''' This documentation does not refer to current versions of Moodle
and is here at the moment purely in order to obtain comments. Descriptions of
how groups work refer to how they hopefully work not how they will work now! This document is also written in the present tense even though it doesn't refer to the current version of Moodle. This is so I don't have to go through and change it all!

=== How groups work in Moodle ===

It is possible to have groups of users in Moodle. A person with the right
permissions (generally an editting teacher or admin) can creates sets of groups known as groupings for a course and then add and remove users from groups. Each
group and grouping must 'belong' to at least one course (it's possible for them to belong to more than one course, but there's no user interface to let you do this easily at the moment).

Both teachers and students can belong to groups and a user can belong
to more than one group. It is also possible for a group to belong to more than
one grouping.
If you haven't seen the interface for creating groupings and groups, I'd
recommend you go to a course in your installation of Moodle for which you have
edit access and which has some participants and follow the Groups link and take
a look (''note: you can't currently do this obviously as the code isn't released
yet!'').

There is a choice of various permission settings for a grouping - for instance
you can specify that students may both view and contribute to the group of which
they are a member but only view groups of which they are not members. In time
these settings wil hopefully be superceded by an extension of the roles and
permission system used elsewhere in Moodle, but at the moment they are
independent. The main types of permission that a user can have for a
particular group are 'student view', 'student contribute', 'teacher view' and
'teacher contribute', with it being up to modules to decide how to interpret
these. As we have seen, a user does not need to be a member of a group to have a
particular permission type for that group.

Once there is at least one grouping created for a course, when an editor adds an
instance of a module they may if they wish assign one of the groupings for the
course to use with that instance of the module. A user who is not in a group for
a grouping assigned will not be able to see that the instance of the module
exists. It is also possible for the editor to specify a grouping to use for
everything for the course - this is set up in the course settings.

As well as modules, there are also some blocks and global features such as blogs
and the calendar that use groups in certain ways. We'll come to those later.

It is obviously good if modules support groups in the ways that users expect!
This document is here to try and help you do that - if anything isn't clear, you
have questions or can think of improvements to how groups work in Moodle, please
post on the Groups forum on moodle.org.

=== How does this differ from the way groups previously worked? ===

The biggest difference is that previously it was only possible to have one set of groups for a course. All activities for a course had to use the same set of groups. This is the main reason that the API needed to change.

Also, previously, for a course with groups, there were two groups modes - separate and visible. With separate groups, students
could not see groups to which they did not belong, whereas with visible groups they could see groups to which they did not belong but not contribute to them. This caused a great deal of confusion when it came to teachers belonging to groups and also
led to lots of really horrible logic in module code trying to work out who could view or contribute to an activity. This is why the separate/visible groups modes have been replaced by a more granular and flexible permissions system.

Another big difference that isn't visible is there are now tables in the database for course_groups and courses_groupings, whereas previous the groups table had a courseid column. This made it very difficult to use the same group for more than one course. This should now be much easier. However this obviously affects code that used to access the groups table directly.

There are also improvements to the user interface for creating groups, though these aren't specifically relevant to module developers.

=== How should modules support groups? ===

There are two main ways a module might need to support groups. There may of
course be other more unusual ways in which your module should supports groups,
but these should hopefully be the most common ones. The important thing
is to think about how people would expect your module to behave if they chose to
use groups for it.

==== From a student's point of view ====

From a student's point of view, groups are generally used as a way to enable
parallel versions of the same activity with different groups of students e.g you
might want a separate forum or wiki for each group. If your module is
collaborative in any way (which includes the ability to view the existence of
other students or their contributions) then you need to make sure that this is
supported.

As well as the obvious views of activities being separated, you will need to
make sure that things like searches return the correct results and that teachers
can view the correct groups. You may also need to make a decision as to which
teacher activity is part of the setup of the activity so is the same for every
group and needs to be performed only once, and which teacher activity is the
contribution after the activity has started and so is different for each group.

In general if you module needs to support groups in this way you will find that
the database table(s) where you store the students' contributions will probably
need an extra 'groupid' column, for instance the forum table has a groupid
column.

==== From a teacher's point of view ====

From a teacher's point of view, groups are generally used to manage different
groups of students. For instance there may be several teachers on a course each
assigned to one or more groups of students who mark the work for the groups of
students that have been assigned to them but shouldn't be able to mark the work
of the other groups. A single teacher may also want to be able to view marks for
students by group when they teach the same material to two different classes. In
general, if your module enables teachers to somehow view students' contribution,
then you need to provide this type of support. You can usually do this by
checking which students are in which group rather than needing to alter the
module's database tables in any way.

==== Dealing with users in more than one group ====

Although users may be belong to more than one group, most of the time you can
use the groups library for modules to deal with this rather than having to worry
about this yourself. There will be more about this in the next section. The time
you will probably find that you need to worry about this is when for instance
you are doing a search for contributions that a particular student is allowed to
view. In this case you will need to look for contributions for all the groups
rather than just one group.

=== The groups library for modules ===
The functions at your disposal can be found in course/groups/lib/modulelib.php -
go and have a quick look at it now. (''Again you can't yet, but look here
at the [[Groups API for modules]] instead'') Here are some examples of common ways in which you might want to use
the functions in it.

1) Present a user with a page containing the right information for one of the
groups that they belong to including a selector to see the equivalent page for
any other groups that they belong to. e.g. present a user with a list of
discussion for a group they belong to.

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_STUDENT_CONTRIBUTE;
groups_m_print_group_selector($cmid, $urlroot, $permissiontype);
$currentgroupid = groups_m_get_selected_group($cmid, $permissiontype);
// This is your function that you've written.
do_whizzy_module_stuff_for_group($cmid, $currentgroupid);
} else {
// Do whatever you'd normally do
}

2) Present a user with search results only for the groups that they are allowed
to view.

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_VIEW;
$groupids = groups_m_get_groups_for_user($cmid, $permissiontype);
// You might want the search funtion to check group permissions too to be
// on the safe side.
get_module_search_results_for_groups($groupids, $maybesomeotherparameters);
} else {
// Do whatever you'd normally do
}

3) Get a list of users which a teacher should be able to mark work

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_TEACHER_CONTRIBUTE;
groups_m_print_group_selector($cmid, $urlroot, $permissiontype);
$groupid = groups_m_get_selected_group($cmid, $permissiontype);
$userids = groups_m_get_members($groupid);
} else {
// Get your userids the normal way
}
// Do whatever you'd normally do with the userids.

It is still ok to use inner joins on the groups_members table in the database
for this type of functionality as obviously this is sometimes required for
performance reasons, but make sure you keep your code that queries the database
clearly separated from your other code.

=== Support for legacy code ===

The following functions should still be supported but are deprecated:

get_groups
user_group
ismember
get_group_users
get_group_students
get_group_teachers
add_user_to_group
mygroupid
groupmode
set_current_group
get_current_group
get_and_set_current_group
setup_and_print_groups

Where appropriate, if a grouping has been specified in the course setting for
use for all activities that grouping will be used in what was previously
'separate groups' mode. If no such grouping has been specified then the first
grouping created for the course that still exists will be used, again in
separate groups mode. If you want better support than this, then I'm afraid you
will need to update the code for your module!

Accessing the groups_members table directly should still work (although it is
not recommended unless you need to do an inner join on it for performance
reasons). Directly accessing the groups table may not work because the course
column has been removed.

The groupid argument in the function search_users from datalib.php will still
work, but will only give members of a group, not those with a specific
permission.

=== Blocks and other special cases ===

There is an essentially identical library for blocks as for modules, only all
the _m_'s in the function names are replaced by _b_'s.

At the moment there is no standard way to set the grouping for a block and most
blocks don't need to use groups. If you want to create a way for someone to set
up a grouping for your block then you will need to do this yourself using the
functions in the other parts of the groups library (under course/groups/lib/)
but ask if you need help. There is a new column in the block_instance table
called groupingid that you will need to set using the function
groups_set_grouping_for_block_instance. If a grouping is set for all activities
for a course then this will get automatically set however.

There are currently two 'global' features in the Moodle core - blogs and the
calendar - a quick word on those in case anyone has plug-ins that provide
similar global features.

Calendar - with the calendar a teacher can set group events when they are within
a course, so basically all they need to do is get all the groups for the course
that a teacher has a particular permission for. Then when displaying calendar
entries to users, need to know which groups a particular has view permission
for across all courses though it's a tiny bit more complicated that this because
a grouping can be used for more than one course and someone may be a student on
one course and a teacher on another.

Blog - It's possible for the admin to set a blog option that makes blogs view
access group level. This means that users can only see blogs of people that they
share a group with for some course - there's a function provided in one of the
main groups libraries to find out if two users share a group. I'm guessing that
you're mostly only wanting to use this with installations with a very small
number of teachers and at some point global groups will get used here instead.

At the moment there is generally no general support for global features, but
this will hopefully come!

== Some rationale ==

I'll probably add stuff in here as it comes up :-)

''' Why doesn't this fit in with roles and permissions? '''

Mostly at the time I started doing this development the roles and permission
code wasn't available yet! The changes to roles and permissions are big and the
changes needed to fit in with them properly need some thought and would be even
more massive than they currently are. It seemed better to get the main
improvements to groups in first and give the roles and permissions code a bit of
time to settle. It would be nice if they are integrated sensible eventually.

''' Why do I have to deal separately with the case where the module uses groups and the case where it doesn't? Isn't there a clever way to do this so I don't have to? '''

Yes, but I wanted to try and keep people's code fairly readable and make it as
easy as possible to shift current over. In practice you shouldn't really have
too much extra code this way anyhow - you can always write functions with a
groupid argument that defaults to false.

== Future plans? (Things I'd like to do or you can do for me!) ==

In no particular order:

* Bug fixing I guess :-)
* Global groups - I want it to be possible to set up groupings for course 1 and for these to be visible for all course on the site, but not editable or deletable. I think this code should actually be quite easy to write now and I might even do it before this code is put in, just haven't done it yet.
* A nicer user interface (that doesn't break the back button :-) Ajax separates the back and front end of the code really well, so if anyone has good ideas on this, it should be quite easy for someone else to do without having to know how the internals of the groups code work.
* Integration with roles and permissions
* Sign up sheets for groups
* Proper support for blocks and global features.
* A way for modules and blocks to declare whether they support groups or not.
* Putting in search_users functionality for group permissions as well as just members of groups.
* Cool ways to set up groups automatically for particular pedagogical reasons - things like minimising overlap with groups in another grouping, creating groups just from the users all in another group and creating groups which merge pairs of groups from another grouping.

Development:Groups API for modules

2006-08-21T08:51:32Z

Jvvw:

<?php
/*******************************************************************************
* modulelib.php
*
* This file contains functions to be used by modules to support groups. More
* documentation is available on the Developer's Notes section of the Moodle
* wiki.
*
* For queries, suggestions for improvements etc. please post on the Groups
* forum on the moodle.org site.
******************************************************************************/

/*******************************************************************************
* Permission types
*
* There are six types of permission that a user can hold for a particular
* group - 'student view', 'student contribute', 'teacher view',
* 'teacher contribute', 'view members list' and 'view group existence'.
*
* A particular user need not to be a member of the group to have a specific
* permission and may have more than one permission type. The permission that a
* particular user has for a group used by an particular instance of the module
* depends on whether the student is a teacher or student for the course and on
* the settings for the set of groups (the 'grouping') being used by the
* instance of the module
*
* It is up to each module to decide how to interpret the different permission
* types. The only exception is with 'view members list' and 'view group
* existence'. The former means that the user can view the members of the group
* while the latter means that the user can view information such as the group
* name and description. It is possible that a user may have 'view members list'
* permission without 'view group existence' permission - the members would just
* appear as the other users on the course.
*
* Permission types can be combined with boolean expressions where they are used
* if necessary.
*
* @name GROUPS_STUDENT Either 'student view' or 'student contribute' permission
* @name GROUPS_TEACHER Either 'teacher view' or 'teacher contribute' permission
* @name GROUPS_VIEW Either 'teacher view' or 'student view' permission
* @name GROUPS_CONTRIBUTE Either 'teacher contribute' or 'student contribute'
* permission
* @name GROUPS_VIEW_GROUP_EXISTENCE 'view group existence' permission
* @name GROUPS_VIEW_MEMBERS_LIST 'view members list' permission
* @name GROUPS_STUDENT_VIEW 'student view' permission
* @name GROUPS_STUDENT_CONTRIBUTE 'student contribute' permission
* @name GROUPS_TEACHER_VIEW 'teacher view' permission
* @name GROUPS_TEACHER_CONTRIBUTE 'teacher contribute' permission
******************************************************************************/
define('GROUPS_STUDENT', 1);
define('GROUPS_TEACHER', 2);
define('GROUPS_VIEW', 4);
define('GROUPS_CONTRIBUTE', 8);
define('GROUPS_VIEW_GROUP_EXISTENCE', 16);
define('GROUPS_VIEW_MEMBERS_LIST', 48);
define('GROUPS_STUDENT_VIEW', 5);
define('GROUPS_STUDENT_CONTRIBUTE', 9);
define('GROUPS_TEACHER_VIEW', 6);
define('GROUPS_TEACHER_CONTRIBUTE', 10);

/**
* Indicates if the instance of the module has been set up by an editor of the
* course to use groups. This functionality can also be obtained using the
* groups_m_get_groups() function, however it is sufficiently commonly needed
* that this separate function has been provided and should be used instead.
* @param int $cmid The id of the module instance
* @return boolean True if the instance is set up to use groups, false otherwise
*/
function groups_m_uses_groups($cmid) {
}

/**
* Prints a dropdown box to enable a user to select between the groups for the
* module instance of which they are a member. If a user belongs to 0 or 1
* groups, no form is printed. The dropdown box belongs to a form and when a
* user clicks on the box this form is automatically submitted so that the page
* knows about the change.
* @param int $cmid The id of the module instance
* @param string $urlroot The url of the page - this is necessary so the form
* can submit to the correct page.
* @param int $permissiontype - see note on permissiontypes above.
* @return boolean True unless an error occurred or the module instance does not
* use groups in which case returns false.
*/
function groups_m_print_group_selector($cmid, $urlroot, $permissiontype) {
}

/**
* Gets the group that a student has selected from the drop-down menu printed
* by groups_m_print_group_selector and checks that the student has the
* specified permission for the group and that the group is one of the groups
* assigned for this module instance.
*
* Groups selected are saved between page changes within the module instance but
* not necessarily if the user leaves the instance e.g. returns to the main
* course page. If the selector has not been printed anywhere during the user's
* 'visit' to the module instance, then the function returns false. This means
* that you need to be particularly careful about pages that might be
* bookmarked by the user.
*
* @uses $USER
* @param int $cmid The id of the module instance
* @param int $permissiontype The permission type - see note on permission types
* above
* @param int $userid The id of the user, defaults to the current user
* @return boolean True if no error occurred, false otherwise.
*/
function groups_m_get_selected_group($cmid, $permissiontype,
$userid = $USER->id) {
}

/**
* Gets an array of the groupids of all the groups that the specified user has
* particular permission for in this particular instance of the module
* @uses $USER
* @param int $cmid The id of the module instance
* @param int $permissiontype The permission type - see note on permission types
* above
* @param int $userid The id of the user, defaults to the current user
* @return array An array of the group ids
*/
function groups_m_get_groups_for_user($cmid, $permissiontype,
$userid = $USER->id) {
}

/**
* Indicates if a specified user has a particular type of permission for a
* particular group for this module instance.
* @uses $USER
* @param int $cmid The id of the module instance. This is necessary because the
* same group can be used in different module instances with different
* permission setups.
* @param int $groupid The id of the group
* @param int $permissiontype The permission type - see note on permission types
* above
* @userid int $userid The id of the user, defaults to the current user
* @return boolean True if the user has the specified permission type, false
* otherwise or if an error occurred.
*/
function groups_m_has_permission($cmid, $groupid, $permissiontype,
$userid = $USER->id) {
}

/**
* Gets an array of members of a group that have a particular permission type
* for this instance of the module and that are enrolled on the course that
* the module instance belongs to.
*
* @param int $cmid The id of the module instance. This is necessary because the
* same group can be used in different module instances with different
* permission setups.
* @param int $groupid The id of the group
* @param int $permissiontype The permission type - see note on permission types
* above
* @return array An array containing the ids of the users with the specified
* permission.
*/
function groups_m_get_members_with_permission($cmid, $groupid,
$permissiontype) {
}

/**
* Gets the group object associated with a group id. This group object can be
* used to get information such as the name of the group and the file for the
* group icon if it exists. (Look at the groups table in the database to see
* the fields).
* @param int $groupid The id of the group
* @return group The group object
*/
function groups_m_get_group($groupid) {
}

/**
* Gets the groups for the module instance. In general, you should use
* groups_m_get_groups_for_user, however this function is provided for
* circumstances where this function isn't sufficient for some reason.
* @param int $cmid The id of the module instance.
* @return array An array of the ids of the groups for the module instance
*/
function groups_m_get_groups($cmid) {
}

/**
* Gets the members of group that are enrolled on the course that the specified
* module instance belongs to.
* @param int $cmid The id of the module instance
* @param int $groupid The id of the group
* @return array An array of the userids of the members.
*/
function groups_m_get_members($cmid, $groupid) {
}

/**
* Indicates if a user is a member of a particular group. In general you should
* use groups_m_has_permission, however this function is provided for
* circumstances where this function isn't sufficient for some reason.
* @param int $groupid The id of the group
* @param int $userid The id of the user
* @return boolean True if the user is a member of the group, false otherwise
*/
function groups_m_is_member($groupid, $userid) {
}
?>

Development:Groups documentation for module developers

2006-08-21T08:46:03Z

Jvvw:

== Groups in Moodle for developers==

'''IMPORTANT:''' This documentation does not refer to current versions of Moodle
and is here at the moment purely in order to obtain comments. Descriptions of
how groups work refer to how they hopefully work not how they will work now!

=== How groups work in Moodle ===

It is possible to have groups of users in Moodle. A person with the right
permissions (generally an editting teacher or admin) can creates sets of groups known as groupings for a course and then add and remove users from groups. Each
group and grouping must 'belong' to at least one course (it's possible for them to belong to more than one course, but there's no user interface to let you do this easily at the moment).

Both teachers and students can belong to groups and a user can belong
to more than one group. It is also possible for a group to belong to more than
one grouping.
If you haven't seen the interface for creating groupings and groups, I'd
recommend you go to a course in your installation of Moodle for which you have
edit access and which has some participants and follow the Groups link and take
a look (''note: you can't currently do this obviously as the code isn't released
yet!'').

There is a choice of various permission settings for a grouping - for instance
you can specify that students may both view and contribute to the group of which
they are a member but only view groups of which they are not members. In time
these settings wil hopefully be superceded by an extension of the roles and
permission system used elsewhere in Moodle, but at the moment they are
independent. The main types of permission that a user can have for a
particular group are 'student view', 'student contribute', 'teacher view' and
'teacher contribute', with it being up to modules to decide how to interpret
these. As we have seen, a user does not need to be a member of a group to have a
particular permission type for that group.

Once there is at least one grouping created for a course, when an editor adds an
instance of a module they may if they wish assign one of the groupings for the
course to use with that instance of the module. A user who is not in a group for
a grouping assigned will not be able to see that the instance of the module
exists. It is also possible for the editor to specify a grouping to use for
everything for the course - this is set up in the course settings.

As well as modules, there are also some blocks and global features such as blogs
and the calendar that use groups in certain ways. We'll come to those later.

It is obviously good if modules support groups in the ways that users expect!
This document is here to try and help you do that - if anything isn't clear, you
have questions or can think of improvements to how groups work in Moodle, please
post on the Groups forum on moodle.org.

=== How should modules support groups? ===

There are two main ways a module might need to support groups. There may of
course be other more unusual ways in which your module should supports groups,
but these should hopefully be the most common ones. The important thing
is to think about how people would expect your module to behave if they chose to
use groups for it.

==== From a student's point of view ====

From a student's point of view, groups are generally used as a way to enable
parallel versions of the same activity with different groups of students e.g you
might want a separate forum or wiki for each group. If your module is
collaborative in any way (which includes the ability to view the existence of
other students or their contributions) then you need to make sure that this is
supported.

As well as the obvious views of activities being separated, you will need to
make sure that things like searches return the correct results and that teachers
can view the correct groups. You may also need to make a decision as to which
teacher activity is part of the setup of the activity so is the same for every
group and needs to be performed only once, and which teacher activity is the
contribution after the activity has started and so is different for each group.

In general if you module needs to support groups in this way you will find that
the database table(s) where you store the students' contributions will probably
need an extra 'groupid' column, for instance the forum table has a groupid
column.

==== From a teacher's point of view ====

From a teacher's point of view, groups are generally used to manage different
groups of students. For instance there may be several teachers on a course each
assigned to one or more groups of students who mark the work for the groups of
students that have been assigned to them but shouldn't be able to mark the work
of the other groups. A single teacher may also want to be able to view marks for
students by group when they teach the same material to two different classes. In
general, if your module enables teachers to somehow view students' contribution,
then you need to provide this type of support. You can usually do this by
checking which students are in which group rather than needing to alter the
module's database tables in any way.

==== Dealing with users in more than one group ====

Although users may be belong to more than one group, most of the time you can
use the groups library for modules to deal with this rather than having to worry
about this yourself. There will be more about this in the next section. The time
you will probably find that you need to worry about this is when for instance
you are doing a search for contributions that a particular student is allowed to
view. In this case you will need to look for contributions for all the groups
rather than just one group.

=== The groups library for modules ===
The functions at your disposal can be found in course/groups/lib/modulelib.php -
go and have a quick look at it now. (''Again you can't yet, but look here
at the [[Groups API for modules]] instead'') Here are some examples of common ways in which you might want to use
the functions in it.

1) Present a user with a page containing the right information for one of the
groups that they belong to including a selector to see the equivalent page for
any other groups that they belong to. e.g. present a user with a list of
discussion for a group they belong to.

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_STUDENT_CONTRIBUTE;
groups_m_print_group_selector($cmid, $urlroot, $permissiontype);
$currentgroupid = groups_m_get_selected_group($cmid, $permissiontype);
// This is your function that you've written.
do_whizzy_module_stuff_for_group($cmid, $currentgroupid);
} else {
// Do whatever you'd normally do
}

2) Present a user with search results only for the groups that they are allowed
to view.

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_VIEW;
$groupids = groups_m_get_groups_for_user($cmid, $permissiontype);
// You might want the search funtion to check group permissions too to be
// on the safe side.
get_module_search_results_for_groups($groupids, $maybesomeotherparameters);
} else {
// Do whatever you'd normally do
}

3) Get a list of users which a teacher should be able to mark work

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_TEACHER_CONTRIBUTE;
groups_m_print_group_selector($cmid, $urlroot, $permissiontype);
$groupid = groups_m_get_selected_group($cmid, $permissiontype);
$userids = groups_m_get_members($groupid);
} else {
// Get your userids the normal way
}
// Do whatever you'd normally do with the userids.

It is still ok to use inner joins on the groups_members table in the database
for this type of functionality as obviously this is sometimes required for
performance reasons, but make sure you keep your code that queries the database
clearly separated from your other code.

=== Support for legacy code ===

The following functions should still be supported but are deprecated:

get_groups
user_group
ismember
get_group_users
get_group_students
get_group_teachers
add_user_to_group
mygroupid
groupmode
set_current_group
get_current_group
get_and_set_current_group
setup_and_print_groups

Where appropriate, if a grouping has been specified in the course setting for
use for all activities that grouping will be used in what was previously
'separate groups' mode. If no such grouping has been specified then the first
grouping created for the course that still exists will be used, again in
separate groups mode. If you want better support than this, then I'm afraid you
will need to update the code for your module!

Accessing the groups_members table directly should still work (although it is
not recommended unless you need to do an inner join on it for performance
reasons). Directly accessing the groups table may not work because the course
column has been removed.

The groupid argument in the function search_users from datalib.php will still
work, but will only give members of a group, not those with a specific
permission.

=== Blocks and other special cases ===

There is an essentially identical library for blocks as for modules, only all
the _m_'s in the function names are replaced by _b_'s.

At the moment there is no standard way to set the grouping for a block and most
blocks don't need to use groups. If you want to create a way for someone to set
up a grouping for your block then you will need to do this yourself using the
functions in the other parts of the groups library (under course/groups/lib/)
but ask if you need help. There is a new column in the block_instance table
called groupingid that you will need to set using the function
groups_set_grouping_for_block_instance. If a grouping is set for all activities
for a course then this will get automatically set however.

There are currently two 'global' features in the Moodle core - blogs and the
calendar - a quick word on those in case anyone has plug-ins that provide
similar global features.

Calendar - with the calendar a teacher can set group events when they are within
a course, so basically all they need to do is get all the groups for the course
that a teacher has a particular permission for. Then when displaying calendar
entries to users, need to know which groups a particular has view permission
for across all courses though it's a tiny bit more complicated that this because
a grouping can be used for more than one course and someone may be a student on
one course and a teacher on another.

Blog - It's possible for the admin to set a blog option that makes blogs view
access group level. This means that users can only see blogs of people that they
share a group with for some course - there's a function provided in one of the
main groups libraries to find out if two users share a group. I'm guessing that
you're mostly only wanting to use this with installations with a very small
number of teachers and at some point global groups will get used here instead.

At the moment there is generally no general support for global features, but
this will hopefully come!

== Some rationale ==

I'll probably add stuff in here as it comes up :-)

''' Why doesn't this fit in with roles and permissions? '''

Mostly at the time I started doing this development the roles and permission
code wasn't available yet! The changes to roles and permissions are big and the
changes needed to fit in with them properly need some thought and would be even
more massive than they currently are. It seemed better to get the main
improvements to groups in first and give the roles and permissions code a bit of
time to settle. It would be nice if they are integrated sensible eventually.

''' Why do I have to deal separately with the case where the module uses groups and the case where it doesn't? Isn't there a clever way to do this so I don't have to? '''

Yes, but I wanted to try and keep people's code fairly readable and make it as
easy as possible to shift current over. In practice you shouldn't really have
too much extra code this way anyhow - you can always write functions with a
groupid argument that defaults to false.

== Future plans? (Things I'd like to do or you can do for me!) ==

In no particular order:

* Bug fixing I guess :-)
* Global groups - I want it to be possible to set up groupings for course 1 and for these to be visible for all course on the site, but not editable or deletable. I think this code should actually be quite easy to write now and I might even do it before this code is put in, just haven't done it yet.
* A nicer user interface (that doesn't break the back button :-) Ajax separates the back and front end of the code really well, so if anyone has good ideas on this, it should be quite easy for someone else to do without having to know how the internals of the groups code work.
* Integration with roles and permissions
* Sign up sheets for groups
* Proper support for blocks and global features.
* A way for modules and blocks to declare whether they support groups or not.
* Putting in search_users functionality for group permissions as well as just members of groups.
* Cool ways to set up groups automatically for particular pedagogical reasons - things like minimising overlap with groups in another grouping, creating groups just from the users all in another group and creating groups which merge pairs of groups from another grouping.

Development:Groups documentation for module developers

2006-08-21T08:45:20Z

Jvvw:

== Groups in Moodle for developers==

'''IMPORTANT:''' This documentation does not refer to current versions of Moodle
and is here at the moment purely in order to obtain comments. Descriptions of
how groups work refer to how they hopefully work not how they will work now!

=== How groups work in Moodle ===

It is possible to have groups of users in Moodle. A person with the right
permissions (generally an editting teacher or admin) can creates sets of groups known as groupings for a course and then add and remove users from groups. Each
group and grouping must 'belong' to at least one course (it's possible for them to belong to more than one course, but there's no user interface to let you do this easily at the moment).

Both teachers and students can belong to groups and a user can belong
to more than one group. It is also possible for a group to belong to more than
one grouping.
If you haven't seen the interface for creating groupings and groups, I'd
recommend you go to a course in your installation of Moodle for which you have
edit access and which has some participants and follow the Groups link and take
a look (''note: you can't currently do this obviously as the code isn't released
yet!'').

There is a choice of various permission settings for a grouping - for instance
you can specify that students may both view and contribute to the group of which
they are a member but only view groups of which they are not members. In time
these settings wil hopefully be superceded by an extension of the roles and
permission system used elsewhere in Moodle, but at the moment they are
independent. The main types of permission that a user can have for a
particular group are 'student view', 'student contribute', 'teacher view' and
'teacher contribute', with it being up to modules to decide how to interpret
these. As we have seen, a user does not need to be a member of a group to have a
particular permission type for that group.

Once there is at least one grouping created for a course, when an editor adds an
instance of a module they may if they wish assign one of the groupings for the
course to use with that instance of the module. A user who is not in a group for
a grouping assigned will not be able to see that the instance of the module
exists. It is also possible for the editor to specify a grouping to use for
everything for the course - this is set up in the course settings.

As well as modules, there are also some blocks and global features such as blogs
and the calendar that use groups in certain ways. We'll come to those later.

It is obviously good if modules support groups in the ways that users expect!
This document is here to try and help you do that - if anything isn't clear, you
have questions or can think of improvements to how groups work in Moodle, please
post on the Groups forum on moodle.org.

=== How should modules support groups? ===

There are two main ways a module might need to support groups. There may of
course be other more unusual ways in which your module should supports groups,
but these should hopefully be the most common ones. The important thing
is to think about how people would expect your module to behave if they chose to
use groups for it.

==== From a student's point of view ====

From a student's point of view, groups are generally used as a way to enable
parallel versions of the same activity with different groups of students e.g you
might want a separate forum or wiki for each group. If your module is
collaborative in any way (which includes the ability to view the existence of
other students or their contributions) then you need to make sure that this is
supported.

As well as the obvious views of activities being separated, you will need to
make sure that things like searches return the correct results and that teachers
can view the correct groups. You may also need to make a decision as to which
teacher activity is part of the setup of the activity so is the same for every
group and needs to be performed only once, and which teacher activity is the
contribution after the activity has started and so is different for each group.

In general if you module needs to support groups in this way you will find that
the database table(s) where you store the students' contributions will probably
need an extra 'groupid' column, for instance the forum table has a groupid
column.

==== From a teacher's point of view ====

From a teacher's point of view, groups are generally used to manage different
groups of students. For instance there may be several teachers on a course each
assigned to one or more groups of students who mark the work for the groups of
students that have been assigned to them but shouldn't be able to mark the work
of the other groups. A single teacher may also want to be able to view marks for
students by group when they teach the same material to two different classes. In
general, if your module enables teachers to somehow view students' contribution,
then you need to provide this type of support. You can usually do this by
checking which students are in which group rather than needing to alter the
module's database tables in any way.

==== Dealing with users in more than one group ====

Although users may be belong to more than one group, most of the time you can
use the groups library for modules to deal with this rather than having to worry
about this yourself. There will be more about this in the next section. The time
you will probably find that you need to worry about this is when for instance
you are doing a search for contributions that a particular student is allowed to
view. In this case you will need to look for contributions for all the groups
rather than just one group.

=== The groups library for modules ===
The functions at your disposal can be found in course/groups/lib/modulelib.php -
go and have a quick look at it now. (''Again you can't yet, but look here
instead'') Here are some examples of common ways in which you might want to use
the functions in it.

1) Present a user with a page containing the right information for one of the
groups that they belong to including a selector to see the equivalent page for
any other groups that they belong to. e.g. present a user with a list of
discussion for a group they belong to.

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_STUDENT_CONTRIBUTE;
groups_m_print_group_selector($cmid, $urlroot, $permissiontype);
$currentgroupid = groups_m_get_selected_group($cmid, $permissiontype);
// This is your function that you've written.
do_whizzy_module_stuff_for_group($cmid, $currentgroupid);
} else {
// Do whatever you'd normally do
}

2) Present a user with search results only for the groups that they are allowed
to view.

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_VIEW;
$groupids = groups_m_get_groups_for_user($cmid, $permissiontype);
// You might want the search funtion to check group permissions too to be
// on the safe side.
get_module_search_results_for_groups($groupids, $maybesomeotherparameters);
} else {
// Do whatever you'd normally do
}

3) Get a list of users which a teacher should be able to mark work

if (groups_m_uses_groups($cmid)) {
$permissiontype = GROUPS_TEACHER_CONTRIBUTE;
groups_m_print_group_selector($cmid, $urlroot, $permissiontype);
$groupid = groups_m_get_selected_group($cmid, $permissiontype);
$userids = groups_m_get_members($groupid);
} else {
// Get your userids the normal way
}
// Do whatever you'd normally do with the userids.

It is still ok to use inner joins on the groups_members table in the database
for this type of functionality as obviously this is sometimes required for
performance reasons, but make sure you keep your code that queries the database
clearly separated from your other code.

=== Support for legacy code ===

The following functions should still be supported but are deprecated:

get_groups
user_group
ismember
get_group_users
get_group_students
get_group_teachers
add_user_to_group
mygroupid
groupmode
set_current_group
get_current_group
get_and_set_current_group
setup_and_print_groups

Where appropriate, if a grouping has been specified in the course setting for
use for all activities that grouping will be used in what was previously
'separate groups' mode. If no such grouping has been specified then the first
grouping created for the course that still exists will be used, again in
separate groups mode. If you want better support than this, then I'm afraid you
will need to update the code for your module!

Accessing the groups_members table directly should still work (although it is
not recommended unless you need to do an inner join on it for performance
reasons). Directly accessing the groups table may not work because the course
column has been removed.

The groupid argument in the function search_users from datalib.php will still
work, but will only give members of a group, not those with a specific
permission.

=== Blocks and other special cases ===

There is an essentially identical library for blocks as for modules, only all
the _m_'s in the function names are replaced by _b_'s.

At the moment there is no standard way to set the grouping for a block and most
blocks don't need to use groups. If you want to create a way for someone to set
up a grouping for your block then you will need to do this yourself using the
functions in the other parts of the groups library (under course/groups/lib/)
but ask if you need help. There is a new column in the block_instance table
called groupingid that you will need to set using the function
groups_set_grouping_for_block_instance. If a grouping is set for all activities
for a course then this will get automatically set however.

There are currently two 'global' features in the Moodle core - blogs and the
calendar - a quick word on those in case anyone has plug-ins that provide
similar global features.

Calendar - with the calendar a teacher can set group events when they are within
a course, so basically all they need to do is get all the groups for the course
that a teacher has a particular permission for. Then when displaying calendar
entries to users, need to know which groups a particular has view permission
for across all courses though it's a tiny bit more complicated that this because
a grouping can be used for more than one course and someone may be a student on
one course and a teacher on another.

Blog - It's possible for the admin to set a blog option that makes blogs view
access group level. This means that users can only see blogs of people that they
share a group with for some course - there's a function provided in one of the
main groups libraries to find out if two users share a group. I'm guessing that
you're mostly only wanting to use this with installations with a very small
number of teachers and at some point global groups will get used here instead.

At the moment there is generally no general support for global features, but
this will hopefully come!

== Some rationale ==

I'll probably add stuff in here as it comes up :-)

''' Why doesn't this fit in with roles and permissions? '''

Mostly at the time I started doing this development the roles and permission
code wasn't available yet! The changes to roles and permissions are big and the
changes needed to fit in with them properly need some thought and would be even
more massive than they currently are. It seemed better to get the main
improvements to groups in first and give the roles and permissions code a bit of
time to settle. It would be nice if they are integrated sensible eventually.

''' Why do I have to deal separately with the case where the module uses groups and the case where it doesn't? Isn't there a clever way to do this so I don't have to? '''

Yes, but I wanted to try and keep people's code fairly readable and make it as
easy as possible to shift current over. In practice you shouldn't really have
too much extra code this way anyhow - you can always write functions with a
groupid argument that defaults to false.

== Future plans? (Things I'd like to do or you can do for me!) ==

In no particular order:

* Bug fixing I guess :-)
* Global groups - I want it to be possible to set up groupings for course 1 and for these to be visible for all course on the site, but not editable or deletable. I think this code should actually be quite easy to write now and I might even do it before this code is put in, just haven't done it yet.
* A nicer user interface (that doesn't break the back button :-) Ajax separates the back and front end of the code really well, so if anyone has good ideas on this, it should be quite easy for someone else to do without having to know how the internals of the groups code work.
* Integration with roles and permissions
* Sign up sheets for groups
* Proper support for blocks and global features.
* A way for modules and blocks to declare whether they support groups or not.
* Putting in search_users functionality for group permissions as well as just members of groups.
* Cool ways to set up groups automatically for particular pedagogical reasons - things like minimising overlap with groups in another grouping, creating groups just from the users all in another group and creating groups which merge pairs of groups from another grouping.

Development:Developer notes

2006-08-21T08:38:55Z

Jvvw: /* Core code */

<p class="note"> '''Note for contributors:''' This area is for developers to work on various bits of code and documentation as necessary. Once material has matured it should be linked to from the main [[Developer documentation]] page.</p>

==Core code==

*[[Other lang issues|Language issues]]
*[[Datalib Notes]]
*[[Application/session variables]]
*[[Roles]]
*[[Filters schema]]
*[[Filterall support]]
*[[Moodle forms library]]
*[[Martin form notes]]
*[[Groups documentation for module developers]]

==Modules and other recognised plugin types==

*[[Forum development|Forum functional upgrade]]
*[[Blogs and forums|Blogs, forums and the nature of discussion]]
*[[Conditional activities]]
*[[Wiki development|Wiki module development]]
*[[Improved Payment Plugin]]
*[[Calculated question development]]
*[[Cleanups required in the quiz and question bank]]

==Other==

*[[MoodleDocs development]]
*[[Usability]]
*[[Document Management API]]
*[[wikindx|Possible integration of WIKINDX with Moodle]]
*[[simple web services]]

''I split this into three categories becuase the list was getting a bit long.''--[[User:Tim Hunt|Tim Hunt]] 00:34, 17 August 2006 (WST)

[[Category:Developer]]

Development:Developer notes

2006-08-21T08:38:34Z

Jvvw:

<p class="note"> '''Note for contributors:''' This area is for developers to work on various bits of code and documentation as necessary. Once material has matured it should be linked to from the main [[Developer documentation]] page.</p>

==Core code==

*[[Other lang issues|Language issues]]
*[[Datalib Notes]]
*[[Application/session variables]]
*[[Roles]]
*[[Filters schema]]
*[[Filterall support]]
*[[Moodle forms library]]
*[[Martin form notes]]
*[[Groups]]

==Modules and other recognised plugin types==

*[[Forum development|Forum functional upgrade]]
*[[Blogs and forums|Blogs, forums and the nature of discussion]]
*[[Conditional activities]]
*[[Wiki development|Wiki module development]]
*[[Improved Payment Plugin]]
*[[Calculated question development]]
*[[Cleanups required in the quiz and question bank]]

==Other==

*[[MoodleDocs development]]
*[[Usability]]
*[[Document Management API]]
*[[wikindx|Possible integration of WIKINDX with Moodle]]
*[[simple web services]]

''I split this into three categories becuase the list was getting a bit long.''--[[User:Tim Hunt|Tim Hunt]] 00:34, 17 August 2006 (WST)

[[Category:Developer]]

Development:Datalib notes

2006-07-28T13:54:34Z

Jvvw: /* General Datalib usage Notes */

== General Datalib usage Notes ==

Couple of discussion threads about usage of datalib are [http://moodle.org/mod/forum/discuss.php?d=43456 here] and [http://moodle.org/mod/forum/discuss.php?d=38183 here].

== Advanced Usage: get_recordset() ==

There's a new series of function calls in datalib that were introduced shortly after 1.5: get_recordset() and friends. It takes a bit of work to make good use of them, they are definitely useful.

The function calls themselves take similar parameters to the get_records() family, and return an AdoDB recordset. In most situations, the right thing is to use get_records(), making sure that you are selecting a limited number of records (use LIMIT of course wink ), and that you are clearly fetching only the fields you need. That is enough for 99% of the cases. Stop reading now, use get_records(), and done.

Easy!

Now, there are some cases where we need to perform huge selects. And the downside of the get_records() machinery is that it allocates it all in RAM -- and if indeed records > than RAM, we are in trouble. This mostly affects batch processing in admin/cron.php (backups for instance) and the silly sync scripts we have in some auth and enrolment plugins.

In those cases, where you have no option but to SELECT all the users, or all the courses, get_recordset() really shines. As you get an AdoDB recordset, you can iterate through it very fast, and with very low memory usage. I have prepared and profiled some samples and found that to keep that advantage you have to be very careful how you use it.

I started testing with a large mdl_user table with 46K users, stored in PostgreSQL locally (socket connection). Here is a rundown of the code and rough timings...

The traditional get_records() is fast (~14s), but it consumes 296MB of memory. It looks like:

$users = get_records('user');

So the next thing was to check that just triggering the SELECT was fast, and that fetching and re-shaping all that data into memory was an expensive step. get_recordset() in itself never fetches the data into PHP-space, so it takes only 4.8MB and 1.4s:

$users = get_recordset('user');

Next I tried using get_recordset() with FetchNextObj() which looked quite convenient, because it will yield each record in an object, similar to the objects that get_records() returns inside the array. The memory usage stayed the same (4.8M), but this is very slow (~65s):

$users = get_recordset('user');
while($v = $users->FetchNextObj()){
// do something
}

Internally, get_records() is using GetAssoc(), so I looked in there to se faster ways of getting at the data. Apparently, the trick is in reading the $rs->fields array and using MoveNext(). So this loop still takes 4.8MB and walks the 46K user records in 4s:

$users = get_recordset('user');
while(!$users->EOF) {
$user = $users->fields;
// do something
$users->MoveNext();
}

Naturally, as soon as you start doing useful things, this will take longer to exec. The core advantage, however, is that it can give you comparable performance to get_records() but with very low memory usage.

There is an interesting [http://moodle.org/mod/forum/discuss.php?d=45794 discussion about get_recordset() in the General Developer Forum].

[[Category:Developer]]

Development:UK MoodleMoot 06 hackfest

2006-07-10T13:03:31Z

Jvvw: /* 1 Bug fixing */

Monday 24th July, 2006

''Welcommen zum Hackfest'' (OK - I've been watching too much WorldCup on TV).

The first MoodleMoot hackfest is nearly upon us... and we don't have an agenda!

This is an open source agenda for the hackfest. We'll have a day before the Moot to geek out on some code, maybe develop a feature or two, fix some bugs and generally make our favorite learning system a happier place. But I leave it up to you to tell me exactly what we should do. We have four or five rooms with internet connections, a few projectors, and I'll try to get pizza.

Let's start by brainstorming some ideas here for a few days. If someone posts something you're interested in, put your name under it as a vote. The top votes become our central organizing ideas. For example

==1 Bug fixing==

Let's spend a few hours and hunt down as many outstanding bugs in 1.6 as possible. Bounties for most bugs killed, trickiest bug killed, and most unusual bug killed.

''I'm Interested:''
# Jason Cole
# skodak
# martin langhoff (auth & enrolment specifically).
# Martin Dougiamas
# Juliette White (arriving late though!)

(iarenaza) I won't be there, but here are a couple of bugs for Martin L., related to auth: #4648 and #5373. Very easy to fix :-)

==2 What next for the quiz module?==

If any other quizzy people are there, we should have a talk about where we see the quiz module going.

I/the OU have the following priorities:

# Make question type plugins really plug-in-able. At the moment there are some limitations:
#* All the lang strings are still in lang/en_utf8/quiz.php.
#* qtype plugins cannot easily feed CSS and Javascript into the page.
#* pluggable qtypes and pluggable inport/export filters don't play nicely together.
# Write some new question types.
# Make some improvements to existing question types.
# Get RQP working again, so our in-house question engine can talk to Moodle.

''I'm Interested:''
# Tim Hunt

==Performance profiling==

Pick a (memory|database) hog and put it on a diet.

''I'm interested''

# martin langhoff

(iarenaza) Once again, I won't be there, but here's an unfixed bug in 1.6.x and HEAD (was fixed in 1.5.x, but not applied to HEAD at the moment): bug #4591

==Hacking on the OLPC Board==

MartinL will be bringing the OLPC board (if it is booting, and customs allows!) for people to have a play with it. If we have any Mozilla/XUL experts in the house, he will want to explore building a limited cached Moodle UI with it for offline work.

'''Note:''' We will need some spare parts & hardware to get the board going. I will bring a power supply, but a VGA monitor, USB mouse + keyboard, USB ext disk, USB hub, and open wifi (no ethernet on the board) will be needed.

''I'm interested:''

# martin langhoff

==How to save/retrieve a complete section from stock?==
Now the sections become more and more accepted as the tasksets for a week, our teachers wish to have topic oriented stores (courses for the moment) as section stores and want to copy one/more sections form that task store to a clean course..

''(In the end we wish that students can select sections from the store to compose their own courses, until the teacher freezes their choice set and the learning game can begin.)''

''I'm interested:''
# Ger Tielemans (I arrive a little later, so start with the bugs first, please :))
# Jan Kater (same arrival=same message as Ger T.)

==How to reveale files outside a course without using datadir for course 1?==
Can someone explain the right setup and use of the exception array:
- we want to show a student (after login) only his own file from that store
- we want to show a teacher/tutor only the files from the students in his course(s)

''I'm interested:''
# Ger Tielemans
# Jan Kater

==How to repair the last bug in the old bookmark option ?==
We changed William's bookmark in a student only note-taking tool and (thanks Chardelle!) almost repaired the complete bookmark for 1.6. (and it can be accessed from My Page)
Bug: Only when the user tries to sort the heder in the overview, the text of the headers disappear.
Code clean-up: how to remove obsolete code and make the bookmark pages secure?
(Wish for new code: categories are privat, so allow a student to delete a self created category)

''I'm interested:''
Ger Tielemans

==How to insert a HTML-editor in old code block and make it secure ?==
To make the set of student note-taking tools complete, I found old code to have a global private notebook.
(I group this with bookmarks in the calender, so the student has: 1. privat time-related-notes in the calendar, 2. a button for the overview of the privat page-related-notes under the calendar and 3. a global privat notebook for other scribbles..)
On this moment this piece of code has a flat text editor, would be nice to have HTML or even the new (Ajax?) miniWiki?)

With the new "View as student button" check like if isstudent() {..show..} offers teachers and admins empty - only for real student - spots (so an error)

''I'm interested:''
# Ger Tielemans
# Jan Kater

== Improve the way we integrate Rubrics in Moodle, like... ==
http://docs.subjectivemetrics.com/User/cam/rubistar/rs_overview.html

maybe with some flavors of...

http://ipeer.apsc.ubc.ca/ipeer_site/

==Add your suggestion here ...==

Go on, you know you want to.

==See also==
* [http://moodlemoot.org/ http://moodlemoot.org/]

[[Category:Developer]]

Development:CVS for developers

2006-07-03T08:21:05Z

Jvvw:

'''CVS''' is the Concurrent Versioning System, a commonly-used way of managing source code for large software projects. CVS keeps all versions of all files so that nothing is ever lost, and usage by different people is tracked. It also provides ways to merge code if two or more people are working on the same file. All code and all versions are stored on a central server (in the case of Moodle, at Sourceforge). The [http://cvsbook.red-bean.com/cvsbook.html CVS book] holds more information about CVS than you need.

If you just want to download Moodle using CVS to run a site, then you probably don't need this page - just follow the simpler CVS instructions on the [http://download.moodle.org/cvs/ Moodle download] page.

==Joining the project as a developer==

So, you've been offered CVS write access to help us develop and maintain Moodle! [http://sourceforge.net/project/memberlist.php?group_id=30935 Welcome aboard]!

To be able to write changes into [http://moodle.cvs.sourceforge.net/moodle/moodle/ Moodle's CVS archive], you first need to have an account at Sourceforge ([http://sourceforge.net/account/newuser_emailverify.php registration is free and easy]). For the examples on this page, let's assume your username is myusername and your password is mypassword.

Once you have a working Sourceforge account, contact [http://moodle.com/helpdesk Martin Dougiamas] so he can set up your account with write access to particular Moodle directories.

To avoid being prompted for mypassword every time you run a CVS command, follow [http://sourceforge.net/docman/display_doc.php?docid=761&group_id=1 the Sourceforge directions for using authorized keys]. This step is optional, but it can make your CVS experience a lot nicer.

With that done, you should have all the permissions you need, so you just need to set up your machine and download the current sources so you can start working on them. There is no need to read the [https://sourceforge.net/docs/E04 Sourceforge CVS documentation] unless you are interested.

==CVS modules==

Within CVS, the word "modules" refers to separate collections of code. In Moodle we have the following modules within our repository:

* '''moodle''' - the main Moodle source code
* '''contrib''' - user contributions and other assorted code in development
* '''mysql''' - a customised phpMyAdmin to plug into Moodle for database admin
* '''windows-cron''' - a small package that makes cron possible on Windows systems
* '''docs''' - various extra user-contributed documentation

Most people are working on the existing features in the moodle module, but many are also contributing new ideas in the contrib modules. Once code reaches a certain level of maturity in the contrib area, it can be migrated over into the main moodle tree.

==Basic CVS commands==

===CVS on Unix===

Sourceforge CVS uses ssh as a transport layer for security, so you will have to set a CVS_RSH environment variable in your Unix shell. It's best to put these commands in your .bashrc or .cshrc so you don't have to type it all the time:
setenv CVS_RSH ssh (for csh, tcsh etc)
export CVS_RSH=ssh (for sh, bash etc)

Next, you can check out the latest development version of Moodle using this (all one line). NOTE: Don't try to do run this first CVS command over an existing moodle installation: start fresh with a new directory!:
cvs -z3 -d:ext:myusername@moodle.cvs.sourceforge.net:/cvsroot/moodle co moodle

The command is similar for other CVS modules:
cvs -z3 -d:ext:myusername@moodle.cvs.sourceforge.net:/cvsroot/moodle co contrib

Note that you will be prompted for mypassword for each command unless you set up authorized keys.

Now, you should have a new 'moodle' directory. You can rename it and move it around if you like. Go into it:
cd moodle

All the latest Moodle files should be in there. You can now change files in your copy. To compare your files and directories against the main CVS copy on the server use cvs diff, e.g.:
cvs diff -c config-dist.php
cvs diff -c lang

To fetch the latest updates from the server use:
cvs update -dP

To copy your new files back to the server you would do something like:
cd lang/ca
cvs commit

You will be prompted to add some comments (depends on your default text editor) ... add a meaningful comment and close the editor ... the files will be sent to Sourceforge and stored. Done!

To save more time you can put default arguments into a file called .cvsrc in your home directory. For example, mine contains:
diff -c
update -dP

Try 'cvs help' for more details ...

===CVS on Windows===

First, you need to download a completely fresh copy of Moodle using your developer account.

1. Get TortoiseCVS from tortoisecvs.org and install it, then reboot.

2. Find or create a new folder somewhere where you want Moodle to be downloaded to.

3. Right-mouse-click that folder and choose "CVS Checkout" from the menu. You should see a dialog box.

4. Copy this text into the CVSROOT field (using your own username!):

:ext:myusername@moodle.cvs.sourceforge.net:/cvsroot/moodle

5. Under the "Module" field, type "moodle" to get the latest development version of Moodle, "contrib" to get the contributions directory, or "mysql" to get the MySQL Admin module.

6. Press the button: "OK" and everything should be downloaded.

A dialog box should show all the files being downloaded, and after a while you should have a complete copy of Moodle. After this first checkout, you can fetch the latest updated files from the CVS server:

# Right-mouse-click on your Moodle folder (or any file) and select "CVS Update".
# Sit back and watch the logs scroll by. Take note of conflicts that may occur if your local code has changes that conflict with the incoming versions - you will need to edit these files and resolve the conflicts manually.

After modifying files (you will notice their icons change from green to red!), you can commit them back to the CVS server like this:

# Right-mouse-click on your Moodle folder (or any file) and select "CVS Commit...".
# In the dialog box, type a clear description of the changes you are committing.
# Click "OK". Your changes will be sent to the server.

==Working with branches==

This diagram shows how the main moodle module branches into different versions over time.

[[Image:Cvstree.png|CVS tree]]

To see all the current tags and branches that are available, use this command on any old file (such as index.php in the top moodle directory):
cvs status -v index.php

Some tagging guidelines:
* Tag and branch names should always be all upper-case.
* Tags and branches should ALWAYS be applied to the entire module (all of Moodle). Don't tag individual files or directories.
* We don't allow renaming of tags because people may be relying on them, so get them right the first time!

===Trunk development===

The Trunk of CVS is the main development version of Moodle. In CVS it is also known as the HEAD, or default branch.

Moodle developers try to keep this stable as possible, but as it usually contains new code it probably has bugs and small instabilities.

Every now and then we decide the product has enough features to make a release. At this time, the trunk is tagged with a MOODLE_XX_BETA tag (in case we ever want to roll back to that point) and a new branch is formed for the release, called MOODLE_XX_STABLE.

A Beta package is also released at this point - it's for testers who don't use CVS but want to test the latest features and report bugs.

===Stable branches for each release===

As soon as the stable branch MOODLE_XX_STABLE is created, development efforts will fork into two streams for a while. Some people may continue working on new features in the trunk for the next release, but most developers should be concentrating on using the current STABLE branch and fixing bugs that are found in it.

You can switch your local copy of Moodle to the STABLE version using the following command in Unix from the root directory:
cvs update -dP -r MOODLE_XX_STABLE

After that, all the commands described above will apply to that stable version. To return to the trunk version just issue:
cvs update -dPA

On Windows clients you should have a menu from which you can choose the branch.

Once the new STABLE branch really stabilises, a release can be declared. Packages are created for distribution and the branch will be tagged (by Martin) with a tag named: MOODLE_XXX

Periodically, bug fixes in the STABLE branch should be merged into the trunk so that they become available in future versions of Moodle. A floating tag called MOODLE_XX_MERGED will be maintained to keep track of the last merge. The procedure for such a merge is as follows:

1. Get out the very latest trunk version.

cvs update -dPA

2. Merge everything on the branch since the last merge, into your trunk version

cvs update -kk -j MOODLE_XX_MERGED -j MOODLE_XX_STABLE

3. Carefully watch the update logs for conflicts, and fix every file that you see with a conflict

4. Check the merged copy back into CVS trunk version

cvs commit

5. Go back to the branch version

cvs update -dPr MOODLE_XX_STABLE

6. Update the floating merge tag so that this process can be repeated next time

cvs tag -RF MOODLE_XX_MERGED

Finally, the values for $version in all the Moodle version.php files within the stable branch should not be updated at all if possible (except the last digit if necessary). The reason is that someone updating from a very stable version to the next very stable version could miss database upgrades that happened on the trunk.

===Feature branches for large changes===

Occasionally, there may be a very large feature that needs to be checked in so several people can work on it, but it is too unstable to be included in the main development trunk.

In these cases a short-term branch can be created to work on the feature, and then merged back into the main trunk as soon as possible. An example called MOODLE_14_WIDGET branch can be seen in the above diagram.

If you need to do this for your new WIDGET feature, follow these steps:

1. Discuss with other developers to make sure it's necessary!

2. Make a new tag on the trunk (for all of moodle) called MOODLE_XX_WIDGET_PRE

cvs tag -R MOODLE_XX_WIDGET_PRE

3. Create your branch called MOODLE_XX_WIDGET

cvs tag -Rb MOODLE_XX_WIDGET

4. Work in that branch until the feature is reasonably stable. Commit as necessary.

cvs commit

5. When ready, merge the whole branch into the trunk, fix conflicts, commit it to the trunk and then abandon the branch.

cvs update -dPA
cvs update -kk -j MOODLE_XX_WIDGET
cvs commit

Good luck, be careful and have fun!

==Tips and Hints==
* [[Tracking Moodle CVS with git]]
* [http://moodle.org/mod/forum/discuss.php?d=34472 Merging Custom Moodle Code With Stable Releases]
* [[Unmerged files]]: To see if you've forgotten to merge any file.

When you have difficulties accessing CVS this may be due to a problem at Sourceforge. You can check the
* [https://sourceforge.net/docs/A04/ Sourceforge status page]
for any news about outages.

[[Category:Developer]]
[[Category:Developer tools]]

[[es:CVS para desarrolladores]]

Messaging

2006-06-20T13:20:11Z

Jvvw:

Site-wide messaging may be disabled/enabled in the permissions section of Administration >> Configuration >> [[Variables]].

If messaging is enabled, each user's profile page contains a "send messages" button and a "messages" button on the user's own profile page. However, an easier way of accessing messaging is through a [[Messages|messages block]] which may be included on the site home page and/or course home pages.

To find old messages, go to the search tab and search for a common word like 'the' that is likely to be in the messages you want to find.

==See also==
* [[Messaging enhancements]]
* Using Moodle [http://moodle.org/mod/forum/view.php?f=476 Messaging forum]

[[Category: Administrator]]

[[es:Mensajería]]

Development:Modules

2006-05-31T10:34:59Z

Jvvw: Placeholder about support for groups and metacourses

'''Activity modules''' reside in the 'mod' directory. Each module is in a separate subdirectory and consists of the following mandatory elements (plus extra scripts unique to each module):

* ''mod.html'' - a form to set up or update an instance of this module
* ''version.php'' - defines some meta-info and provides upgrading code
* ''icon.gif'' - a 16x16 icon for the module
* ''db/'' - SQL dumps of all the required db tables and data (for each database type)
* ''index.php'' - a page to list all instances in a course
* ''view.php'' - a page to view a particular instance
* ''lib.php'' - any/all functions defined by the module should be in here. If the modulename is called widget, then the required functions include:
:* widget_add_instance() - code to add a new instance of widget
:* widget_update_instance() - code to update an existing instance
:* widget_delete_instance() - code to delete an instance
:* widget_user_outline() - given an instance, return a summary of a user's contribution
:* widget_user_complete() - given an instance, print details of a user's contribution
:* Other functions available but not required are:
:** widget_delete_course() - code to clean up anything that would be leftover after all instances are deleted
:** widget_process_options() - code to pre-process the form data from module settings
:* To avoid possible conflict, any module functions should be named starting with widget_ and any constants you define should start with WIDGET_
* ''config.html'' - (optional) a form to set up or update global settings of this module
* Lastly, each module will have some language files that contain strings for that module.

IMPORTANT: When creating a new module, the new name of the module must not contain numbers or other special characters!

You should also make sure that your activity module provides appropriate support for groups and metacourses.

==See also==

* http://download.moodle.org/download.php/modules/NEWMODULE.zip - new module template for starting module development. Please follow the README instructions inside the zip.
* Using Moodle [http://moodle.org/course/view.php?id=5 Activity modules] forum

[[Category:Developer]]
[[Category:Module]]

[[es:Módulos de actividades (desarrollador)]]

Groups FAQ

2006-05-11T08:41:53Z

Jvvw:

[[Category:Teacher]]
[[Category:Groups]]
[[Category:FAQ]]

= General =
==What is the ‘groups mode’ setting? ==

There are three different groups mode – No groups, Separate Groups, Visible Groups. In ‘Separate groups’ mode, each group can only see their own group – other groups are invisible. In ‘Visible groups’ mode, each group works in their own group, but can also see other groups.

==What is the ‘force’ setting?==

If force is set to yes, then all activities are group activities. This overrides any settings for individual activities. If force is set to no, then activities are only group activities if they have been set to group mode.

==How do I assign a teacher to a group? Can a teacher be in more than one group? ==

You can assign a teacher to a group in exactly the same way that you assign a student to a group. In 1.5, a teacher cannot be in more than one group. This will change in 1.6.

==How do I restrict a teacher to view only information about the groups that they are in?==

For Separate Groups mode, if a teacher has edit rights set to yes, then they can see all groups. If a teacher has edit rights set to no, then they can see only the groups of which they are a member.

==What determines whether students can see a teacher’s profile? ==

A student can see the profile of all teachers that are members of their group or that have edit rights.

==I have two groups that meet on different days. Can I set up activities for different times for the two groups?==

Not currently. You can create a separate course for each class using backup and restore, though you do then have to update both courses.

==Can I use the same groups for more than one course?==

Not currently. There are two possible workarounds for this. The first is to give the students group enrolment keys, so they enrol themselves into the right group for each course. The other alternative is to create a master course with all the students enrolled and in the correct groups, and then to make each of the courses a metacourse (link) based on that master course (although the metacourse documentation claims that metacourses do not preserve groups, this seems to have been used by some people). See the documentation on [[Metacourses]].

==Can a student be a member of more than one group? Is it possible to have students not in any group?==

In 1.5, a student cannot be a member of more than one group. This will change in 1.6. A student does not need to be in a group.

==If I have several groups, can I make a specific activity visible to just one of those groups? ==

Not currently. You can however make a forum post visible to just one group.

==Can I have one set of groups for Activity A and another set of groups for Activity B?==

Not currently.

==Is it possible to view all the groups in a course as a list to print out?==

Not currently.

==When I try to add a student, they are always added to the first group, whichever group I select?==

Make sure that the students name does not include any punctuation. There is also a workaround – give each group a temporary name at the start of the alphabet, put your students in the group and then rename the group.

=Activity modules and groups=

Different activity modules vary as to how they treat groups – some have better support for groups than others! In general if you have questions about how an activity supports groups, you’re advised to post in the forum for the activity module, and not the groups forum.

==What happens if I switch an activity from being in non-groups mode to being in groups mode? ==

This depends on the activity module in question.

For forums, posts made before the forum is put into groups mode are visible to all students after you have put the forum into group mode. However students cannot reply to these posts if they have no group (i.e. blank).

==What happens if I change the groups for an activity in groups mode e.g. if I move a student from one group to another?==

Again this depends on the activity module. You may find that grades or activity logs are lost, so check for the specific activity module first.

==How do I post a message in a forum that only one group can see?==

Before you click ‘Add a new topic’, you need to choose the group from the Separate groups drop-down menu at the top left.

==As a teacher I want to put the same post in each group’s forum with students able to reply to that post. How can I do this?==

You need to post the same message into the forum for each group. There is currently no way to do this in one go if you want students to be able to reply to your post. If you don’t mind students not being able to reply, then you can of course just post the message to all participants