Search moodle.org's
Developer Documentation

See Release Notes

  • Bug fixes for general core bugs in 3.11.x will end 14 Nov 2022 (12 months plus 6 months extension).
  • Bug fixes for security issues in 3.11.x will end 13 Nov 2023 (18 months plus 12 months extension).
  • PHP version: minimum PHP 7.3.0 Note: minimum PHP version has increased since Moodle 3.10. PHP 7.4.x is supported too.
/mod/workshop/ -> locallib.php (source)

[Source view]

Differences Between: [Versions 310 and 311] [Versions 311 and 401] [Versions 311 and 402] [Versions 311 and 403] [Versions 39 and 311]

Library of internal classes and functions for module workshop All the workshop specific functions, needed to implement the module logic, should go to here. Instead of having bunch of function named workshop_something() taking the workshop instance as the first parameter, we use a class workshop that provides all methods.

Copyright: 2009 David Mudrak <david.mudrak@gmail.com>
License: http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
File Size: 4763 lines (190 kb)
Included or required: 20 times
Referenced: 13 times
Includes or requires: 3 files
 mod/workshop/feedbackreviewer_form.php
 mod/workshop/lib.php
 mod/workshop/feedbackauthor_form.php

Defines 17 classes

workshop:: (116 methods):
  __construct()
  installed_allocators()
  instruction_editors_options()
  percent_to_value()
  available_maxgrades_list()
  available_example_modes_list()
  available_strategies_list()
  available_evaluators_list()
  available_dimension_weights_list()
  available_assessment_weights_list()
  gcd()
  lcm()
  timestamp_formats()
  normalize_file_extensions()
  clean_file_extensions()
  invalid_file_extensions()
  is_allowed_file_type()
  get_potential_authors()
  count_potential_authors()
  get_potential_reviewers()
  count_potential_reviewers()
  get_participants()
  count_participants()
  is_participant()
  get_grouped()
  get_allocations()
  count_submissions()
  get_submissions()
  get_visible_submissions()
  get_submission_by_id()
  get_submission_by_author()
  get_published_submissions()
  get_example_by_id()
  get_examples_for_manager()
  get_examples_for_reviewer()
  prepare_submission()
  prepare_submission_summary()
  prepare_example_submission()
  prepare_example_summary()
  prepare_assessment()
  prepare_example_assessment()
  prepare_example_reference_assessment()
  delete_submission()
  get_all_assessments()
  get_assessment_by_id()
  get_assessment_of_submission_by_user()
  get_assessments_of_submission()
  get_assessments_by_reviewer()
  get_pending_assessments_by_reviewer()
  add_allocation()
  delete_assessment()
  grading_strategy_instance()
  set_grading_evaluation_method()
  grading_evaluation_instance()
  allocator_instance()
  view_url()
  editform_url()
  previewform_url()
  assess_url()
  exassess_url()
  submission_url()
  exsubmission_url()
  compare_url()
  excompare_url()
  updatemod_url()
  allocation_url()
  switchphase_url()
  aggregate_url()
  toolbox_url()
  log()
  creating_submission_allowed()
  modifying_submission_allowed()
  assessing_allowed()
  assessing_examples_allowed()
  assessments_available()
  switch_phase()
  set_peer_grade()
  prepare_grading_report_data()
  real_grade_value()
  raw_grade_value()
  real_grade()
  real_grading_grade()
  clear_assessments()
  clear_submission_grades()
  aggregate_submission_grades()
  clear_grading_grades()
  aggregate_grading_grades()
  get_feedbackreviewer_form()
  get_feedbackauthor_form()
  get_gradebook_grades()
  submission_content_options()
  submission_attachment_options()
  overall_feedback_content_options()
  overall_feedback_attachment_options()
  reset_userdata()
  check_group_membership()
  check_examples_assessed_before_submission()
  check_examples_assessed_before_assessment()
  set_module_viewed()
  validate_submission_data()
  edit_submission()
  check_view_assessment()
  check_edit_assessment()
  edit_assessment()
  evaluate_assessment()
  set_submission_viewed()
  evaluate_submission()
  aggregate_submission_grades_process()
  aggregate_grading_grades_process()
  get_users_with_capability_sql()
  get_participants_sql()
  available_phases_list()
  log_convert_url()
  reset_userdata_assessments()
  reset_userdata_submissions()
  reset_phase()

workshop_user_plan:: (2 methods):
  __construct()
  get_examples()

workshop_submission_base:: (3 methods):
  __construct()
  anonymize()
  is_anonymous()

workshop_submission_summary:: (0 methods):

workshop_submission:: (0 methods):

workshop_example_submission_summary:: (1 method):
  is_anonymous()

workshop_example_submission:: (0 methods):

workshop_assessment_base:: (3 methods):
  __construct()
  add_action()
  validate_raw_record()

workshop_assessment:: (2 methods):
  get_overall_feedback_content()
  get_overall_feedback_attachments()

workshop_example_assessment:: (1 method):
  validate_raw_record()

workshop_example_reference_assessment:: (1 method):
  validate_raw_record()

workshop_message:: (8 methods):
  __construct()
  set_text()
  set_type()
  set_action()
  get_message()
  get_type()
  get_action_url()
  get_action_label()

workshop_grading_report:: (4 methods):
  __construct()
  get_data()
  get_options()
  export_data_for_external()

workshop_feedback:: (3 methods):
  get_provider()
  get_content()
  get_format()

workshop_feedback_author:: (1 method):
  __construct()

workshop_feedback_reviewer:: (1 method):
  __construct()

workshop_final_grades:: (0 methods):


Class: workshop  - X-Ref

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.
__construct(stdclass $dbrecord, $cm, $course, stdclass $context=null)   X-Ref
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.

param: stdClass $dbrecord Workshop instance data from {workshop} table
param: stdClass|cm_info $cm Course module record
param: stdClass $course Course record from {course} table
param: stdClass $context The context of the workshop instance

installed_allocators()   X-Ref
Return list of available allocation methods

return: array Array ['string' => 'string'] of localized allocation method names

instruction_editors_options(stdclass $context)   X-Ref
Returns an array of options for the editors that are used for submitting and assessing instructions

param: stdClass $context
return: array

percent_to_value($percent, $total)   X-Ref
Given the percent and the total, returns the number

param: float $percent from 0 to 100
param: float $total   the 100% value
return: float

available_maxgrades_list()   X-Ref
Returns an array of numeric values that can be used as maximum grades

return: array Array of integers

available_example_modes_list()   X-Ref
Returns the localized list of supported examples modes

return: array

available_strategies_list()   X-Ref
Returns the list of available grading strategy methods

return: array ['string' => 'string']

available_evaluators_list()   X-Ref
Returns the list of available grading evaluation methods

return: array of (string)name => (string)localized title

available_dimension_weights_list()   X-Ref
Return an array of possible values of assessment dimension weight

return: array of integers 0, 1, 2, ..., 16

available_assessment_weights_list()   X-Ref
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: array of integers 0, 1, 2, ..., 16

gcd($a, $b)   X-Ref
Helper function returning the greatest common divisor

param: int $a
param: int $b
return: int

lcm($a, $b)   X-Ref
Helper function returning the least common multiple

param: int $a
param: int $b
return: int

timestamp_formats($timestamp)   X-Ref
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.

param: int $timestamp the timestamp in UTC
return: stdclass

normalize_file_extensions($extensions)   X-Ref
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.

param: string|array $extensions list of file extensions
return: array of strings

clean_file_extensions($extensions)   X-Ref
Cleans the user provided list of file extensions.

param: string $extensions
return: string

invalid_file_extensions($extensions, $allowlist)   X-Ref
Check given file types and return invalid/unknown ones.

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

param: string|array $extensions list of file extensions
param: string|array $allowlist list of valid extensions
return: array list of invalid extensions not found in the allowlist

is_allowed_file_type($filename, $allowlist)   X-Ref
Is the file have allowed to be uploaded to the workshop?

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

param: string $filename the file name
param: string|array $allowlist list of allowed file extensions
return: false

get_potential_authors($musthavesubmission=true, $groupid=0, $limitfrom=0, $limitnum=0)   X-Ref
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.

param: bool $musthavesubmission if true, return only users who have already submitted
param: int $groupid 0 means ignore groups, any other value limits the result by group id
param: int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set)
param: int $limitnum return a subset containing this number of records (optional, required if $limitfrom is set)
return: array array[userid] => stdClass

count_potential_authors($musthavesubmission=true, $groupid=0)   X-Ref
Returns the total number of users that would be fetched by {@link self::get_potential_authors()}

param: bool $musthavesubmission if true, count only users who have already submitted
param: int $groupid 0 means ignore groups, any other value limits the result by group id
return: int

get_potential_reviewers($musthavesubmission=false, $groupid=0, $limitfrom=0, $limitnum=0)   X-Ref
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.

param: bool $musthavesubmission if true, return only users who have already submitted
param: int $groupid 0 means ignore groups, any other value limits the result by group id
param: int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set)
param: int $limitnum return a subset containing this number of records (optional, required if $limitfrom is set)
return: array array[userid] => stdClass

count_potential_reviewers($musthavesubmission=false, $groupid=0)   X-Ref
Returns the total number of users that would be fetched by {@link self::get_potential_reviewers()}

param: bool $musthavesubmission if true, count only users who have already submitted
param: int $groupid 0 means ignore groups, any other value limits the result by group id
return: int

get_participants($musthavesubmission=false, $groupid=0, $limitfrom=0, $limitnum=0)   X-Ref
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.

param: bool $musthavesubmission if true, return only users who have already submitted
param: int $groupid 0 means ignore groups, any other value limits the result by group id
param: int $limitfrom return a subset of records, starting at this point (optional, required if $limitnum is set)
param: int $limitnum return a subset containing this number of records (optional, required if $limitfrom is set)
return: array array[userid] => stdClass

count_participants($musthavesubmission=false, $groupid=0)   X-Ref
Returns the total number of records that would be returned by {@link self::get_participants()}

param: bool $musthavesubmission if true, return only users who have already submitted
param: int $groupid 0 means ignore groups, any other value limits the result by group id
return: int

is_participant($userid=null)   X-Ref
Checks if the given user is an actively enrolled participant in the workshop

param: int $userid, defaults to the current $USER
return: boolean

get_grouped($users)   X-Ref
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.

param: array $users array[userid] => stdclass{->id ->lastname ->firstname}
return: array array[groupid][userid] => stdclass{->id ->lastname ->firstname}

get_allocations()   X-Ref
Returns the list of all allocations (i.e. assigned assessments) in the workshop

Assessments of example submissions are ignored

return: array

count_submissions($authorid='all', $groupid=0)   X-Ref
Returns the total number of records that would be returned by {@link self::get_submissions()}

param: mixed $authorid int|array|'all' If set to [array of] integer, return submission[s] of the given user[s] only
param: int $groupid If non-zero, return only submissions by authors in the specified group
return: int number of records

get_submissions($authorid='all', $groupid=0, $limitfrom=0, $limitnum=0)   X-Ref
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.

param: mixed $authorid int|array|'all' If set to [array of] integer, return submission[s] of the given user[s] only
param: int $groupid If non-zero, return only submissions by authors in the specified group
param: int $limitfrom Return a subset of records, starting at this point (optional)
param: int $limitnum Return a subset containing this many records in total (optional, required if $limitfrom is set)
return: array of records or an empty array

get_visible_submissions($authorid = 0, $groupid = 0, $limitfrom = 0, $limitnum = 0)   X-Ref
Returns submissions from this workshop that are viewable by the current user (except example submissions).

param: mixed $authorid int|array If set to [array of] integer, return submission[s] of the given user[s] only
param: int $groupid If non-zero, return only submissions by authors in the specified group. 0 for all groups.
param: int $limitfrom Return a subset of records, starting at this point (optional)
param: int $limitnum Return a subset containing this many records in total (optional, required if $limitfrom is set)
return: array of records and the total submissions count

get_submission_by_id($id)   X-Ref
Returns a submission record with the author's data

param: int $id submission id
return: stdclass

get_submission_by_author($authorid)   X-Ref
Returns a submission submitted by the given author

param: int $id author id
return: stdclass|false

get_published_submissions($orderby='finalgrade DESC')   X-Ref
Returns published submissions with their authors data

return: array of stdclass

get_example_by_id($id)   X-Ref
Returns full record of the given example submission

param: int $id example submission od
return: object

get_examples_for_manager()   X-Ref
Returns the list of example submissions in this workshop with reference assessments attached

return: array of objects or an empty array

get_examples_for_reviewer($reviewerid)   X-Ref
Returns the list of all example submissions in this workshop with the information of assessments done by the given user

param: int $reviewerid user id
return: array of objects, indexed by example submission id

prepare_submission(stdClass $record, $showauthor = false)   X-Ref
Prepares renderable submission component

param: stdClass $record required by {@see workshop_submission}
param: bool $showauthor show the author-related information
return: workshop_submission

prepare_submission_summary(stdClass $record, $showauthor = false)   X-Ref
Prepares renderable submission summary component

param: stdClass $record required by {@see workshop_submission_summary}
param: bool $showauthor show the author-related information
return: workshop_submission_summary

prepare_example_submission(stdClass $record)   X-Ref
Prepares renderable example submission component

param: stdClass $record required by {@see workshop_example_submission}
return: workshop_example_submission

prepare_example_summary(stdClass $example)   X-Ref
Prepares renderable example submission summary component

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

param: stdClass $example as returned by {@link workshop::get_examples_for_manager()} or {@link workshop::get_examples_for_reviewer()}
return: workshop_example_submission_summary to be rendered

prepare_assessment(stdClass $record, $form, array $options = array()   X-Ref
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

param: stdClass $record as returned by eg {@link self::get_assessment_by_id()}
param: workshop_assessment_form|null $form as returned by {@link workshop_strategy::get_assessment_form()}
param: array $options
return: workshop_assessment

prepare_example_assessment(stdClass $record, $form = null, array $options = array()   X-Ref
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

param: stdClass $record as returned by eg {@link self::get_assessment_by_id()}
param: workshop_assessment_form|null $form as returned by {@link workshop_strategy::get_assessment_form()}
param: array $options
return: workshop_example_assessment

prepare_example_reference_assessment(stdClass $record, $form = null, array $options = array()   X-Ref
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

param: stdClass $record as returned by eg {@link self::get_assessment_by_id()}
param: workshop_assessment_form|null $form as returned by {@link workshop_strategy::get_assessment_form()}
param: array $options
return: workshop_example_reference_assessment

delete_submission(stdclass $submission)   X-Ref
Removes the submission and all relevant data

param: stdClass $submission record to delete
return: void

get_all_assessments()   X-Ref
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: array [assessmentid] => assessment stdclass

get_assessment_by_id($id)   X-Ref
Get the complete information about the given assessment

param: int $id Assessment ID
return: stdclass

get_assessment_of_submission_by_user($submissionid, $reviewerid)   X-Ref
Get the complete information about the user's assessment of the given submission

param: int $sid submission ID
param: int $uid user ID of the reviewer
return: false|stdclass false if not found, stdclass otherwise

get_assessments_of_submission($submissionid)   X-Ref
Get the complete information about all assessments of the given submission

param: int $submissionid
return: array

get_assessments_by_reviewer($reviewerid)   X-Ref
Get the complete information about all assessments allocated to the given reviewer

param: int $reviewerid
return: array

get_pending_assessments_by_reviewer($reviewerid, $exclude = null)   X-Ref
Get allocated assessments not graded yet by the given reviewer

param: int $reviewerid the reviewer id
param: null|int|array $exclude optional assessment id (or list of them) to be excluded
return: array

add_allocation(stdclass $submission, $reviewerid, $weight=1, $bulk=false)   X-Ref
Allocate a submission to a user for review

param: stdClass $submission Submission object with at least id property
param: int $reviewerid User ID
param: int $weight of the new assessment, from 0 to 16
param: bool $bulk repeated inserts into DB expected
return: int ID of the new assessment or an error code {@link self::ALLOCATION_EXISTS} if the allocation already exists

delete_assessment($id)   X-Ref
Delete assessment record or records.

Removes associated records from the workshop_grades table, too.

param: int|array $id assessment id or array of assessments ids
return: bool true

grading_strategy_instance()   X-Ref
Returns instance of grading strategy class

return: stdclass Instance of a grading strategy

set_grading_evaluation_method($method)   X-Ref
Sets the current evaluation method to the given plugin.

param: string $method the name of the workshopeval subplugin
return: bool true if successfully set

grading_evaluation_instance()   X-Ref
Returns instance of grading evaluation class

return: stdclass Instance of a grading evaluation

allocator_instance($method)   X-Ref
Returns instance of submissions allocator

param: string $method The name of the allocation method, must be PARAM_ALPHA
return: stdclass Instance of submissions allocator

view_url()   X-Ref

return: moodle_url of this workshop's view page

editform_url()   X-Ref

return: moodle_url of the page for editing this workshop's grading form

previewform_url()   X-Ref

return: moodle_url of the page for previewing this workshop's grading form

assess_url($assessmentid)   X-Ref

param: int $assessmentid The ID of assessment record
return: moodle_url of the assessment page

exassess_url($assessmentid)   X-Ref

param: int $assessmentid The ID of assessment record
return: moodle_url of the example assessment page

submission_url($id=null)   X-Ref

return: moodle_url of the page to view a submission, defaults to the own one

exsubmission_url($id)   X-Ref

param: int $id example submission id
return: moodle_url of the page to view an example submission

compare_url($sid, array $aids)   X-Ref

param: int $sid submission id
param: array $aid of int assessment ids
return: moodle_url of the page to compare assessments of the given submission

excompare_url($sid, $aid)   X-Ref

param: int $sid submission id
param: int $aid assessment id
return: moodle_url of the page to compare the reference assessments of the given example submission

updatemod_url()   X-Ref

return: moodle_url of the mod_edit form

allocation_url($method=null)   X-Ref

param: string $method allocation method
return: moodle_url to the allocation page

switchphase_url($phasecode)   X-Ref

param: int $phasecode The internal phase code
return: moodle_url of the script to change the current phase to $phasecode

aggregate_url()   X-Ref

return: moodle_url to the aggregation page

toolbox_url($tool)   X-Ref

return: moodle_url of this workshop's toolbox page

log($action, moodle_url $url = null, $info = null, $return = false)   X-Ref
Workshop wrapper around {@see add_to_log()}

param: string $action to be logged
param: moodle_url $url absolute url as returned by {@see workshop::submission_url()} and friends
param: mixed $info additional info, usually id in a table
param: bool $return true to return the arguments for add_to_log.
return: void|array array of arguments for add_to_log if $return is true

creating_submission_allowed($userid)   X-Ref
Is the given user allowed to create their submission?

param: int $userid
return: bool

modifying_submission_allowed($userid)   X-Ref
Is the given user allowed to modify their existing submission?

param: int $userid
return: bool

assessing_allowed($userid)   X-Ref
Is the given reviewer allowed to create/edit their assessments?

param: int $userid
return: bool

assessing_examples_allowed()   X-Ref
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: null|bool

assessments_available()   X-Ref
Are the peer-reviews available to the authors?

return: bool

switch_phase($newphase)   X-Ref
Switch to a new workshop phase

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

param: int $newphase new phase code
return: bool true if success, false otherwise

set_peer_grade($assessmentid, $grade)   X-Ref
Saves a raw grade for submission as calculated from the assessment form fields

param: array $assessmentid assessment record id, must exists
param: mixed $grade        raw percentual grade from 0.00000 to 100.00000
return: false|float        the saved grade

prepare_grading_report_data($userid, $groupid, $page, $perpage, $sortby, $sorthow)   X-Ref
Prepares data object with all workshop grades to be rendered

param: int $userid the user we are preparing the report for
param: int $groupid if non-zero, prepare the report for the given group only
param: int $page the current page (for the pagination)
param: int $perpage participants per page (for the pagination)
param: string $sortby lastname|firstname|submissiontitle|submissiongrade|gradinggrade
param: string $sorthow ASC|DESC
return: stdclass data for the renderer

real_grade_value($value, $max)   X-Ref
Calculates the real value of a grade

param: float $value percentual value from 0 to 100
param: float $max   the maximal grade
return: string

raw_grade_value($value, $max)   X-Ref
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
param: float $value given grade
param: float $max   the maximal grade
return: float       suitable to be stored as numeric(10,5)

real_grade($value)   X-Ref
Calculates the real value of grade for submission

param: float $value percentual value from 0 to 100
return: string

real_grading_grade($value)   X-Ref
Calculates the real value of grade for assessment

param: float $value percentual value from 0 to 100
return: string

clear_assessments()   X-Ref
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: void

clear_submission_grades($restrict=null)   X-Ref
Sets the grades for submission to null

param: null|int|array $restrict If null, update all authors, otherwise update just grades for the given author(s)
return: void

aggregate_submission_grades($restrict=null)   X-Ref
Calculates grades for submission for the given participant(s) and updates it in the database

param: null|int|array $restrict If null, update all authors, otherwise update just grades for the given author(s)
return: void

clear_grading_grades($restrict=null)   X-Ref
Sets the aggregated grades for assessment to null

param: null|int|array $restrict If null, update all reviewers, otherwise update just grades for the given reviewer(s)
return: void

aggregate_grading_grades($restrict=null)   X-Ref
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.

param: null|int|array $restrict If null, update all reviewers, otherwise update just grades for the given reviewer(s)
return: void

get_feedbackreviewer_form($actionurl, stdclass $assessment, $options=array()   X-Ref
Returns the mform the teachers use to put a feedback for the reviewer

param: mixed moodle_url|null $actionurl
param: stdClass $assessment
param: array $options editable, editableweight, overridablegradinggrade
return: workshop_feedbackreviewer_form

get_feedbackauthor_form($actionurl, stdclass $submission, $options=array()   X-Ref
Returns the mform the teachers use to put a feedback for the author on their submission

param: stdClass $submission
param: array $options editable
return: workshop_feedbackauthor_form

get_gradebook_grades($userid)   X-Ref
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.

param: int $userid the user's id
return: workshop_final_grades|false

submission_content_options()   X-Ref
Return the editor options for the submission content field.

return: array

submission_attachment_options()   X-Ref
Return the filemanager options for the submission attachments field.

return: array

overall_feedback_content_options()   X-Ref
Return the editor options for the overall feedback for the author.

return: array

overall_feedback_attachment_options()   X-Ref
Return the filemanager options for the overall feedback for the author.

return: array

reset_userdata(stdClass $data)   X-Ref
Performs the reset of this workshop instance.

param: stdClass $data The actual course reset settings.
return: array List of results, each being array[(string)component, (string)item, (string)error]

check_group_membership($otheruserid)   X-Ref
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
{@link 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.

param: int $otheruserid The ID of the other user, e.g. the author of a submission.
return: bool False if the current user cannot access the other user's group.

check_examples_assessed_before_submission($userid)   X-Ref
Check whether the given user has assessed all his required examples before submission.

param: int $userid the user to check
return: bool        false if there are examples missing assessment, true otherwise.

check_examples_assessed_before_assessment($userid)   X-Ref
Check that all required examples have been assessed by the given user.

param: stdClass $userid     the user (reviewer) to check
return: mixed bool|state     false and notice code if there are examples missing assessment, true otherwise.

set_module_viewed()   X-Ref
Trigger module viewed event and set the module viewed for completion.


validate_submission_data($data)   X-Ref
Validates the submission form or WS data.

param: array $data the data to be validated
return: array       the validation errors (if any)

edit_submission($submission)   X-Ref
Adds or updates a submission.

param: stdClass $submission The submissin data (via form or via WS).
return: the new or updated submission id.

check_view_assessment($assessment, $submission)   X-Ref
Helper method for validating if the current user can view the given assessment.

param: stdClass   $assessment assessment object
param: stdClass   $submission submission object
return: void

check_edit_assessment($assessment, $submission)   X-Ref
Helper method for validating if the current user can edit the given assessment.

param: stdClass   $assessment assessment object
param: stdClass   $submission submission object
return: void

edit_assessment($assessment, $submission, $data, $strategy)   X-Ref
Adds information to an allocated assessment (function used the first time a review is done or when updating an existing one).

param: stdClass $assessment the assessment
param: stdClass $submission the submission
param: stdClass $data       the assessment data to be added or Updated
param: stdClass $strategy   the strategy instance
return: float|null           Raw percentual grade (0.00000 to 100.00000) for submission

evaluate_assessment($assessment, $data, $cansetassessmentweight, $canoverridegrades)   X-Ref
Evaluates an assessment.

param: stdClass $assessment the assessment
param: stdClass $data       the assessment data to be updated
param: bool $cansetassessmentweight   whether the user can change the assessment weight
param: bool $canoverridegrades   whether the user can override the assessment grades
return: void

set_submission_viewed($submission)   X-Ref
Trigger submission viewed event.

param: stdClass $submission submission object

evaluate_submission($submission, $data, $canpublish, $canoverride)   X-Ref
Evaluates a submission.

param: stdClass $submission the submission
param: stdClass $data       the submission data to be updated
param: bool $canpublish     whether the user can publish the submission
param: bool $canoverride    whether the user can override the submission grade
return: void

aggregate_submission_grades_process(array $assessments)   X-Ref
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.

param: array $assessments of stdclass(->submissionid ->submissiongrade ->gradeover ->weight ->grade)
return: void

aggregate_grading_grades_process(array $assessments, $timegraded = null)   X-Ref
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.

param: array $assessments of stdclass(->reviewerid ->gradinggrade ->gradinggradeover ->aggregationid ->aggregatedgrade)
param: null|int $timegraded explicit timestamp of the aggregation, defaults to the current time
return: void

get_users_with_capability_sql($capability, $musthavesubmission, $groupid)   X-Ref
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).

param: string $capability the name of the capability
param: bool $musthavesubmission ff true, return only users who have already submitted
param: int $groupid 0 means ignore groups, any other value limits the result by group id
return: array of (string)sql, (array)params

get_participants_sql($musthavesubmission=false, $groupid=0)   X-Ref
Returns SQL statement that can be used to fetch all actively enrolled participants in the workshop

param: bool $musthavesubmission if true, return only users who have already submitted
param: int $groupid 0 means ignore groups, any other value limits the result by group id
return: array of (string)sql, (array)params

available_phases_list()   X-Ref

return: array of available workshop phases

log_convert_url(moodle_url $fullurl)   X-Ref
Converts absolute URL to relative URL needed by {@see add_to_log()}

param: moodle_url $url absolute URL
return: string

reset_userdata_assessments(stdClass $data)   X-Ref
Removes all user data related to assessments (including allocations).

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

param: stdClass $data The actual course reset settings.
return: bool|string True on success, error message otherwise.

reset_userdata_submissions(stdClass $data)   X-Ref
Removes all user data related to participants' submissions.

param: stdClass $data The actual course reset settings.
return: bool|string True on success, error message otherwise.

reset_phase()   X-Ref
Hard set the workshop phase to the setup one.


Class: workshop_user_plan  - X-Ref

Represents the user planner tool

Planner contains list of phases. Each phase contains list of tasks. Task is a simple object with
title, link and completed (true/false/null logic).
__construct(workshop $workshop, $userid)   X-Ref
Prepare an individual workshop plan for the given user.

param: workshop $workshop instance
param: int $userid whom the plan is prepared for

get_examples()   X-Ref
Returns example submissions to be assessed by the owner of the planner

This is here to cache the DB query because the same list is needed later in view.php

return: array

Class: workshop_submission_base  - X-Ref

Common base class for submissions and example submissions rendering

Subclasses of this class convert raw submission record from
workshop_submissions table (as returned by {@see workshop::get_submission_by_id()}
for example) into renderable objects.
__construct(workshop $workshop, stdClass $submission, $showauthor = false)   X-Ref
Copies the properties of the given database record into properties of $this instance

param: workshop $workshop
param: stdClass $submission full record
param: bool $showauthor show the author-related information
param: array $options additional properties

anonymize()   X-Ref
Unsets all author-related properties so that the renderer does not have access to them

Usually this is called by the contructor but can be called explicitely, too.

is_anonymous()   X-Ref
Does the submission object contain author-related information?

return: null|boolean

Class: workshop_submission_summary  - X-Ref

Renderable object containing a basic set of information needed to display the submission summary

Class: workshop_submission  - X-Ref

Renderable object containing all the information needed to display the submission

Class: workshop_example_submission_summary  - X-Ref

Renderable object containing a basic set of information needed to display the example submission summary

is_anonymous()   X-Ref
Example submissions are always anonymous

return: true

Class: workshop_example_submission  - X-Ref

Renderable object containing all the information needed to display the example submission

Class: workshop_assessment_base  - X-Ref

Common base class for assessments rendering

Subclasses of this class convert raw assessment record from
workshop_assessments table (as returned by {@see workshop::get_assessment_by_id()}
for example) into renderable objects.
__construct(workshop $workshop, stdClass $record, array $options = array()   X-Ref
Copies the properties of the given database record into properties of $this instance

The $options keys are: showreviewer, showauthor
param: workshop $workshop
param: stdClass $assessment full record
param: array $options additional properties

add_action(moodle_url $url, $label, $method = 'get')   X-Ref
Adds a new action

param: moodle_url $url action URL
param: string $label action label
param: string $method get|post

validate_raw_record(stdClass $record)   X-Ref
Makes sure that we can cook the renderable component from the passed raw database record

param: stdClass $assessment full assessment record

Class: workshop_assessment  - X-Ref

Represents a rendarable full assessment

get_overall_feedback_content()   X-Ref
Format the overall feedback text content

False is returned if the overall feedback feature is disabled. Null is returned
if the overall feedback content has not been found. Otherwise, string with
formatted feedback text is returned.

return: string|bool|null

get_overall_feedback_attachments()   X-Ref
Prepares the list of overall feedback attachments

Returns false if overall feedback attachments are not allowed. Otherwise returns
list of attachments (may be empty).

return: bool|array of stdClass

Class: workshop_example_assessment  - X-Ref

Represents a renderable training assessment of an example submission

validate_raw_record(stdClass $record)   X-Ref


Class: workshop_example_reference_assessment  - X-Ref

Represents a renderable reference assessment of an example submission

validate_raw_record(stdClass $record)   X-Ref


Class: workshop_message  - X-Ref

Renderable message to be displayed to the user

Message can contain an optional action link with a label that is supposed to be rendered
as a button or a link.

__construct($text = null, $type = self::TYPE_INFO)   X-Ref

param: string $text short text to be displayed
param: string $type optional message type info|ok|error

set_text($text)   X-Ref
Sets the message text

param: string $text short text to be displayed

set_type($type = self::TYPE_INFO)   X-Ref
Sets the message type

param: int $type

set_action(moodle_url $url, $label)   X-Ref
Sets the optional message action

param: moodle_url $url to follow on action
param: string $label action label

get_message()   X-Ref
Returns message text with HTML tags quoted

return: string

get_type()   X-Ref
Returns message type

return: int

get_action_url()   X-Ref
Returns action URL

return: moodle_url|null

get_action_label()   X-Ref
Returns action label

return: string

Class: workshop_grading_report  - X-Ref

Renderable component containing all the data needed to display the grading report

__construct(stdClass $data, stdClass $options)   X-Ref
Grades in $data must be already rounded to the set number of decimals or must be null
(in which later case, the [mod_workshop,nullgrade] string shall be displayed)

param: stdClass $data prepared by {@link workshop::prepare_grading_report_data()}
param: stdClass $options display options (showauthornames, showreviewernames, sortby, sorthow, showsubmissiongrade, showgradinggrade)

get_data()   X-Ref

return: stdClass grading report data

get_options()   X-Ref

return: stdClass rendering options

export_data_for_external()   X-Ref
Prepare the data to be exported to a external system via Web Services.

This function applies extra capabilities checks.
return: stdClass the data ready for external systems

Class: workshop_feedback  - X-Ref

Base class for renderable feedback for author and feedback for reviewer

get_provider()   X-Ref

return: stdClass the user info

get_content()   X-Ref

return: string the feedback text

get_format()   X-Ref

return: int format of the feedback text

Class: workshop_feedback_author  - X-Ref

Renderable feedback for the author of submission

__construct(stdClass $submission)   X-Ref
Extracts feedback from the given submission record

param: stdClass $submission record as returned by {@see self::get_submission_by_id()}

Class: workshop_feedback_reviewer  - X-Ref

Renderable feedback for the reviewer

__construct(stdClass $assessment)   X-Ref
Extracts feedback from the given assessment record

param: stdClass $assessment record as returned by eg {@see self::get_assessment_by_id()}

Class: workshop_final_grades  - X-Ref

Holds the final grades for the activity as are stored in the gradebook