NAME

WeBWorK::Utils::CourseManagement - create, rename, and delete courses.

FUNCTIONS

listCourses($ce)

Lists the courses defined.

addCourse(%options)

%options must contain:

 courseID => $courseID,
 ce => $ce,
 courseOptions => $courseOptions, 
 dbOptions => $dbOptions,
 users => $users

%options may contain:

 templatesFrom => $templatesCourseID,

Create a new course named $courseID.

$ce is a WeBWorK::CourseEnvironment object that describes the new course's environment.

$courseOptions is a reference to a hash containing the following options:

 dbLayoutName         => $dbLayoutName
 globalUserID         => $dbLayouts{gdbm}->{set}->{params}->{globalUserID}
                         $dbLayouts{gdbm}->{problem}->{params}->{globalUserID}
 allowedRecipients    => $mail{allowedRecipients}
 feedbackRecipients   => $mail{feedbackRecipients}
 PRINT_FILE_NAMES_FOR => $pg{specialPGEnvironmentVars}->{PRINT_FILE_NAMES_FOR}

dbLayoutName is required. allowedRecipients, feedbackRecipients, and PRINT_FILE_NAMES_FOR are references to arrays.

$dbOptions is a reference to a hash containing information required to create a database for the course.

 if dbLayout == "sql":
 
        host     => host to connect to
        port     => port to connect to
        username => user to connect as (must have CREATE, DELETE, FILE, INSERT,
                    SELECT, UPDATE privileges, WITH GRANT OPTION.)
        password => password to supply
        database => the name of the database to create
        wwhost   => the host from which the webwork database users will be allowed
                    to connect. (if host is set to localhost, this should be set to
                    localhost too.)

These values must match the information given in the selected dbLayout. If $dbOptions is undefined, addCourse() assumes that the database has already been created, and skips that step in the course creation process.

$users is a list of arrayrefs, each containing a User, Password, and PermissionLevel record for a single user:

 $users = [ $User, $Password, $PermissionLevel ]

These users are added to the course.

$templatesCourseID indicates the ID of a course from which the contents of the templates directory will be copied to the new course.

renameCourse($webworkRoot, $oldCourseID, $newCourseID)

Rename the course named $oldCourseID to $newCourseID.

The name course directory is set to $newCourseID.

If the course's database layout is sql, a new database is created, course data is exported from the old database and imported into the new database, and the old database is deleted.

If the course's database layout is gdbm, the DBM files are simply renamed on disk.

If the course's database layout is something else, no database changes are made.

Any errors encountered while renaming the course are returned.

deleteCourse(%options)

Options must contain:

 courseID => $courseID,
 ce => $ce,
 dbOptions => $dbOptions,

$ce is a WeBWorK::CourseEnvironment object that describes the course's environment. It is your responsability to pass a course environment object that describes the course to be deleted. Do not pass the course environment object associated with the request, unless you are deleting the course you're currently using.

$dbOptions is a reference to a hash containing information required to create a database for the course.

 if dbLayout == "sql":
 
        host     => host to connect to
        port     => port to connect to
        username => user to connect as (must have CREATE, DELETE, FILE, INSERT,
                    SELECT, UPDATE privileges, WITH GRANT OPTION.)
        password => password to supply
        database => the name of the database to create

Deletes the course named $courseID. The course directory is removed.

If the course's database layout is sql, the course database is dropped.

If the course's database layout is something else, no databases are removed.

Any errors encountered while deleting the course are returned.

dbLayoutSQLSources($dbLayout)

Retrun a hash of database sources for the sql and sql_single database layouts. Each element of the hash takes this form:

 dbi_source => {
     tables => [ 'table1', 'table2', ... ],
     username => 'username',
     password => 'password',
 }

In the common case, there will only be one source returned.

DATABASE-LAYOUT SPECIFIC HELPER FUNCTIONS

The addCourseHelper(), renameCourseHelper(), and deleteCourseHelper() functions are used by addCourse(), renameCourse(), and deleteCourse() to perform database-layout specific operations, such as creating a database. They are called after the course directory structure has been created, but before the database is initialized.

The implementations in this class do nothing, but if an appropriate function exists in a class with the name WeBWorK::Utils::CourseManagement::$dbLayoutName, it will be used instead.

addCourseHelper($courseID, $ce, $dbLayoutName, %options): Perform database-layout specific operations for adding a course.
renameCourseHelper($oldCourseID, $newCourseID, $ce, $dbLayoutName, %options): Perform database-layout specific operations for renaming a course.
deleteCourseHelper($courseID, $ce, $dbLayoutName, %options): Perform database-layout specific operations for renaming a course.

UTILITIES

These functions are used by this class's public functions and should not be called directly.

callHelperIfExists($helperName, $args): Call a database-specific helper function, if a database-layout specific helper class exists and contains a function named ``${helperName}Helper''.
protectQString($string): Protects the contents of a single-quoted Perl string.
writeCourseConf($fh, $ce, %options): Writes a course.conf file to $fh, a file handle, using defaults from the course environment object $ce and overrides from %options. %options can contain any of the pairs accepted in %courseOptions by addCourse(), above.