Moodle APIs 3.9
Moodle 3.9.13+ (Build: 20220325)
Public Member Functions | Static Public Member Functions | Public Attributes | Protected Member Functions | Protected Attributes | List of all members
workshop Class Reference

Full-featured workshop API. More...

Public Member Functions

 __construct (stdclass $dbrecord, $cm, $course, stdclass $context=null)
 Initializes the workshop API instance using the data from DB. More...
 
 add_allocation (stdclass $submission, $reviewerid, $weight=1, $bulk=false)
 Allocate a submission to a user for review. More...
 
 aggregate_grading_grades ($restrict=null)
 Calculates grades for assessment for the given participant(s) More...
 
 aggregate_submission_grades ($restrict=null)
 Calculates grades for submission for the given participant(s) and updates it in the database. More...
 
 aggregate_url ()
 
 allocation_url ($method=null)
 
 allocator_instance ($method)
 Returns instance of submissions allocator. More...
 
 assess_url ($assessmentid)
 
 assessing_allowed ($userid)
 Is the given reviewer allowed to create/edit their assessments? More...
 
 assessing_examples_allowed ()
 Are reviewers allowed to create/edit their assessments of the example submissions? More...
 
 assessments_available ()
 Are the peer-reviews available to the authors? More...
 
 check_edit_assessment ($assessment, $submission)
 Helper method for validating if the current user can edit the given assessment. More...
 
 check_examples_assessed_before_assessment ($userid)
 Check that all required examples have been assessed by the given user. More...
 
 check_examples_assessed_before_submission ($userid)
 Check whether the given user has assessed all his required examples before submission. More...
 
 check_group_membership ($otheruserid)
 Check if the current user can access the other user's group. More...
 
 check_view_assessment ($assessment, $submission)
 Helper method for validating if the current user can view the given assessment. More...
 
 clear_assessments ()
 Sets the given grades and received grading grades to null. More...
 
 clear_grading_grades ($restrict=null)
 Sets the aggregated grades for assessment to null. More...
 
 clear_submission_grades ($restrict=null)
 Sets the grades for submission to null. More...
 
 compare_url ($sid, array $aids)
 
 count_participants ($musthavesubmission=false, $groupid=0)
 Returns the total number of records that would be returned by self::get_participants(). More...
 
 count_potential_authors ($musthavesubmission=true, $groupid=0)
 Returns the total number of users that would be fetched by self::get_potential_authors(). More...
 
 count_potential_reviewers ($musthavesubmission=false, $groupid=0)
 Returns the total number of users that would be fetched by self::get_potential_reviewers(). More...
 
 count_submissions ($authorid='all', $groupid=0)
 Returns the total number of records that would be returned by self::get_submissions(). More...
 
 creating_submission_allowed ($userid)
 Is the given user allowed to create their submission? More...
 
 delete_assessment ($id)
 Delete assessment record or records. More...
 
 delete_submission (stdclass $submission)
 Removes the submission and all relevant data. More...
 
 edit_assessment ($assessment, $submission, $data, $strategy)
 Adds information to an allocated assessment (function used the first time a review is done or when updating an existing one). More...
 
 edit_submission ($submission)
 Adds or updates a submission. More...
 
 editform_url ()
 
 evaluate_assessment ($assessment, $data, $cansetassessmentweight, $canoverridegrades)
 Evaluates an assessment. More...
 
 evaluate_submission ($submission, $data, $canpublish, $canoverride)
 Evaluates a submission. More...
 
 exassess_url ($assessmentid)
 
 excompare_url ($sid, $aid)
 
 exsubmission_url ($id)
 
 get_all_assessments ()
 Returns the list of all assessments in the workshop with some data added. More...
 
 get_allocations ()
 Returns the list of all allocations (i.e. More...
 
 get_assessment_by_id ($id)
 Get the complete information about the given assessment. More...
 
 get_assessment_of_submission_by_user ($submissionid, $reviewerid)
 Get the complete information about the user's assessment of the given submission. More...
 
 get_assessments_by_reviewer ($reviewerid)
 Get the complete information about all assessments allocated to the given reviewer. More...
 
 get_assessments_of_submission ($submissionid)
 Get the complete information about all assessments of the given submission. More...
 
 get_example_by_id ($id)
 Returns full record of the given example submission. More...
 
 get_examples_for_manager ()
 Returns the list of example submissions in this workshop with reference assessments attached. More...
 
 get_examples_for_reviewer ($reviewerid)
 Returns the list of all example submissions in this workshop with the information of assessments done by the given user. More...
 
 get_feedbackauthor_form ($actionurl, stdclass $submission, $options=array())
 Returns the mform the teachers use to put a feedback for the author on their submission. More...
 
 get_feedbackreviewer_form ($actionurl, stdclass $assessment, $options=array())
 Returns the mform the teachers use to put a feedback for the reviewer. More...
 
 get_gradebook_grades ($userid)
 Returns the information about the user's grades as they are stored in the gradebook. More...
 
 get_grouped ($users)
 Groups the given users by the group membership. More...
 
 get_participants ($musthavesubmission=false, $groupid=0, $limitfrom=0, $limitnum=0)
 Fetches all enrolled users that are authors or reviewers (or both) in the current workshop. More...
 
 get_pending_assessments_by_reviewer ($reviewerid, $exclude=null)
 Get allocated assessments not graded yet by the given reviewer. More...
 
 get_potential_authors ($musthavesubmission=true, $groupid=0, $limitfrom=0, $limitnum=0)
 Fetches all enrolled users with the capability mod/workshop:submit in the current workshop. More...
 
 get_potential_reviewers ($musthavesubmission=false, $groupid=0, $limitfrom=0, $limitnum=0)
 Fetches all enrolled users with the capability mod/workshop:peerassess in the current workshop. More...
 
 get_published_submissions ($orderby='finalgrade DESC')
 Returns published submissions with their authors data. More...
 
 get_submission_by_author ($authorid)
 Returns a submission submitted by the given author. More...
 
 get_submission_by_id ($id)
 Returns a submission record with the author's data. More...
 
 get_submissions ($authorid='all', $groupid=0, $limitfrom=0, $limitnum=0)
 Returns submissions from this workshop. More...
 
 get_visible_submissions ($authorid=0, $groupid=0, $limitfrom=0, $limitnum=0)
 Returns submissions from this workshop that are viewable by the current user (except example submissions). More...
 
 grading_evaluation_instance ()
 Returns instance of grading evaluation class. More...
 
 grading_strategy_instance ()
 Returns instance of grading strategy class. More...
 
 is_participant ($userid=null)
 Checks if the given user is an actively enrolled participant in the workshop. More...
 
 log ($action, moodle_url $url=null, $info=null, $return=false)
 Workshop wrapper around {. More...
 
 modifying_submission_allowed ($userid)
 Is the given user allowed to modify their existing submission? More...
 
 overall_feedback_attachment_options ()
 Return the filemanager options for the overall feedback for the author. More...
 
 overall_feedback_content_options ()
 Return the editor options for the overall feedback for the author. More...
 
 prepare_assessment (stdClass $record, $form, array $options=array())
 Prepares renderable assessment component. More...
 
 prepare_example_assessment (stdClass $record, $form=null, array $options=array())
 Prepares renderable example submission's assessment component. More...
 
 prepare_example_reference_assessment (stdClass $record, $form=null, array $options=array())
 Prepares renderable example submission's reference assessment component. More...
 
 prepare_example_submission (stdClass $record)
 Prepares renderable example submission component. More...
 
 prepare_example_summary (stdClass $example)
 Prepares renderable example submission summary component. More...
 
 prepare_grading_report_data ($userid, $groupid, $page, $perpage, $sortby, $sorthow)
 Prepares data object with all workshop grades to be rendered. More...
 
 prepare_submission (stdClass $record, $showauthor=false)
 Prepares renderable submission component. More...
 
 prepare_submission_summary (stdClass $record, $showauthor=false)
 Prepares renderable submission summary component. More...
 
 previewform_url ()
 
 raw_grade_value ($value, $max)
 Calculates the raw (percentual) value from a real grade. More...
 
 real_grade ($value)
 Calculates the real value of grade for submission. More...
 
 real_grade_value ($value, $max)
 Calculates the real value of a grade. More...
 
 real_grading_grade ($value)
 Calculates the real value of grade for assessment. More...
 
 reset_userdata (stdClass $data)
 Performs the reset of this workshop instance. More...
 
 set_grading_evaluation_method ($method)
 Sets the current evaluation method to the given plugin. More...
 
 set_module_viewed ()
 Trigger module viewed event and set the module viewed for completion. More...
 
 set_peer_grade ($assessmentid, $grade)
 Saves a raw grade for submission as calculated from the assessment form fields. More...
 
 set_submission_viewed ($submission)
 Trigger submission viewed event. More...
 
 submission_attachment_options ()
 Return the filemanager options for the submission attachments field. More...
 
 submission_content_options ()
 Return the editor options for the submission content field. More...
 
 submission_url ($id=null)
 
 switch_phase ($newphase)
 Switch to a new workshop phase. More...
 
 switchphase_url ($phasecode)
 
 toolbox_url ($tool)
 
 updatemod_url ()
 
 validate_submission_data ($data)
 Validates the submission form or WS data. More...
 
 view_url ()
 

Static Public Member Functions

static available_assessment_weights_list ()
 Return an array of possible values of assessment weight. More...
 
static available_dimension_weights_list ()
 Return an array of possible values of assessment dimension weight. More...
 
static available_evaluators_list ()
 Returns the list of available grading evaluation methods. More...
 
static available_example_modes_list ()
 Returns the localized list of supported examples modes. More...
 
static available_maxgrades_list ()
 Returns an array of numeric values that can be used as maximum grades. More...
 
static available_strategies_list ()
 Returns the list of available grading strategy methods. More...
 
static clean_file_extensions ($extensions)
 Cleans the user provided list of file extensions. More...
 
static gcd ($a, $b)
 Helper function returning the greatest common divisor. More...
 
static installed_allocators ()
 Return list of available allocation methods. More...
 
static instruction_editors_options (stdclass $context)
 Returns an array of options for the editors that are used for submitting and assessing instructions. More...
 
static invalid_file_extensions ($extensions, $whitelist)
 Check given file types and return invalid/unknown ones. More...
 
static is_allowed_file_type ($filename, $whitelist)
 Is the file have allowed to be uploaded to the workshop? More...
 
static lcm ($a, $b)
 Helper function returning the least common multiple. More...
 
static normalize_file_extensions ($extensions)
 Converts the argument into an array (list) of file extensions. More...
 
static percent_to_value ($percent, $total)
 Given the percent and the total, returns the number. More...
 
static timestamp_formats ($timestamp)
 Returns an object suitable for strings containing dates/times. More...
 

Public Attributes

int $assessmentend
 if greater than 0 then the peer assessment is not allowed after this timestamp
 
int $assessmentstart
 if greater than 0 then the peer assessment is not allowed before this timestamp
 
cm_info $cm
 course module record
 
string $conclusion
 conclusion text to be displayed at the end of the activity
 
int $conclusionformat
 format of the conclusion text
 
stdclass $context
 context object
 
stdclass $course
 course record
 
stdclass $dbrecord
 workshop record from database
 
string $evaluation
 the name of the evaluation plugin to use for grading grades calculation
 
int $examplesmode
 mode of example submissions support, for example workshop::EXAMPLES_VOLUNTARY
 
float $grade
 number (10, 5) unsigned, the maximum grade for submission
 
int $gradedecimals
 number of digits that should be shown after the decimal point when displaying grades
 
float $gradinggrade
 number (10, 5) unsigned, the maximum grade for assessment
 
int $id
 workshop instance identifier
 
string $instructauthors
 instructions for the submission phase
 
int $instructauthorsformat
 format of the $instructauthors
 
string $instructreviewers
 instructions for the assessment phase
 
int $instructreviewersformat
 format of the $instructreviewers
 
string $intro
 introduction or description of the activity
 
int $introformat
 format of the $intro
 
bool $latesubmissions
 allow submitting the work after the deadline
 
int $maxbytes
 maximum size of the one attached file in bytes
 
string $name
 workshop activity name
 
int $nattachments
 number of allowed submission attachments and the files embedded into submission
 
int $overallfeedbackfiles
 maximum number of overall feedback attachments
 
string $overallfeedbackfiletypes = null
 list of allowed file types that can be attached to the overall feedback
 
int $overallfeedbackmaxbytes
 maximum size of one file attached to the overall feedback
 
int $overallfeedbackmode
 the mode of the overall feedback
 
int $phase
 current phase of workshop, for example workshop::PHASE_SETUP
 
bool $phaseswitchassessment
 automatically switch to the assessment phase after the submissions deadline
 
string $strategy
 type of the current grading strategy used in this workshop, for example 'accumulative'
 
int $submissionend
 if greater than 0 then the submission is not allowed after this timestamp
 
string $submissionfiletypes = null
 list of allowed file types that are allowed to be embedded into submission
 
int $submissionstart
 if greater than 0 then the submission is not allowed before this timestamp
 
int $submissiontypefile
 Should the submission form show the file attachment field?
 
int $submissiontypetext
 Should the submission form show the text field?
 
int $timemodified
 timestamp of when the module was modified
 
bool $useexamples
 optional feature: students practise evaluating on example submissions from teacher
 
bool $usepeerassessment
 optional feature: students perform peer assessment of others' work (deprecated, consider always enabled)
 
bool $useselfassessment
 optional feature: students perform self assessment of their own work
 
const ALLOCATION_EXISTS = -9999
 error status of the self::add_allocation()
 
const EXAMPLES_BEFORE_ASSESSMENT = 2
 
const EXAMPLES_BEFORE_SUBMISSION = 1
 
const EXAMPLES_VOLUNTARY = 0
 the internal code of the examples modes as are stored in the database
 
const PHASE_ASSESSMENT = 30
 
const PHASE_CLOSED = 50
 
const PHASE_EVALUATION = 40
 
const PHASE_SETUP = 10
 the internal code of the workshop phases as are stored in the database
 
const PHASE_SUBMISSION = 20
 

Protected Member Functions

 aggregate_grading_grades_process (array $assessments, $timegraded=null)
 Given an array of all assessments done by a single reviewer, calculates the final grading grade. More...
 
 aggregate_submission_grades_process (array $assessments)
 Given an array of all assessments of a single submission, calculates the final grade for this submission. More...
 
 available_phases_list ()
 
 get_participants_sql ($musthavesubmission=false, $groupid=0)
 Returns SQL statement that can be used to fetch all actively enrolled participants in the workshop. More...
 
 get_users_with_capability_sql ($capability, $musthavesubmission, $groupid)
 Returns SQL to fetch all enrolled users with the given capability in the current workshop. More...
 
 log_convert_url (moodle_url $fullurl)
 Converts absolute URL to relative URL needed by {. More...
 
 reset_phase ()
 Hard set the workshop phase to the setup one.
 
 reset_userdata_assessments (stdClass $data)
 Removes all user data related to assessments (including allocations). More...
 
 reset_userdata_submissions (stdClass $data)
 Removes all user data related to participants' submissions. More...
 

Protected Attributes

workshop_evaluation $evaluationinstance = null
 grading evaluation instance Do not use directly, get the instance using workshop::grading_evaluation_instance()
 
workshop_strategy $strategyinstance = null
 grading strategy instance Do not use directly, get the instance using workshop::grading_strategy_instance()
 

Detailed Description

Full-featured workshop API.

This wraps the workshop database record with a set of methods that are called from the module itself. The class should be initialized right after you get $workshop, $cm and $course records at the begining of the script.

Constructor & Destructor Documentation

◆ __construct()

workshop::__construct ( stdclass  $dbrecord,
  $cm,
  $course,
stdclass  $context = null 
)

Initializes the workshop API instance using the data from DB.

Makes deep copy of all passed records properties.

For unit testing only, $cm and $course may be set to null. This is so that you can test without having any real database objects if you like. Not all functions will work in this situation.

Parameters
stdClass$dbrecordWorkshop instance data from {workshop} table
stdClass | cm_info$cmCourse module record
stdClass$courseCourse record from {course} table
stdClass$contextThe context of the workshop instance

Member Function Documentation

◆ add_allocation()

workshop::add_allocation ( stdclass  $submission,
  $reviewerid,
  $weight = 1,
  $bulk = false 
)

Allocate a submission to a user for review.

Parameters
stdClass$submissionSubmission object with at least id property
int$revieweridUser ID
int$weightof the new assessment, from 0 to 16
bool$bulkrepeated inserts into DB expected
Return values
intID of the new assessment or an error code self::ALLOCATION_EXISTS if the allocation already exists

◆ aggregate_grading_grades()

workshop::aggregate_grading_grades (   $restrict = null)

Calculates grades for assessment for the given participant(s)

Grade for assessment is calculated as a simple mean of all grading grades calculated by the grading evaluator. The assessment weight is not taken into account here.

Parameters
null | int | array$restrictIf null, update all reviewers, otherwise update just grades for the given reviewer(s)
Return values
void

◆ aggregate_grading_grades_process()

workshop::aggregate_grading_grades_process ( array  $assessments,
  $timegraded = null 
)
protected

Given an array of all assessments done by a single reviewer, calculates the final grading grade.

This calculates the simple mean of the passed grading grades. If, however, the grading grade was overridden by a teacher, the gradinggradeover value is returned and the rest of grades are ignored.

Parameters
array$assessmentsof stdclass(->reviewerid ->gradinggrade ->gradinggradeover ->aggregationid ->aggregatedgrade)
null | int$timegradedexplicit timestamp of the aggregation, defaults to the current time
Return values
void

◆ aggregate_submission_grades()

workshop::aggregate_submission_grades (   $restrict = null)

Calculates grades for submission for the given participant(s) and updates it in the database.

Parameters
null | int | array$restrictIf null, update all authors, otherwise update just grades for the given author(s)
Return values
void

◆ aggregate_submission_grades_process()

workshop::aggregate_submission_grades_process ( array  $assessments)
protected

Given an array of all assessments of a single submission, calculates the final grade for this submission.

This calculates the weighted mean of the passed assessment grades. If, however, the submission grade was overridden by a teacher, the gradeover value is returned and the rest of grades are ignored.

Parameters
array$assessmentsof stdclass(->submissionid ->submissiongrade ->gradeover ->weight ->grade)
Return values
void

◆ aggregate_url()

workshop::aggregate_url ( )
Return values
moodle_urlto the aggregation page

◆ allocation_url()

workshop::allocation_url (   $method = null)
Parameters
string$methodallocation method
Return values
moodle_urlto the allocation page

◆ allocator_instance()

workshop::allocator_instance (   $method)

Returns instance of submissions allocator.

Parameters
string$methodThe name of the allocation method, must be PARAM_ALPHA
Return values
stdclassInstance of submissions allocator

◆ assess_url()

workshop::assess_url (   $assessmentid)
Parameters
int$assessmentidThe ID of assessment record
Return values
moodle_urlof the assessment page

◆ assessing_allowed()

workshop::assessing_allowed (   $userid)

Is the given reviewer allowed to create/edit their assessments?

Parameters
int$userid
Return values
bool

◆ assessing_examples_allowed()

workshop::assessing_examples_allowed ( )

Are reviewers allowed to create/edit their assessments of the example submissions?

Returns null if example submissions are not enabled in this workshop. Otherwise returns true or false. Note this does not check other conditions like the number of already assessed examples, examples mode etc.

Return values
null|bool

◆ assessments_available()

workshop::assessments_available ( )

Are the peer-reviews available to the authors?

Return values
bool

◆ available_assessment_weights_list()

static workshop::available_assessment_weights_list ( )
static

Return an array of possible values of assessment weight.

Note there is no real reason why the maximum value here is 16. It used to be 10 in workshop 1.x and I just decided to use the same number as in the maximum weight of a single assessment dimension. The value looks reasonable, though. Teachers who would want to assign themselves higher weight probably do not want peer assessment really...

Return values
arrayof integers 0, 1, 2, ..., 16

◆ available_dimension_weights_list()

static workshop::available_dimension_weights_list ( )
static

Return an array of possible values of assessment dimension weight.

Return values
arrayof integers 0, 1, 2, ..., 16

◆ available_evaluators_list()

static workshop::available_evaluators_list ( )
static

Returns the list of available grading evaluation methods.

Return values
arrayof (string)name => (string)localized title

◆ available_example_modes_list()

static workshop::available_example_modes_list ( )
static

Returns the localized list of supported examples modes.

Return values
array

◆ available_maxgrades_list()

static workshop::available_maxgrades_list ( )
static

Returns an array of numeric values that can be used as maximum grades.

Return values
arrayArray of integers

◆ available_phases_list()

workshop::available_phases_list ( )
protected
Return values
arrayof available workshop phases

◆ available_strategies_list()

static workshop::available_strategies_list ( )
static

Returns the list of available grading strategy methods.

Return values
array['string' => 'string']

◆ check_edit_assessment()

workshop::check_edit_assessment (   $assessment,
  $submission 
)

Helper method for validating if the current user can edit the given assessment.

Parameters
stdClass$assessmentassessment object
stdClass$submissionsubmission object
Return values
void
Exceptions
moodle_exception
Since
Moodle 3.4

◆ check_examples_assessed_before_assessment()

workshop::check_examples_assessed_before_assessment (   $userid)

Check that all required examples have been assessed by the given user.

Parameters
stdClass$useridthe user (reviewer) to check
Return values
mixedbool|state false and notice code if there are examples missing assessment, true otherwise.
Since
Moodle 3.4

◆ check_examples_assessed_before_submission()

workshop::check_examples_assessed_before_submission (   $userid)

Check whether the given user has assessed all his required examples before submission.

Parameters
int$useridthe user to check
Return values
boolfalse if there are examples missing assessment, true otherwise.
Since
Moodle 3.4

◆ check_group_membership()

workshop::check_group_membership (   $otheruserid)

Check if the current user can access the other user's group.

This is typically used for teacher roles that have permissions like 'view all submissions'. Even with such a permission granted, we have to check the workshop activity group mode.

If the workshop is not in a group mode, or if it is in the visible group mode, this method returns true. This is consistent with how the groups_get_activity_allowed_groups() behaves.

If the workshop is in a separate group mode, the current user has to have the 'access all groups' permission, or share at least one accessible group with the other user.

Parameters
int$otheruseridThe ID of the other user, e.g. the author of a submission.
Return values
boolFalse if the current user cannot access the other user's group.

◆ check_view_assessment()

workshop::check_view_assessment (   $assessment,
  $submission 
)

Helper method for validating if the current user can view the given assessment.

Parameters
stdClass$assessmentassessment object
stdClass$submissionsubmission object
Return values
void
Exceptions
moodle_exception
Since
Moodle 3.4

◆ clean_file_extensions()

static workshop::clean_file_extensions (   $extensions)
static

Cleans the user provided list of file extensions.

Deprecated:
since Moodle 3.4 MDL-56486 - please use the core_form::filetypes_util
Parameters
string$extensions
Return values
string

◆ clear_assessments()

workshop::clear_assessments ( )

Sets the given grades and received grading grades to null.

This does not clear the information about how the peers filled the assessment forms, but clears the calculated grades in workshop_assessments. Therefore reviewers have to re-assess the allocated submissions.

Return values
void

◆ clear_grading_grades()

workshop::clear_grading_grades (   $restrict = null)

Sets the aggregated grades for assessment to null.

Parameters
null | int | array$restrictIf null, update all reviewers, otherwise update just grades for the given reviewer(s)
Return values
void

◆ clear_submission_grades()

workshop::clear_submission_grades (   $restrict = null)

Sets the grades for submission to null.

Parameters
null | int | array$restrictIf null, update all authors, otherwise update just grades for the given author(s)
Return values
void

◆ compare_url()

workshop::compare_url (   $sid,
array  $aids 
)
Parameters
int$sidsubmission id
array$aidof int assessment ids
Return values
moodle_urlof the page to compare assessments of the given submission

◆ count_participants()

workshop::count_participants (   $musthavesubmission = false,
  $groupid = 0 
)

Returns the total number of records that would be returned by self::get_participants().

Parameters
bool$musthavesubmissionif true, return only users who have already submitted
int$groupid0 means ignore groups, any other value limits the result by group id
Return values
int

◆ count_potential_authors()

workshop::count_potential_authors (   $musthavesubmission = true,
  $groupid = 0 
)

Returns the total number of users that would be fetched by self::get_potential_authors().

Parameters
bool$musthavesubmissionif true, count only users who have already submitted
int$groupid0 means ignore groups, any other value limits the result by group id
Return values
int

◆ count_potential_reviewers()

workshop::count_potential_reviewers (   $musthavesubmission = false,
  $groupid = 0 
)

Returns the total number of users that would be fetched by self::get_potential_reviewers().

Parameters
bool$musthavesubmissionif true, count only users who have already submitted
int$groupid0 means ignore groups, any other value limits the result by group id
Return values
int

◆ count_submissions()

workshop::count_submissions (   $authorid = 'all',
  $groupid = 0 
)

Returns the total number of records that would be returned by self::get_submissions().

Parameters
mixed$authoridint|array|'all' If set to [array of] integer, return submission[s] of the given user[s] only
int$groupidIf non-zero, return only submissions by authors in the specified group
Return values
intnumber of records

◆ creating_submission_allowed()

workshop::creating_submission_allowed (   $userid)

Is the given user allowed to create their submission?

Parameters
int$userid
Return values
bool

◆ delete_assessment()

workshop::delete_assessment (   $id)

Delete assessment record or records.

Removes associated records from the workshop_grades table, too.

Parameters
int | array$idassessment id or array of assessments ids
Todo:
Give grading strategy plugins a chance to clean up their data, too.
Return values
booltrue

◆ delete_submission()

workshop::delete_submission ( stdclass  $submission)

Removes the submission and all relevant data.

Parameters
stdClass$submissionrecord to delete
Return values
void

◆ edit_assessment()

workshop::edit_assessment (   $assessment,
  $submission,
  $data,
  $strategy 
)

Adds information to an allocated assessment (function used the first time a review is done or when updating an existing one).

Parameters
stdClass$assessmentthe assessment
stdClass$submissionthe submission
stdClass$datathe assessment data to be added or Updated
stdClass$strategythe strategy instance
Return values
float|nullRaw percentual grade (0.00000 to 100.00000) for submission
Since
Moodle 3.4

◆ edit_submission()

workshop::edit_submission (   $submission)

Adds or updates a submission.

Parameters
stdClass$submissionThe submissin data (via form or via WS).
Return values
thenew or updated submission id.
Since
Moodle 3.4

◆ editform_url()

workshop::editform_url ( )
Return values
moodle_urlof the page for editing this workshop's grading form

◆ evaluate_assessment()

workshop::evaluate_assessment (   $assessment,
  $data,
  $cansetassessmentweight,
  $canoverridegrades 
)

Evaluates an assessment.

Parameters
stdClass$assessmentthe assessment
stdClass$datathe assessment data to be updated
bool$cansetassessmentweightwhether the user can change the assessment weight
bool$canoverridegradeswhether the user can override the assessment grades
Return values
void
Since
Moodle 3.4

◆ evaluate_submission()

workshop::evaluate_submission (   $submission,
  $data,
  $canpublish,
  $canoverride 
)

Evaluates a submission.

Parameters
stdClass$submissionthe submission
stdClass$datathe submission data to be updated
bool$canpublishwhether the user can publish the submission
bool$canoverridewhether the user can override the submission grade
Return values
void
Since
Moodle 3.4

◆ exassess_url()

workshop::exassess_url (   $assessmentid)
Parameters
int$assessmentidThe ID of assessment record
Return values
moodle_urlof the example assessment page

◆ excompare_url()

workshop::excompare_url (   $sid,
  $aid 
)
Parameters
int$sidsubmission id
int$aidassessment id
Return values
moodle_urlof the page to compare the reference assessments of the given example submission

◆ exsubmission_url()

workshop::exsubmission_url (   $id)
Parameters
int$idexample submission id
Return values
moodle_urlof the page to view an example submission

◆ gcd()

static workshop::gcd (   $a,
  $b 
)
static

Helper function returning the greatest common divisor.

Parameters
int$a
int$b
Return values
int

◆ get_all_assessments()

workshop::get_all_assessments ( )

Returns the list of all assessments in the workshop with some data added.

Fetches data from {workshop_assessments} and adds some useful information from other tables. The returned object does not contain textual fields (i.e. comments) to prevent memory lack issues.

Return values
array[assessmentid] => assessment stdclass

◆ get_allocations()

workshop::get_allocations ( )

Returns the list of all allocations (i.e.

assigned assessments) in the workshop

Assessments of example submissions are ignored

Return values
array

◆ get_assessment_by_id()

workshop::get_assessment_by_id (   $id)

Get the complete information about the given assessment.

Parameters
int$idAssessment ID
Return values
stdclass

◆ get_assessment_of_submission_by_user()

workshop::get_assessment_of_submission_by_user (   $submissionid,
  $reviewerid 
)

Get the complete information about the user's assessment of the given submission.

Parameters
int$sidsubmission ID
int$uiduser ID of the reviewer
Return values
false|stdclassfalse if not found, stdclass otherwise

◆ get_assessments_by_reviewer()

workshop::get_assessments_by_reviewer (   $reviewerid)

Get the complete information about all assessments allocated to the given reviewer.

Parameters
int$reviewerid
Return values
array

◆ get_assessments_of_submission()

workshop::get_assessments_of_submission (   $submissionid)

Get the complete information about all assessments of the given submission.

Parameters
int$submissionid
Return values
array

◆ get_example_by_id()

workshop::get_example_by_id (   $id)

Returns full record of the given example submission.

Parameters
int$idexample submission od
Return values
object

◆ get_examples_for_manager()

workshop::get_examples_for_manager ( )

Returns the list of example submissions in this workshop with reference assessments attached.

Return values
arrayof objects or an empty array
See also
workshop::prepare_example_summary()

◆ get_examples_for_reviewer()

workshop::get_examples_for_reviewer (   $reviewerid)

Returns the list of all example submissions in this workshop with the information of assessments done by the given user.

Parameters
int$revieweriduser id
Return values
arrayof objects, indexed by example submission id
See also
workshop::prepare_example_summary()

◆ get_feedbackauthor_form()

workshop::get_feedbackauthor_form (   $actionurl,
stdclass  $submission,
  $options = array() 
)

Returns the mform the teachers use to put a feedback for the author on their submission.

@mixed moodle_url|null $actionurl

Parameters
stdClass$submission
array$optionseditable
Return values
workshop_feedbackauthor_form

◆ get_feedbackreviewer_form()

workshop::get_feedbackreviewer_form (   $actionurl,
stdclass  $assessment,
  $options = array() 
)

Returns the mform the teachers use to put a feedback for the reviewer.

Parameters
mixedmoodle_url|null $actionurl
stdClass$assessment
array$optionseditable, editableweight, overridablegradinggrade
Return values
workshop_feedbackreviewer_form

◆ get_gradebook_grades()

workshop::get_gradebook_grades (   $userid)

Returns the information about the user's grades as they are stored in the gradebook.

The submission grade is returned for users with the capability mod/workshop:submit and the assessment grade is returned for users with the capability mod/workshop:peerassess. Unless the user has the capability to view hidden grades, grades must be visible to be returned. Null grades are not returned. If none grade is to be returned, this method returns false.

Parameters
int$useridthe user's id
Return values
workshop_final_grades|false

◆ get_grouped()

workshop::get_grouped (   $users)

Groups the given users by the group membership.

This takes the module grouping settings into account. If a grouping is set, returns only groups withing the course module grouping. Always returns group [0] with all the given users.

Parameters
array$usersarray[userid] => stdclass{->id ->lastname ->firstname}
Return values
arrayarray[groupid][userid] => stdclass{->id ->lastname ->firstname}

◆ get_participants()

workshop::get_participants (   $musthavesubmission = false,
  $groupid = 0,
  $limitfrom = 0,
  $limitnum = 0 
)

Fetches all enrolled users that are authors or reviewers (or both) in the current workshop.

The returned objects contain properties required by user_picture and are ordered by lastname, firstname. Only users with the active enrolment are returned.

See also
self::get_potential_authors()
self::get_potential_reviewers()
Parameters
bool$musthavesubmissionif true, return only users who have already submitted
int$groupid0 means ignore groups, any other value limits the result by group id
int$limitfromreturn a subset of records, starting at this point (optional, required if $limitnum is set)
int$limitnumreturn a subset containing this number of records (optional, required if $limitfrom is set)
Return values
arrayarray[userid] => stdClass

◆ get_participants_sql()

workshop::get_participants_sql (   $musthavesubmission = false,
  $groupid = 0 
)
protected

Returns SQL statement that can be used to fetch all actively enrolled participants in the workshop.

Parameters
bool$musthavesubmissionif true, return only users who have already submitted
int$groupid0 means ignore groups, any other value limits the result by group id
Return values
arrayof (string)sql, (array)params

◆ get_pending_assessments_by_reviewer()

workshop::get_pending_assessments_by_reviewer (   $reviewerid,
  $exclude = null 
)

Get allocated assessments not graded yet by the given reviewer.

See also
self::get_assessments_by_reviewer()
Parameters
int$revieweridthe reviewer id
null | int | array$excludeoptional assessment id (or list of them) to be excluded
Return values
array

◆ get_potential_authors()

workshop::get_potential_authors (   $musthavesubmission = true,
  $groupid = 0,
  $limitfrom = 0,
  $limitnum = 0 
)

Fetches all enrolled users with the capability mod/workshop:submit in the current workshop.

The returned objects contain properties required by user_picture and are ordered by lastname, firstname. Only users with the active enrolment are returned.

Parameters
bool$musthavesubmissionif true, return only users who have already submitted
int$groupid0 means ignore groups, any other value limits the result by group id
int$limitfromreturn a subset of records, starting at this point (optional, required if $limitnum is set)
int$limitnumreturn a subset containing this number of records (optional, required if $limitfrom is set)
Return values
arrayarray[userid] => stdClass

◆ get_potential_reviewers()

workshop::get_potential_reviewers (   $musthavesubmission = false,
  $groupid = 0,
  $limitfrom = 0,
  $limitnum = 0 
)

Fetches all enrolled users with the capability mod/workshop:peerassess in the current workshop.

The returned objects contain properties required by user_picture and are ordered by lastname, firstname. Only users with the active enrolment are returned.

Parameters
bool$musthavesubmissionif true, return only users who have already submitted
int$groupid0 means ignore groups, any other value limits the result by group id
int$limitfromreturn a subset of records, starting at this point (optional, required if $limitnum is set)
int$limitnumreturn a subset containing this number of records (optional, required if $limitfrom is set)
Return values
arrayarray[userid] => stdClass

◆ get_published_submissions()

workshop::get_published_submissions (   $orderby = 'finalgrade DESC')

Returns published submissions with their authors data.

Return values
arrayof stdclass

◆ get_submission_by_author()

workshop::get_submission_by_author (   $authorid)

Returns a submission submitted by the given author.

Parameters
int$idauthor id
Return values
stdclass|false

◆ get_submission_by_id()

workshop::get_submission_by_id (   $id)

Returns a submission record with the author's data.

Parameters
int$idsubmission id
Return values
stdclass

◆ get_submissions()

workshop::get_submissions (   $authorid = 'all',
  $groupid = 0,
  $limitfrom = 0,
  $limitnum = 0 
)

Returns submissions from this workshop.

Fetches data from {workshop_submissions} and adds some useful information from other tables. Does not return textual fields to prevent possible memory lack issues.

See also
self::count_submissions()
Parameters
mixed$authoridint|array|'all' If set to [array of] integer, return submission[s] of the given user[s] only
int$groupidIf non-zero, return only submissions by authors in the specified group
int$limitfromReturn a subset of records, starting at this point (optional)
int$limitnumReturn a subset containing this many records in total (optional, required if $limitfrom is set)
Return values
arrayof records or an empty array

◆ get_users_with_capability_sql()

workshop::get_users_with_capability_sql (   $capability,
  $musthavesubmission,
  $groupid 
)
protected

Returns SQL to fetch all enrolled users with the given capability in the current workshop.

The returned array consists of string $sql and the $params array. Note that the $sql can be empty if a grouping is selected and it has no groups.

The list is automatically restricted according to any availability restrictions that apply to user lists (e.g. group, grouping restrictions).

Parameters
string$capabilitythe name of the capability
bool$musthavesubmissionff true, return only users who have already submitted
int$groupid0 means ignore groups, any other value limits the result by group id
Return values
arrayof (string)sql, (array)params

◆ get_visible_submissions()

workshop::get_visible_submissions (   $authorid = 0,
  $groupid = 0,
  $limitfrom = 0,
  $limitnum = 0 
)

Returns submissions from this workshop that are viewable by the current user (except example submissions).

Parameters
mixed$authoridint|array If set to [array of] integer, return submission[s] of the given user[s] only
int$groupidIf non-zero, return only submissions by authors in the specified group. 0 for all groups.
int$limitfromReturn a subset of records, starting at this point (optional)
int$limitnumReturn a subset containing this many records in total (optional, required if $limitfrom is set)
Return values
arrayof records and the total submissions count
Since
Moodle 3.4

◆ grading_evaluation_instance()

workshop::grading_evaluation_instance ( )

Returns instance of grading evaluation class.

Return values
stdclassInstance of a grading evaluation

◆ grading_strategy_instance()

workshop::grading_strategy_instance ( )

Returns instance of grading strategy class.

Return values
stdclassInstance of a grading strategy

◆ installed_allocators()

static workshop::installed_allocators ( )
static

Return list of available allocation methods.

Return values
arrayArray ['string' => 'string'] of localized allocation method names

◆ instruction_editors_options()

static workshop::instruction_editors_options ( stdclass  $context)
static

Returns an array of options for the editors that are used for submitting and assessing instructions.

Parameters
stdClass$context@uses EDITOR_UNLIMITED_FILES hard-coded value for the 'maxfiles' option
Return values
array

◆ invalid_file_extensions()

static workshop::invalid_file_extensions (   $extensions,
  $whitelist 
)
static

Check given file types and return invalid/unknown ones.

Empty whitelist is interpretted as "any extension is valid".

Deprecated:
since Moodle 3.4 MDL-56486 - please use the core_form::filetypes_util
Parameters
string | array$extensionslist of file extensions
string | array$whitelistlist of valid extensions
Return values
arraylist of invalid extensions not found in the whitelist

◆ is_allowed_file_type()

static workshop::is_allowed_file_type (   $filename,
  $whitelist 
)
static

Is the file have allowed to be uploaded to the workshop?

Empty whitelist is interpretted as "any file type is allowed" rather than "no file can be uploaded".

Deprecated:
since Moodle 3.4 MDL-56486 - please use the core_form::filetypes_util
Parameters
string$filenamethe file name
string | array$whitelistlist of allowed file extensions
Return values
false

◆ is_participant()

workshop::is_participant (   $userid = null)

Checks if the given user is an actively enrolled participant in the workshop.

Parameters
int$userid,defaultsto the current $USER
Return values
boolean

◆ lcm()

static workshop::lcm (   $a,
  $b 
)
static

Helper function returning the least common multiple.

Parameters
int$a
int$b
Return values
int

◆ log()

workshop::log (   $action,
moodle_url  $url = null,
  $info = null,
  $return = false 
)

Workshop wrapper around {.

See also
add_to_log()}
Deprecated:
since 2.7 Please use the provided event classes for logging actions.
Parameters
string$actionto be logged
moodle_url$urlabsolute url as returned by {
See also
workshop::submission_url()} and friends
Parameters
mixed$infoadditional info, usually id in a table
bool$returntrue to return the arguments for add_to_log.
Return values
void|arrayarray of arguments for add_to_log if $return is true

◆ log_convert_url()

workshop::log_convert_url ( moodle_url  $fullurl)
protected

Converts absolute URL to relative URL needed by {.

See also
add_to_log()}
Parameters
moodle_url$urlabsolute URL
Return values
string

◆ modifying_submission_allowed()

workshop::modifying_submission_allowed (   $userid)

Is the given user allowed to modify their existing submission?

Parameters
int$userid
Return values
bool

◆ normalize_file_extensions()

static workshop::normalize_file_extensions (   $extensions)
static

Converts the argument into an array (list) of file extensions.

The list can be separated by whitespace, end of lines, commas colons and semicolons. Empty values are not returned. Values are converted to lowercase. Duplicates are removed. Glob evaluation is not supported.

Deprecated:
since Moodle 3.4 MDL-56486 - please use the core_form::filetypes_util
Parameters
string | array$extensionslist of file extensions
Return values
arrayof strings

◆ overall_feedback_attachment_options()

workshop::overall_feedback_attachment_options ( )

Return the filemanager options for the overall feedback for the author.

Return values
array

◆ overall_feedback_content_options()

workshop::overall_feedback_content_options ( )

Return the editor options for the overall feedback for the author.

Return values
array

◆ percent_to_value()

static workshop::percent_to_value (   $percent,
  $total 
)
static

Given the percent and the total, returns the number.

Parameters
float$percentfrom 0 to 100
float$totalthe 100% value
Return values
float

◆ prepare_assessment()

workshop::prepare_assessment ( stdClass  $record,
  $form,
array  $options = array() 
)

Prepares renderable assessment component.

The $options array supports the following keys: showauthor - should the author user info be available for the renderer showreviewer - should the reviewer user info be available for the renderer showform - show the assessment form if it is available showweight - should the assessment weight be available for the renderer

Parameters
stdClass$recordas returned by eg self::get_assessment_by_id()
workshop_assessment_form | null$formas returned by workshop_strategy::get_assessment_form()
array$options
Return values
workshop_assessment

◆ prepare_example_assessment()

workshop::prepare_example_assessment ( stdClass  $record,
  $form = null,
array  $options = array() 
)

Prepares renderable example submission's assessment component.

The $options array supports the following keys: showauthor - should the author user info be available for the renderer showreviewer - should the reviewer user info be available for the renderer showform - show the assessment form if it is available

Parameters
stdClass$recordas returned by eg self::get_assessment_by_id()
workshop_assessment_form | null$formas returned by workshop_strategy::get_assessment_form()
array$options
Return values
workshop_example_assessment

◆ prepare_example_reference_assessment()

workshop::prepare_example_reference_assessment ( stdClass  $record,
  $form = null,
array  $options = array() 
)

Prepares renderable example submission's reference assessment component.

The $options array supports the following keys: showauthor - should the author user info be available for the renderer showreviewer - should the reviewer user info be available for the renderer showform - show the assessment form if it is available

Parameters
stdClass$recordas returned by eg self::get_assessment_by_id()
workshop_assessment_form | null$formas returned by workshop_strategy::get_assessment_form()
array$options
Return values
workshop_example_reference_assessment

◆ prepare_example_submission()

workshop::prepare_example_submission ( stdClass  $record)

Prepares renderable example submission component.

Parameters
stdClass$recordrequired by {
See also
workshop_example_submission}
Return values
workshop_example_submission

◆ prepare_example_summary()

workshop::prepare_example_summary ( stdClass  $example)

Prepares renderable example submission summary component.

If the example is editable, the caller must set the 'editable' flag explicitly.

Parameters
stdClass$exampleas returned by workshop::get_examples_for_manager() or workshop::get_examples_for_reviewer()
Return values
workshop_example_submission_summaryto be rendered

◆ prepare_grading_report_data()

workshop::prepare_grading_report_data (   $userid,
  $groupid,
  $page,
  $perpage,
  $sortby,
  $sorthow 
)

Prepares data object with all workshop grades to be rendered.

Parameters
int$useridthe user we are preparing the report for
int$groupidif non-zero, prepare the report for the given group only
int$pagethe current page (for the pagination)
int$perpageparticipants per page (for the pagination)
string$sortbylastname|firstname|submissiontitle|submissiongrade|gradinggrade
string$sorthowASC|DESC
Return values
stdclassdata for the renderer

◆ prepare_submission()

workshop::prepare_submission ( stdClass  $record,
  $showauthor = false 
)

Prepares renderable submission component.

Parameters
stdClass$recordrequired by {
See also
workshop_submission}
Parameters
bool$showauthorshow the author-related information
Return values
workshop_submission

◆ prepare_submission_summary()

workshop::prepare_submission_summary ( stdClass  $record,
  $showauthor = false 
)

Prepares renderable submission summary component.

Parameters
stdClass$recordrequired by {
See also
workshop_submission_summary}
Parameters
bool$showauthorshow the author-related information
Return values
workshop_submission_summary

◆ previewform_url()

workshop::previewform_url ( )
Return values
moodle_urlof the page for previewing this workshop's grading form

◆ raw_grade_value()

workshop::raw_grade_value (   $value,
  $max 
)

Calculates the raw (percentual) value from a real grade.

This is used in cases when a user wants to give a grade such as 12 of 20 and we need to save this value in a raw percentual form into DB

Parameters
float$valuegiven grade
float$maxthe maximal grade
Return values
floatsuitable to be stored as numeric(10,5)

◆ real_grade()

workshop::real_grade (   $value)

Calculates the real value of grade for submission.

Parameters
float$valuepercentual value from 0 to 100
Return values
string

◆ real_grade_value()

workshop::real_grade_value (   $value,
  $max 
)

Calculates the real value of a grade.

Parameters
float$valuepercentual value from 0 to 100
float$maxthe maximal grade
Return values
string

◆ real_grading_grade()

workshop::real_grading_grade (   $value)

Calculates the real value of grade for assessment.

Parameters
float$valuepercentual value from 0 to 100
Return values
string

◆ reset_userdata()

workshop::reset_userdata ( stdClass  $data)

Performs the reset of this workshop instance.

Parameters
stdClass$dataThe actual course reset settings.
Return values
arrayList of results, each being array[(string)component, (string)item, (string)error]

◆ reset_userdata_assessments()

workshop::reset_userdata_assessments ( stdClass  $data)
protected

Removes all user data related to assessments (including allocations).

This includes assessments of example submissions as long as they are not referential assessments.

Parameters
stdClass$dataThe actual course reset settings.
Return values
bool|stringTrue on success, error message otherwise.

◆ reset_userdata_submissions()

workshop::reset_userdata_submissions ( stdClass  $data)
protected

Removes all user data related to participants' submissions.

Parameters
stdClass$dataThe actual course reset settings.
Return values
bool|stringTrue on success, error message otherwise.

◆ set_grading_evaluation_method()

workshop::set_grading_evaluation_method (   $method)

Sets the current evaluation method to the given plugin.

Parameters
string$methodthe name of the workshopeval subplugin
Return values
booltrue if successfully set
Exceptions
coding_exceptionif attempting to set a non-installed evaluation method

◆ set_module_viewed()

workshop::set_module_viewed ( )

Trigger module viewed event and set the module viewed for completion.

Since
Moodle 3.4

◆ set_peer_grade()

workshop::set_peer_grade (   $assessmentid,
  $grade 
)

Saves a raw grade for submission as calculated from the assessment form fields.

Parameters
array$assessmentidassessment record id, must exists
mixed$graderaw percentual grade from 0.00000 to 100.00000
Return values
false|floatthe saved grade

◆ set_submission_viewed()

workshop::set_submission_viewed (   $submission)

Trigger submission viewed event.

Parameters
stdClass$submissionsubmission object
Since
Moodle 3.4

◆ submission_attachment_options()

workshop::submission_attachment_options ( )

Return the filemanager options for the submission attachments field.

Return values
array

◆ submission_content_options()

workshop::submission_content_options ( )

Return the editor options for the submission content field.

Return values
array

◆ submission_url()

workshop::submission_url (   $id = null)
Return values
moodle_urlof the page to view a submission, defaults to the own one

◆ switch_phase()

workshop::switch_phase (   $newphase)

Switch to a new workshop phase.

Modifies the underlying database record. You should terminate the script shortly after calling this.

Parameters
int$newphasenew phase code
Return values
booltrue if success, false otherwise

◆ switchphase_url()

workshop::switchphase_url (   $phasecode)
Parameters
int$phasecodeThe internal phase code
Return values
moodle_urlof the script to change the current phase to $phasecode

◆ timestamp_formats()

static workshop::timestamp_formats (   $timestamp)
static

Returns an object suitable for strings containing dates/times.

The returned object contains properties date, datefullshort, datetime, ... containing the given timestamp formatted using strftimedate, strftimedatefullshort, strftimedatetime, ... from the current lang's langconfig.php This allows translators and administrators customize the date/time format.

Parameters
int$timestampthe timestamp in UTC
Return values
stdclass

◆ toolbox_url()

workshop::toolbox_url (   $tool)
Return values
moodle_urlof this workshop's toolbox page

◆ updatemod_url()

workshop::updatemod_url ( )
Return values
moodle_urlof the mod_edit form

◆ validate_submission_data()

workshop::validate_submission_data (   $data)

Validates the submission form or WS data.

Parameters
array$datathe data to be validated
Return values
arraythe validation errors (if any)
Since
Moodle 3.4

◆ view_url()

workshop::view_url ( )
Return values
moodle_urlof this workshop's view page

The documentation for this class was generated from the following file: