README
------

30-07-2006 15:17:52 Ken Wilson v1.0
06-08-2006 16:19:54 Ken Wilson v1.1

This file is for the max number of enrolments modification to Moodle 1.6. These changes will allow you to set a limit on the number of enrolments in your Moodle courses.

Tested with Moodle 1.6.1 (2006050506) for both Internal and PayPal enorolments. 

If something does not work, send me a message via moodle.org. Similarly, if it works for you, please let me know as well (!)

Inspiration for this work is from the discussion began by John Moon (see http://moodle.org/mod/forum/discuss.php?d=50063) and Joseph Spilatore's Max_Class_Files.zip. 

OVERVIEW
========

This document is divided into three sections:
(a) Quick Install - use this method if you just want to drop the amended files into the directories concerned. 
(b) Patient Install - this takes you through the process of copying each of the required files individually.
(c) Changes Made - this section lists all the code changes made.

All methods require you to manually add a new column in the mdl_course table (assuming you use the mdl_ prefix). Most people use PHPMyAdmin, but I steer clear of it because of security issues. If you have direct access to your server use MySQl Client program instead or the MySQL Browser (download from mysql.net).

As usual, be very careful about changing a production system. Test these changes first on your non-production (test) system by going through the Patient Install and checking the changes to make sure that you are familiar with the way they work before committing them to your users.

(A) QUICK INSTALL
=================

1. IMPORTANT: Make backup copies of these files:
   - moodle\course\edit.html
   - moodle\course\edit.php
   - moodle\course\enrol.php
   - moodle\course\lib.php
   - moodle\lib\moodlelib.php
   - moodle\lang\en_utf8\help\index.html
   - moodle\lang\en_utf8\moodle.php

   The last two files are language files and their location will depend on which language pack you have installed. If you can translate these into your own language, please let me have a copy and I'll make it available in the download.

2. IMPORTANT: Make a backup copy of your moodle database
   - Use PHPMyAdmin or the mysqldump program:

   #mysqldump -u root --password=mypassword -C -Q -e -a moodle > moodle-database.sql

3. Change the moodle database to add a new column called "enrolmax":
   - Use PHPMyAdmin or MySQL Client. Here is an example with MySQL client:

   mysql> use moodle;
   Database changed
   mysql> ALTER TABLE `mdl_course` ADD `enrolmax` INT(10) UNSIGNED DEFAULT '0' NOT NULL AFTER    `notifystudents`;
   Query OK, 3 rows affected (0.07 sec)
   Records: 3  Duplicates: 0  Warnings: 0

   mysql> Quit

   Note: The above example assumes that you use the prefix "mdl_" for your moodle database. 

4. Unzip the zip file attached into the moodle folder and overwrite any files.

5. Edit the settings of the required course and enter the maximum number of students in the "Maximum enrolled students" box. 

Note: be careful on courses which already have students enrolled on them, as you will not be able to  add any more users via the course management menu.


(B) PATIENT INSTALL
===================

1. IMPORTANT: Make backup copies of these files:
   - moodle\course\edit.html
   - moodle\course\edit.php
   - moodle\course\enrol.php
   - moodle\course\lib.php
   - moodle\lib\moodlelib.php
   - moodle\lang\en_utf8\help\index.html
   - moodle\lang\en_utf8\moodle.php

   The last two files are language files and their location will depend on which language pack you have installed.

2. IMPORTANT: Make a backup copy of your moodle database
   - Use PHPMyAdmin or the mysqldump program:

   #mysqldump -u root --password=mypassword -C -Q -e -a moodle > moodle-database.sql

3. Change the moodle database to add a new column called "enrolmax":
   - Use PHPMyAdmin or MySQL Client:

   mysql> use moodle;
   Database changed
   mysql> ALTER TABLE `mdl_course` ADD `enrolmax` INT(10) UNSIGNED DEFAULT '0' NOT NULL AFTER    `notifystudents`;
   Query OK, 3 rows affected (0.07 sec)
   Records: 3  Duplicates: 0  Warnings: 0

   mysql> Quit

   Note: The above example assumes that you use the prefix "mdl_" for your moodle database.

4. Copy the new course files:
   - Copy the edit.html file provided into moodle\course\ and overwrite the original.
   - Copy the edit.php file provided into moodle\course\ and overwrite the original.
   - Copy the enrol.php file provided into moodle\course\ and overwrite the original.
   - Copy the lib.php file provided into moodle\course\ and overwrite the original.

5. Copy the language files (assuming you are using en_utf8):
   - Copy the new file enrolmax.html provided into moodle\lang\en_utf8\help\ and overwrite the original.
   - Copy the index.html file provided into moodle\lang\en_utf8\help\ and overwrite the original.
   - Copy the moodle.php file provided into moodle\lang\en_utf8\ and overwrite the original.

6. Copy the new moodlelib.php file provided into moodle\lib and overwrite the original

7. Edit the settings of the required course and enter the maximum number of students in the "Maximum enrolled students" box. 

Note: be careful on courses which already have students enrolled on them, as you will not be able to  add any more users via the course management menu.


(C) CHANGES MADE
================

Here is a list of changes made to Moodle 1.6.1. Sometimes I refer to line numbers where changes are made. If you're a Windows user, download PSPad (www.pspad.com) and choose View, Line Numbers to switch these on. If you're using VI, type :set number to turn line numbers on.

1. A new column needs to be added to the mdl_course table to store the maximum number of enrolments. 
   The MySQL command is:

ALTER TABLE `mdl_course` ADD `enrolmax` INT(10) UNSIGNED DEFAULT '0' NOT NULL AFTER `notifystudents`;


2. Change moodle\course\edit.html (above numberofweeks section - line 230)

<tr valign="top">
    <td align="right"><?php  print_string("enrolmax") ?>:</td>
    <td><input type="text" name="enrolmax" size=5 value="<?php  p($form->enrolmax) ?>">
    <?php  helpbutton("enrolmax", get_string("enrolmax")) ?>
    <?php  if (isset($err["enrolmax"])) formerr($err["enrolmax"]); ?>
    <?php  echo '&nbsp;&nbsp;&nbsp;&nbsp;';
           print_string('existingstudents');
           echo ': ';
           echo (count_course_students($course)) 
    ?>
    </td>
</tr>


3. Change moodle\course\edit.php

function validate_form($course, &$form, &$err) {

    if (empty($form->enrolenddisabled) && $form->enrolenddate <= $form->enrolstartdate) {
        $err["enroldate"] = get_string("enrolenddaterror");
    }

    $form->enrolmax += 0; //<-- Added for max enrolments


4. Change moodle\course\enrol.php

    require_once("$CFG->dirroot/enrol/enrol.class.php");
    require_once("../lib/datalib.php"); //<-- Added for max enrolments

    $id           = required_param('id', PARAM_INT);
    $loginasguest = optional_param('loginasguest', 0, PARAM_BOOL);

    require_login();

    if (! $course = get_record("course", "id", $id) ) {
        error("That's an invalid course id");
    }

    //Next 6 lines added for max enrolments
    /// Check if course is full
    if ($course->enrolmax > 0 and count_course_students($course) >= $course->enrolmax) {
      $message = get_string('enrolcoursefull', '', $course);
      print_header();
      notice($message, $CFG->wwwroot);
    }


5. Change moodle\course\lib.php to display available places in my courses
   This change is made in the print_course function which starts at line 1235. The code is added after the section which prints the name of the course teachers.
   

    if ($teachers = get_course_teachers($course->id)) {
        echo "<span class=\"teachers\">\n";
        foreach ($teachers as $teacher) {
            if ($teacher->authority > 0) {
                if (!$teacher->role) {
                    $teacher->role = $course->teacher;
                }
                $fullname = fullname($teacher, isteacher($course->id)); // is the USER a teacher of that course
                echo $teacher->role.': <a href="'.$CFG->wwwroot.'/user/view.php?id='.$teacher->id.
                     '&amp;course='.SITEID.'">'.$fullname.'</a><br />';
            }
        }
        echo "</span>\n";
    }
    
    ///Next 9 lines are for maximum enrolment limit
    ///Added for maximum enrolment limit
    $maxenrolment=get_field('course','enrolmax','id',$course->id);
    $availableenrolments = $maxenrolment - count_course_students($course);
    if ($availableenrolments >= 0) {
        echo "<br>";
        print_string(availableenrolments); 
        echo ': '; 
        echo $availableenrolments;
    }
     

6. Change moodle\lib\moodlelib.php so that any enrolment method is handled.

    function enrol_student($userid, $courseid, $timestart=0, $timeend=0, $enrol='manual') {

    global $CFG, $USER;

    if (!$course = get_record('course', 'id', $courseid)) {  // Check course
        return false;
    }
    if (!$user = get_record('user', 'id', $userid)) {        // Check user
        return false;
    }

    /// Check if course is full //<-- Added for max enrolments
    if ($course->enrolmax > 0 and count_course_students($course) >= $course->enrolmax) {
        return false;
    }


7. Contents of moodle\lang\en_utf8\help\enrolmax.html. This is a new help file.

<p align="center"><b>Maximum number of enrolled students</b></p>

<p>This setting specifies the maximum number of students
   that are allowed to be enrolled on the course.</p>

<p>The maximum number will be displayed when a student
   tries to enrol on the course.</p>

<p>When the number of students on this course reaches the
   maximum limit, no one will be able to enrol on the course.</p>


8. Change moodle\lang\en_utf8\help\index.html

  <li><a href="help.php?file=enrolmax.html">Course maximum enrolments</a></li>


9. change moodle\lang\en_utf8\moodle.php

$string['availablestudents'] = 'Available students';
$string['availableenrolments'] = 'Available places';
$string['enrolmax'] = 'Maximum enrolled students';
$string['enrolcoursefull'] = 'Sorry, the number of enrolments on this course has reached the maximum limit set. This course is full.';


10. Change moodle\course\student.html to display maximum students and improve format of displaying existing and potential students

<form name="studentform" id="studentform" method="post" action="student.php">
<input type="hidden" name="previoussearch" value="<?php echo $previoussearch ?>" />
<input type="hidden" name="sesskey" value="<?php echo sesskey() ?>" />
<input type="hidden" name="id" value="<?php echo $course->id ?>" />
  <table align="center" border="0" cellpadding="5" cellspacing="0">
    <tr>
      <td valign="top">
          <?php
              $a->count = count($students);
              $a->items = $strexistingstudents;
              print_string('existingstudents');
              echo (': ');
              echo($a->count);
          ?> <br>
          <?php //Added for max enrolments
              print_string('enrolmax');
              echo (': ');
              echo($course->enrolmax);
              ?>
      </td>
      <td></td>
      <td valign="top">
          <?php
              $a->count = $usercount;
              $a->items = $strpotentialstudents;
              print_string('potentialstudents');
              echo (': ');
              echo ($a->count);
          ?><br>
          <?php //Added for max enrolments
              print_string('availableenrolments');
              echo (': ');
              echo($course->enrolmax - count_course_students($course));
              ?>
      </td>
    </tr>


HISTORY
=======
v1.1 - Added display of number of enrolled students on course\edit.html page
     - Added display of maximum enrolled students on course\student.html page
     - Added display of available places in Available Courses section on index page and when enrolling onto a course
     - Tidy-up of formatting of text on course\student.html

v1.0 - Initial version.


TO DO
=====
This is a list of features I would like to add to this work. If you have any more, please let me know.

  - enforce limit (Y/N) box
  - email teacher when limit is reached
  - threshold of how low the number of spaces should be set at (minimum number of enrolments)
  - waiting list for full courses, with email to student when place becomes available (and a fixed time period for responding before it is made available to someone else)