Search moodle.org's
Developer Documentation

See Release Notes
Long Term Support Release

  • Bug fixes for general core bugs in 4.1.x will end 13 November 2023 (12 months).
  • Bug fixes for security issues in 4.1.x will end 10 November 2025 (36 months).
  • PHP version: minimum PHP 7.4.0 Note: minimum PHP version has increased since Moodle 4.0. PHP 8.0.x is supported too.

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

Lesson external API

Copyright: 2017 Juan Leyva <juan@moodle.com>
License: http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
File Size: 2034 lines (87 kb)
Included or required:0 times
Referenced: 0 times
Includes or requires: 0 files

Defines 1 class

mod_lesson_external:: (60 methods):
  get_lesson_summary_for_exporter()
  get_lessons_by_courses_parameters()
  get_lessons_by_courses()
  get_lessons_by_courses_returns()
  validate_lesson()
  validate_attempt()
  get_lesson_access_information_parameters()
  get_lesson_access_information()
  get_lesson_access_information_returns()
  view_lesson_parameters()
  view_lesson()
  view_lesson_returns()
  check_can_view_user_data()
  get_questions_attempts_parameters()
  get_questions_attempts()
  get_questions_attempts_returns()
  get_user_grade_parameters()
  get_user_grade()
  get_user_grade_returns()
  get_user_attempt_grade_structure()
  get_user_attempt_grade_parameters()
  get_user_attempt_grade()
  get_user_attempt_grade_returns()
  get_content_pages_viewed_parameters()
  get_content_pages_viewed()
  get_content_pages_viewed_returns()
  get_user_timers_parameters()
  get_user_timers()
  get_user_timers_returns()
  get_page_structure()
  get_page_fields()
  get_pages_parameters()
  get_pages()
  get_pages_returns()
  launch_attempt_parameters()
  format_lesson_messages()
  external_messages()
  launch_attempt()
  launch_attempt_returns()
  get_page_data_parameters()
  get_page_data()
  get_page_data_returns()
  process_page_parameters()
  process_page()
  process_page_returns()
  finish_attempt_parameters()
  finish_attempt()
  finish_attempt_returns()
  get_attempts_overview_parameters()
  get_attempts_overview()
  get_attempts_overview_returns()
  get_user_attempt_parameters()
  get_user_attempt()
  get_user_attempt_returns()
  get_pages_possible_jumps_parameters()
  get_pages_possible_jumps()
  get_pages_possible_jumps_returns()
  get_lesson_parameters()
  get_lesson()
  get_lesson_returns()


Class: mod_lesson_external  - X-Ref

Lesson external functions

get_lesson_summary_for_exporter($lessonrecord, $password = '')   X-Ref
Return a lesson record ready for being exported.

param: stdClass $lessonrecord lesson record
param: string $password       lesson password
return: stdClass the lesson record ready for exporting.

get_lessons_by_courses_parameters()   X-Ref
Describes the parameters for get_lessons_by_courses.

return: external_function_parameters

get_lessons_by_courses($courseids = array()   X-Ref
Returns a list of lessons in a provided list of courses,
if no list is provided all lessons that the user can view will be returned.

param: array $courseids Array of course ids
return: array of lessons details

get_lessons_by_courses_returns()   X-Ref
Describes the get_lessons_by_courses return value.

return: external_single_structure

validate_lesson($lessonid)   X-Ref
Utility function for validating a lesson.

param: int $lessonid lesson instance id
return: array array containing the lesson, course, context and course module objects

validate_attempt(lesson $lesson, $params, $return = false)   X-Ref
Validates a new attempt.

param: lesson  $lesson lesson instance
param: array   $params request parameters
param: boolean $return whether to return the errors or throw exceptions
return: array          the errors (if return set to true)

get_lesson_access_information_parameters()   X-Ref
Describes the parameters for get_lesson_access_information.

return: external_function_parameters

get_lesson_access_information($lessonid)   X-Ref
Return access information for a given lesson.

param: int $lessonid lesson instance id
return: array of warnings and the access information

get_lesson_access_information_returns()   X-Ref
Describes the get_lesson_access_information return value.

return: external_single_structure

view_lesson_parameters()   X-Ref
Describes the parameters for view_lesson.

return: external_function_parameters

view_lesson($lessonid, $password = '')   X-Ref
Trigger the course module viewed event and update the module completion status.

param: int $lessonid lesson instance id
param: string $password optional password (the lesson may be protected)
return: array of warnings and status result

view_lesson_returns()   X-Ref
Describes the view_lesson return value.

return: external_single_structure

check_can_view_user_data($userid, $course, $cm, $context)   X-Ref
Check if the current user can retrieve lesson information (grades, attempts) about the given user.

param: int $userid the user to check
param: stdClass $course course object
param: stdClass $cm cm object
param: stdClass $context context object

get_questions_attempts_parameters()   X-Ref
Describes the parameters for get_questions_attempts.

return: external_function_parameters

get_questions_attempts($lessonid, $attempt, $correct = false, $pageid = null, $userid = null)   X-Ref
Return the list of page question attempts in a given lesson.

param: int $lessonid lesson instance id
param: int $attempt the lesson attempt number
param: bool $correct only fetch correct attempts
param: int $pageid only fetch attempts at the given page
param: int $userid only fetch attempts of the given user
return: array of warnings and page attempts

get_questions_attempts_returns()   X-Ref
Describes the get_questions_attempts return value.

return: external_single_structure

get_user_grade_parameters()   X-Ref
Describes the parameters for get_user_grade.

return: external_function_parameters

get_user_grade($lessonid, $userid = null)   X-Ref
Return the final grade in the lesson for the given user.

param: int $lessonid lesson instance id
param: int $userid only fetch grades of this user
return: array of warnings and page attempts

get_user_grade_returns()   X-Ref
Describes the get_user_grade return value.

return: external_single_structure

get_user_attempt_grade_structure($required = VALUE_REQUIRED)   X-Ref
Describes an attempt grade structure.

param: int $required if the structure is required or optional
return: external_single_structure the structure

get_user_attempt_grade_parameters()   X-Ref
Describes the parameters for get_user_attempt_grade.

return: external_function_parameters

get_user_attempt_grade($lessonid, $lessonattempt, $userid = null)   X-Ref
Return grade information in the attempt for a given user.

param: int $lessonid lesson instance id
param: int $lessonattempt lesson attempt number
param: int $userid only fetch attempts of the given user
return: array of warnings and page attempts

get_user_attempt_grade_returns()   X-Ref
Describes the get_user_attempt_grade return value.

return: external_single_structure

get_content_pages_viewed_parameters()   X-Ref
Describes the parameters for get_content_pages_viewed.

return: external_function_parameters

get_content_pages_viewed($lessonid, $lessonattempt, $userid = null)   X-Ref
Return the list of content pages viewed by a user during a lesson attempt.

param: int $lessonid lesson instance id
param: int $lessonattempt lesson attempt number
param: int $userid only fetch attempts of the given user
return: array of warnings and page attempts

get_content_pages_viewed_returns()   X-Ref
Describes the get_content_pages_viewed return value.

return: external_single_structure

get_user_timers_parameters()   X-Ref
Describes the parameters for get_user_timers.

return: external_function_parameters

get_user_timers($lessonid, $userid = null)   X-Ref
Return the timers in the current lesson for the given user.

param: int $lessonid lesson instance id
param: int $userid only fetch timers of the given user
return: array of warnings and timers

get_user_timers_returns()   X-Ref
Describes the get_user_timers return value.

return: external_single_structure

get_page_structure($required = VALUE_REQUIRED)   X-Ref
Describes the external structure for a lesson page.

return: external_single_structure

get_page_fields(lesson_page $page, $returncontents = false)   X-Ref
Returns the fields of a page object

param: lesson_page $page the lesson page
param: bool $returncontents whether to return the page title and contents
return: stdClass          the fields matching the external page structure

get_pages_parameters()   X-Ref
Describes the parameters for get_pages.

return: external_function_parameters

get_pages($lessonid, $password = '')   X-Ref
Return the list of pages in a lesson (based on the user permissions).

param: int $lessonid lesson instance id
param: string $password optional password (the lesson may be protected)
return: array of warnings and status result

get_pages_returns()   X-Ref
Describes the get_pages return value.

return: external_single_structure

launch_attempt_parameters()   X-Ref
Describes the parameters for launch_attempt.

return: external_function_parameters

format_lesson_messages($lesson)   X-Ref
Return lesson messages formatted according the external_messages structure

param: lesson $lesson lesson instance
return: array          messages formatted

external_messages()   X-Ref
Return a external structure representing messages.

return: external_multiple_structure messages structure

launch_attempt($lessonid, $password = '', $pageid = 0, $review = false)   X-Ref
Starts a new attempt or continues an existing one.

param: int $lessonid lesson instance id
param: string $password optional password (the lesson may be protected)
param: int $pageid page id to continue from (only when continuing an attempt)
param: bool $review if we want to review just after finishing
return: array of warnings and status result

launch_attempt_returns()   X-Ref
Describes the launch_attempt return value.

return: external_single_structure

get_page_data_parameters()   X-Ref
Describes the parameters for get_page_data.

return: external_function_parameters

get_page_data($lessonid, $pageid, $password = '', $review = false, $returncontents = false)   X-Ref
Return information of a given page, including its contents.

param: int $lessonid lesson instance id
param: int $pageid page id
param: string $password optional password (the lesson may be protected)
param: bool $review if we want to review just after finishing (1 hour margin)
param: bool $returncontents if we must return the complete page contents once rendered
return: array of warnings and status result

get_page_data_returns()   X-Ref
Describes the get_page_data return value.

return: external_single_structure

process_page_parameters()   X-Ref
Describes the parameters for process_page.

return: external_function_parameters

process_page($lessonid, $pageid, $data, $password = '', $review = false)   X-Ref
Processes page responses

param: int $lessonid lesson instance id
param: int $pageid page id
param: array $data the data to be saved
param: string $password optional password (the lesson may be protected)
param: bool $review if we want to review just after finishing (1 hour margin)
return: array of warnings and status result

process_page_returns()   X-Ref
Describes the process_page return value.

return: external_single_structure

finish_attempt_parameters()   X-Ref
Describes the parameters for finish_attempt.

return: external_function_parameters

finish_attempt($lessonid, $password = '', $outoftime = false, $review = false)   X-Ref
Finishes the current attempt.

param: int $lessonid lesson instance id
param: string $password optional password (the lesson may be protected)
param: bool $outoftime optional if the user run out of time
param: bool $review if we want to review just after finishing (1 hour margin)
return: array of warnings and information about the finished attempt

finish_attempt_returns()   X-Ref
Describes the finish_attempt return value.

return: external_single_structure

get_attempts_overview_parameters()   X-Ref
Describes the parameters for get_attempts_overview.

return: external_function_parameters

get_attempts_overview($lessonid, $groupid = 0)   X-Ref
Get a list of all the attempts made by users in a lesson.

param: int $lessonid lesson instance id
param: int $groupid group id, 0 means that the function will determine the user group
return: array of warnings and status result

get_attempts_overview_returns()   X-Ref
Describes the get_attempts_overview return value.

return: external_single_structure

get_user_attempt_parameters()   X-Ref
Describes the parameters for get_user_attempt.

return: external_function_parameters

get_user_attempt($lessonid, $userid, $lessonattempt)   X-Ref
Return information about the given user attempt (including answers).

param: int $lessonid lesson instance id
param: int $userid the user id
param: int $lessonattempt the attempt number
return: array of warnings and page attempts

get_user_attempt_returns()   X-Ref
Describes the get_user_attempt return value.

return: external_single_structure

get_pages_possible_jumps_parameters()   X-Ref
Describes the parameters for get_pages_possible_jumps.

return: external_function_parameters

get_pages_possible_jumps($lessonid)   X-Ref
Return all the possible jumps for the pages in a given lesson.

You may expect different results on consecutive executions due to the random nature of the lesson module.

param: int $lessonid lesson instance id
return: array of warnings and possible jumps

get_pages_possible_jumps_returns()   X-Ref
Describes the get_pages_possible_jumps return value.

return: external_single_structure

get_lesson_parameters()   X-Ref
Describes the parameters for get_lesson.

return: external_function_parameters

get_lesson($lessonid, $password = '')   X-Ref
Return information of a given lesson.

param: int $lessonid lesson instance id
param: string $password optional password (the lesson may be protected)
return: array of warnings and status result

get_lesson_returns()   X-Ref
Describes the get_lesson return value.

return: external_single_structure