NAME

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

FUNCTIONS

listCourses($ce)

Lists the courses defined.

listArchivedCourses($ce)

Lists the courses which have been archived (end in .tar.gz).

addCourse(%options)

%options must contain:

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

%options may contain:

templatesFrom => $templatesCourseID,
courseTitle => $courseTitle
courseInstitution => $courseInstitution

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
PRINT_FILE_NAMES_FOR => $pg{specialPGEnvironmentVars}->{PRINT_FILE_NAMES_FOR}

dbLayoutName is required. PRINT_FILE_NAMES_FOR is a reference to an array.

$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(%options)

%options must contain:

courseID => $courseID,
ce => $ce,
newCourseID => $newCourseID,

%options may also contain:

skipDBRename => $skipDBRename,
courseTitle => $courseTitle
courseInstitution => $courseInstitution

Rename the course named $courseID to $newCourseID.

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

The name of the course's directory is changed to $newCourseID.

If the course's database layout is sql_single or sql_moodle, new tables are created in the current database, course data is copied from the old tables to the new tables, and the old tables are deleted.

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

If $skipDBRename is true, no database changes are made. This is useful if a course is being unarchived and no database was found, or for renaming the modelCourse.

Any errors encountered while renaming the course are returned.

retitleCourse

Simply changes the title and institution of the course.

Options must contain:

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

Options may contain newCourseTitle => $courseTitle, newCourseInstitution => $courseInstitution,

deleteCourse(%options)

Options must contain:

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

$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.

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

Any errors encountered while deleting the course are returned.

archiveCourse(%options)

%options must contain:

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

Creates a gzipped tar archive (.tar.gz) of the course $courseID and places it in the archives directory of the admin course or in the location given in the optional archive_path option. Before archiving, the course database is dumped into a subdirectory of the course's DATA directory.

Only files and directories stored directly in the course directory are archived. The contents of linked files is not archived although the symbolic links themselves are saved.

$courseID is the name of the course to archive.

$ce is a WeBWorK::CourseEnvironment object that describes the course's environment. (This is used to access the course database and get path information.)

If an error occurs, an exception is thrown.

unarchiveCourse(%options)

%options must contain:

oldCourseID => $oldCourseID,
archivePath => $archivePath,
ce          => $ce,

%options may also contain:

newCourseID => $newCourseID,

Restores course $oldCourseID from a gzipped tar archive (.tar.gz) located at $archivePath. After unarchiving, the course database is restored from a subdirectory of the course's DATA directory.

If $newCourseID is defined and differs from $oldCourseID, the course is renamed after unarchiving.

$ce is a WeBWorK::CourseEnvironment object that describes the some course's environment. (Usually this would be the admin course.) This is used to access the course database and get path information.

If an error occurs, an exception is thrown.

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

These functions are used to perform database-layout specific operations.

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.

archiveCourseHelper($courseID, $ce, $dbLayoutName, %options): Perform database-layout specific operations for archiving the data in a course.
unarchiveCourseHelper($courseID, $ce, $dbLayoutName, %options): Perform database-layout specific operations for unarchiving the data in a course and placing it in the database.
initNonNativeTables($ce, $db, $dbLayoutName, %options): Perform database-layout specific operations for initializing non-native database tables that are not associated with a particular course

UTILITIES

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

callHelperIfExists($helperName, $dbLayoutName, @args): Call a database-specific helper function, if a database-layout specific helper class exists and contains a function named "${helperName}Helper".
getHelperRef($helperName, $dbLayoutName): 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.