Tsugi

LessonsService
in package

Table of Contents

Properties

$anchor  : mixed
$lessons  : mixed
All the lessons
$module  : mixed
The individual module
$position  : mixed
$resource_links  : mixed
Index by resource_link
$toolHome  : mixed
Mounted lessons path (e.g. /lessons or /courses/2/lessons).
$lessonModuleDueDatesForBadges  : array<string|int, mixed>
$lessonModuleGradesForBadges  : array<string|int, mixed>
$lessonsViewerIsInstructor  : bool|null
$linkPublished  : array<string, bool>|null
link_key => published. Null until loaded. A missing key means there is no link row.
$quiz1IdSet  : array<int, bool>|null
Quiz1 id => published. Null until loaded. Missing id means the quiz is not in this course.
$throwOnError  : mixed
When true, structural errors throw InvalidArgumentException instead of dying.

Methods

__construct()  : mixed
absolute_url_ref()  : mixed
adjustArray()  : mixed
Make non-array into an array and adjust paths
applyDiscussionOrder()  : array<int, object>
Sort flattened discussion objects by a resource_link_id order list.
assignmentsDueBadgeModifier()  : mixed
courseStepsOn()  : mixed
The course document's own flag. Missing means on.
domIdForResourceLink()  : string
Stable DOM id for an LTI resource link (assignments page jump targets → module list).
enumerateLtiAssignmentItems()  : array<string|int, array<string|int, mixed>>
LTI assignment rows for the same modules shown on the assignments list (items array or legacy lti).
enumerateQuizDueItems()  : array<string|int, array<string|int, mixed>>
Native Quiz1 rows for the home due list and calendar.
expandLink()  : mixed
flattenedDiscussions()  : array<int, object>
Catalog discussions: top-level, then module items, then optional discussion_order.
fromJson()  : mixed
Build a LessonsService object from a JSON string (file or manifest document).
getCustomWithInherit()  : mixed
Check if a setting value is in a resource in a Lesson
getItemByContentId()  : object|null
Lesson item that points at an lti_content row.
getLaunches()  : array<int, object>
Course-level launches from lessons JSON (top-level "launches" array).
getLtiByRlid()  : mixed
Get an LTI or Discussion associated with a resource link ID
getModuleByAnchor()  : mixed
Get a module associated with an anchor
getModuleByContentId()  : object|null
Module that contains a content launch.
getModuleByRlid()  : mixed
getSetting()  : mixed
get a setting for the lesson
getUrlResources()  : mixed
isEmpty()  : mixed
True when there is no visible Lessons outline (new course, or all modules hidden).
isSingle()  : mixed
Indicate we are in a single lesson
kalturaEmbedUrl()  : string|null
Build a Kaltura iframe embed URL (kaltura_embed extension).
kalturaTabUrl()  : string|null
Build a Kaltura "open in new tab" URL (kaltura_tab playlist template).
kalturaUrlFromExtension()  : string|null
Expand a Kaltura URL template extension with lessons.json kaltura_id.
lessonsHome()  : mixed
Mounted lessons path: /lessons or /courses/{id}/lessons.
lessonsLaunchPath()  : mixed
LTI launch URL for a lessons resource_link_id (sibling _launch route).
lessonsViewerIsInstructor()  : bool
ltiLaunchIsGraded()  : bool
Whether this lessons LTI item is graded (counts toward rollups, assignments list, badges).
makeUrlResource()  : mixed
moduleHasLtiDueDateInContext()  : mixed
True if any LTI in this module has end_datetime set in the current context.
moduleLtiProgressPoints()  : array{0: float, 1: float, 2: string[]}
Graded-link totals for module progress (items array, else legacy lti).
moduleProgressDueDates()  : array<string, array<string, mixed>>
moduleProgressGrades()  : array<string, float>
moduleWorstDueRollup()  : array{modifier: string, end: string, date_disp: string}|null
Worst due state among module LTI items that have an end_datetime (tie: earlier due wins).
quiz1ExistsInCourse()  : bool
quiz1IsPublished()  : bool
True when the quiz has a published launch link. Never-published and unpublished are false.
quiz1LinkId()  : int
Resource link id for a published quiz, or 0.
resourceLinkIdLetterPrefix()  : mixed
First $count letters from $resource_link_id (ignoring non-letters; lowercase).
resourceLinkPublished()  : bool|null
True or false when this course has a link for that resource link id.
resultLinkSignature()  : mixed
Per-result signature for assignments: py345_61 from rlid + lti_link.link_id.
setModuleProgressContext()  : mixed
Grades and due dates for progress badges while one module is rendered.
shouldShowAssignmentResultSignature()  : mixed
Whether to show the per-result signature on an assignments row (instructors only).
shouldShowGradesResultSignature()  : mixed
Whether to show the result signature on a grade book row.
stepsEnabled()  : mixed
Student step checkboxes on ungraded lesson items.
stepsFlag()  : mixed
tryFromJson()  : LessonsService|string
Load JSON without killing the request.
urlLooksLikePdf()  : mixed
Whether a URL path ends in .pdf (after expandLink-friendly strings).
videoUrlForItem()  : string|null
Preferred public URL for a lesson video item.
adjustItemsEntryUrls()  : mixed
Apply absolute_url_ref to launch/href/url on one items-array entry and nested item lists.
assignmentDue()  : string
Due day stored on the lesson item, before a link exists.
collectQuizDueItems()  : mixed
contentAssignmentRow()  : array{title: string, resource_link_id: string, graded: bool}|null
A lesson item that points at lti_content. The grade column's resource link id lives on that row. Graded when the launch may return a grade or the column already exists.
dueModifierWorstRank()  : mixed
Higher = worse urgency for module rollup (matches per-assignment badge modifiers).
fail()  : mixed
Fail a document load: throw when validating, otherwise die.
gradedProgressLinkId()  : string|null
Resource link id for one gradable lesson item, or null when it does not count.
lessonsCourseBaseUrl()  : string
Course mount for expanding /files and /pages hrefs (not site apphome alone).
loadLinkPublication()  : mixed
loadQuiz1Publication()  : mixed
resourceLinkHasDueDateInContext()  : mixed
True when this resource link has end_datetime set for the current context (matches due badge rows).

Properties

Index by resource_link

public mixed $resource_links

$toolHome

Mounted lessons path (e.g. /lessons or /courses/2/lessons).

public mixed $toolHome = ''

Set by the Lessons controller; otherwise derived from REQUEST_URI.

$lessonModuleDueDatesForBadges

private array<string|int, mixed> $lessonModuleDueDatesForBadges = array()

Due rows by link_key from GradeUtil::loadDueDatesForDisplay

$lessonModuleGradesForBadges

private array<string|int, mixed> $lessonModuleGradesForBadges = array()

Grades by resource_link_id for due badges on single-module view

$lessonsViewerIsInstructor

private bool|null $lessonsViewerIsInstructor = null

$linkPublished

link_key => published. Null until loaded. A missing key means there is no link row.

private array<string, bool>|null $linkPublished = null

$quiz1IdSet

Quiz1 id => published. Null until loaded. Missing id means the quiz is not in this course.

private array<int, bool>|null $quiz1IdSet = null

$throwOnError

When true, structural errors throw InvalidArgumentException instead of dying.

private static mixed $throwOnError = false

Used by tryFromJson() so authoring can refuse a bad save.

Methods

__construct()

public __construct([mixed $name = 'lessons.json' ][, mixed $anchor = null ][, mixed $index = null ]) : mixed
Parameters
$name : mixed = 'lessons.json'
$anchor : mixed = null
$index : mixed = null

absolute_url_ref()

public static absolute_url_ref(mixed &$url) : mixed
Parameters
$url : mixed

adjustArray()

Make non-array into an array and adjust paths

public static adjustArray(mixed &$entry) : mixed
Parameters
$entry : mixed

applyDiscussionOrder()

Sort flattened discussion objects by a resource_link_id order list.

public static applyDiscussionOrder(array<int, object> $discussions, array<int, mixed> $order) : array<int, object>
Parameters
$discussions : array<int, object>
$order : array<int, mixed>
Return values
array<int, object>

assignmentsDueBadgeModifier()

public static assignmentsDueBadgeModifier(mixed $resource_link_id, mixed $end, mixed $allgrades) : mixed
Parameters
$resource_link_id : mixed
$end : mixed
$allgrades : mixed

courseStepsOn()

The course document's own flag. Missing means on.

public courseStepsOn() : mixed

Stable DOM id for an LTI resource link (assignments page jump targets → module list).

public static domIdForResourceLink(string $resource_link_id) : string
Parameters
$resource_link_id : string
Return values
string —

HTML id attribute value

enumerateLtiAssignmentItems()

LTI assignment rows for the same modules shown on the assignments list (items array or legacy lti).

public enumerateLtiAssignmentItems([bool $for_due_date_management = false ]) : array<string|int, array<string|int, mixed>>
Parameters
$for_due_date_management : bool = false

When true, omit items with "result": false (ungraded launches are not managed for due dates).

Return values
array<string|int, array<string|int, mixed>> —

Each element: module_index, module_title, module_anchor, item_title, resource_link_id, participates_in_grades (same as ltiLaunchIsGraded())

enumerateQuizDueItems()

Native Quiz1 rows for the home due list and calendar.

public enumerateQuizDueItems() : array<string|int, array<string|int, mixed>>

Same shape as enumerateLtiAssignmentItems(). A student does not see an unpublished quiz.

Return values
array<string|int, array<string|int, mixed>>
public static expandLink(mixed $url) : mixed
Parameters
$url : mixed

flattenedDiscussions()

Catalog discussions: top-level, then module items, then optional discussion_order.

public flattenedDiscussions() : array<int, object>
Return values
array<int, object>

fromJson()

Build a LessonsService object from a JSON string (file or manifest document).

public static fromJson(mixed $json_str[, mixed $anchor = null ][, mixed $index = null ]) : mixed
Parameters
$json_str : mixed
$anchor : mixed = null
$index : mixed = null

getCustomWithInherit()

Check if a setting value is in a resource in a Lesson

public getCustomWithInherit(mixed $key[, mixed $rlid = false ]) : mixed

This solves the problems that (a) most LMS systems do not handle custom well for Common Cartridge Imports and (b) some systems do not handle custom at all when links are installed via ContentItem. Canvas has this problem for sure and others might as well.

The solution is to add the resource link from the Lesson as a GET parameter on the launchurl URL to be a fallback:

https://../mod/zap/?inherit=assn03

Say the tool has custom key of "exercise" that it wants a default for when the tool has not yet been configured. First we check if the LMS sent us a custom parameter and use it if present.

If not, load up the LTI launch for the resource link id (assn03) in the above example and see if there is a custom parameter set in that launch and assume it was passed to us.

Sample call:

$assn = Settings::linkGet('exercise');
if ( ! $assn || ! isset($assignments[$assn]) ) {
    $rlid = isset($_GET['inherit']) ? $_GET['inherit'] : false;
    if ( $rlid && isset($CFG->lessons) ) {
        $l = new LessonsService($CFG->lessons);
        $assn = $l->getCustomWithInherit($rlid, 'exercise');
    } else {
        $assn = LTIX::ltiCustomGet('exercise');
    }
    Settings::linkSet('exercise', $assn);
}
Parameters
$key : mixed
$rlid : mixed = false

getItemByContentId()

Lesson item that points at an lti_content row.

public getItemByContentId(int $contentId) : object|null
Parameters
$contentId : int
Return values
object|null

getLaunches()

Course-level launches from lessons JSON (top-level "launches" array).

public getLaunches() : array<int, object>
Return values
array<int, object> —

List of launch objects (type, title, launch URL, resource_link_id, etc.)

getLtiByRlid()

Get an LTI or Discussion associated with a resource link ID

public getLtiByRlid(mixed $resource_link_id) : mixed
Parameters
$resource_link_id : mixed

getModuleByAnchor()

Get a module associated with an anchor

public getModuleByAnchor(mixed $anchor) : mixed
Parameters
$anchor : mixed

getModuleByContentId()

Module that contains a content launch.

public getModuleByContentId(int $contentId) : object|null
Parameters
$contentId : int
Return values
object|null

getModuleByRlid()

public getModuleByRlid(mixed $resource_link_id) : mixed
Parameters
$resource_link_id : mixed

getSetting()

get a setting for the lesson

public getSetting(mixed $key[, mixed $default = false ]) : mixed
Parameters
$key : mixed
$default : mixed = false

getUrlResources()

public static getUrlResources(mixed $module) : mixed
Parameters
$module : mixed

isEmpty()

True when there is no visible Lessons outline (new course, or all modules hidden).

public isEmpty() : mixed

isSingle()

Indicate we are in a single lesson

public isSingle() : mixed

kalturaEmbedUrl()

Build a Kaltura iframe embed URL (kaltura_embed extension).

public static kalturaEmbedUrl(mixed $item) : string|null
Parameters
$item : mixed
Return values
string|null —

Absolute embed URL, or null if unavailable

kalturaTabUrl()

Build a Kaltura "open in new tab" URL (kaltura_tab playlist template).

public static kalturaTabUrl(mixed $item) : string|null

Falls back to the embed URL when kaltura_tab is not set.

Parameters
$item : mixed
Return values
string|null —

Absolute tab URL, or null if unavailable

kalturaUrlFromExtension()

Expand a Kaltura URL template extension with lessons.json kaltura_id.

public static kalturaUrlFromExtension(mixed $item, mixed $extension_key) : string|null

The template must include a literal {id} placeholder.

Parameters
$item : mixed
$extension_key : mixed
Return values
string|null —

Absolute URL, or null if unavailable

lessonsHome()

Mounted lessons path: /lessons or /courses/{id}/lessons.

public lessonsHome() : mixed

lessonsLaunchPath()

LTI launch URL for a lessons resource_link_id (sibling _launch route).

public lessonsLaunchPath(mixed $resource_link_id) : mixed
Parameters
$resource_link_id : mixed

lessonsViewerIsInstructor()

public lessonsViewerIsInstructor() : bool
Return values
bool

ltiLaunchIsGraded()

Whether this lessons LTI item is graded (counts toward rollups, assignments list, badges).

public static ltiLaunchIsGraded(object|null $lti_item) : bool

JSON "result": false means ungraded; if result is omitted, the launch is treated as graded.

Parameters
$lti_item : object|null

Item with type lti, or legacy module lti object

Return values
bool —

true if graded; false if explicitly ungraded

makeUrlResource()

public static makeUrlResource(mixed $type, mixed $title, mixed $url) : mixed
Parameters
$type : mixed
$title : mixed
$url : mixed

moduleHasLtiDueDateInContext()

True if any LTI in this module has end_datetime set in the current context.

public moduleHasLtiDueDateInContext(array<string|int, string> $rlids, array<string, array<string, mixed>> $duedates) : mixed
Parameters
$rlids : array<string|int, string>
$duedates : array<string, array<string, mixed>>

moduleLtiProgressPoints()

Graded-link totals for module progress (items array, else legacy lti).

public moduleLtiProgressPoints(mixed $module, mixed $allgrades, array<string, array<string, mixed>> $duedates_for_display) : array{0: float, 1: float, 2: string[]}

A published quiz counts, the same as a graded LTI launch or a content row that can return a grade. Discussions, files, and pages do not. When $duedates_for_display is non-empty (GradeUtil::loadDueDatesForDisplay), only resource links with a non-empty end_datetime in the current context are counted (due-date mode). When it is empty (no course due dates, or the learner has hidden due dates), every graded link in the module counts so percent-complete badges still work. LTI entries with "result": false are excluded from points, actuals, and rollup rlids.

Parameters
$module : mixed
$allgrades : mixed
$duedates_for_display : array<string, array<string, mixed>>
Return values
array{0: float, 1: float, 2: string[]} —

possible points, actual points, resource_link_ids

moduleProgressDueDates()

public moduleProgressDueDates() : array<string, array<string, mixed>>
Return values
array<string, array<string, mixed>>

moduleProgressGrades()

public moduleProgressGrades() : array<string, float>
Return values
array<string, float>

moduleWorstDueRollup()

Worst due state among module LTI items that have an end_datetime (tie: earlier due wins).

public moduleWorstDueRollup(array<string|int, string> $rlids, array<string, float> $allgrades, array<string, array<string, mixed>> $duedates) : array{modifier: string, end: string, date_disp: string}|null
Parameters
$rlids : array<string|int, string>
$allgrades : array<string, float>
$duedates : array<string, array<string, mixed>>
Return values
array{modifier: string, end: string, date_disp: string}|null

quiz1ExistsInCourse()

public quiz1ExistsInCourse(mixed $quiz_id) : bool
Parameters
$quiz_id : mixed
Return values
bool

quiz1IsPublished()

True when the quiz has a published launch link. Never-published and unpublished are false.

public quiz1IsPublished(mixed $quiz_id) : bool
Parameters
$quiz_id : mixed
Return values
bool

quiz1LinkId()

Resource link id for a published quiz, or 0.

public quiz1LinkId(mixed $quiz_id) : int
Parameters
$quiz_id : mixed
Return values
int

resourceLinkIdLetterPrefix()

First $count letters from $resource_link_id (ignoring non-letters; lowercase).

public static resourceLinkIdLetterPrefix(mixed $resource_link_id[, mixed $count = 2 ]) : mixed
Parameters
$resource_link_id : mixed
$count : mixed = 2

resourceLinkPublished()

True or false when this course has a link for that resource link id.

public resourceLinkPublished(mixed $resource_link_id) : bool|null

Null means there is no row yet, so an older lesson item stays visible.

Parameters
$resource_link_id : mixed
Return values
bool|null

resultLinkSignature()

Per-result signature for assignments: py345_61 from rlid + lti_link.link_id.

public static resultLinkSignature(mixed $resource_link_id, mixed $link_id) : mixed
Parameters
$resource_link_id : mixed
$link_id : mixed

setModuleProgressContext()

Grades and due dates for progress badges while one module is rendered.

public setModuleProgressContext(array<string, float> $grades, array<string, array<string, mixed>> $duedates) : mixed

The lessons controller sets this before item HTML reads it.

Parameters
$grades : array<string, float>
$duedates : array<string, array<string, mixed>>

shouldShowAssignmentResultSignature()

Whether to show the per-result signature on an assignments row (instructors only).

public static shouldShowAssignmentResultSignature(mixed $resource_link_id, array<string, float> $allgrades, array<string, int> $alllinkids, mixed $is_instructor) : mixed
Parameters
$resource_link_id : mixed
$allgrades : array<string, float>
$alllinkids : array<string, int>
$is_instructor : mixed

shouldShowGradesResultSignature()

Whether to show the result signature on a grade book row.

public static shouldShowGradesResultSignature(mixed $resource_link_id, float|int|string|null $grade, mixed $is_instructor) : mixed
Parameters
$resource_link_id : mixed
$grade : float|int|string|null

Raw grade (0.0–1.0)

$is_instructor : mixed

stepsEnabled()

Student step checkboxes on ungraded lesson items.

public stepsEnabled() : mixed

Missing means on. "steps": false in the lessons document turns them off. The same key is the course manifest and a file-based lessons.json.

stepsFlag()

public static stepsFlag(mixed $value) : mixed
Parameters
$value : mixed

tryFromJson()

Load JSON without killing the request.

public static tryFromJson(mixed $json_str[, mixed $anchor = null ][, mixed $index = null ]) : LessonsService|string
Parameters
$json_str : mixed
$anchor : mixed = null
$index : mixed = null
Return values
LessonsService|string —

LessonsService on success, error message on failure

urlLooksLikePdf()

Whether a URL path ends in .pdf (after expandLink-friendly strings).

public static urlLooksLikePdf(mixed $url) : mixed
Parameters
$url : mixed

videoUrlForItem()

Preferred public URL for a lesson video item.

public static videoUrlForItem(mixed $item) : string|null

Prefers Kaltura embed when kaltura_embed + kaltura_id are available.

Parameters
$item : mixed
Return values
string|null

adjustItemsEntryUrls()

Apply absolute_url_ref to launch/href/url on one items-array entry and nested item lists.

private static adjustItemsEntryUrls(mixed $item) : mixed

Matches legacy adjustArray() behavior; expandLink() runs first so existing {apphome}/{wwwroot} stay correct.

Parameters
$item : mixed

assignmentDue()

Due day stored on the lesson item, before a link exists.

private static assignmentDue(object $item) : string
Parameters
$item : object
Return values
string

collectQuizDueItems()

private collectQuizDueItems(array<int, mixed> $items, object $module, mixed $modIndex, bool|null &$instructor, array<int, true> &$seen, array<int, array<string, mixed>> &$list) : mixed
Parameters
$items : array<int, mixed>
$module : object
$modIndex : mixed
$instructor : bool|null
$seen : array<int, true>
$list : array<int, array<string, mixed>>

contentAssignmentRow()

A lesson item that points at lti_content. The grade column's resource link id lives on that row. Graded when the launch may return a grade or the column already exists.

private static contentAssignmentRow(object $item) : array{title: string, resource_link_id: string, graded: bool}|null
Parameters
$item : object
Return values
array{title: string, resource_link_id: string, graded: bool}|null

dueModifierWorstRank()

Higher = worse urgency for module rollup (matches per-assignment badge modifiers).

private dueModifierWorstRank(mixed $mod) : mixed
Parameters
$mod : mixed

fail()

Fail a document load: throw when validating, otherwise die.

private static fail(mixed $msg) : mixed
Parameters
$msg : mixed

gradedProgressLinkId()

Resource link id for one gradable lesson item, or null when it does not count.

private gradedProgressLinkId(mixed $item) : string|null

A published native quiz uses the quiz's grade-book key. An lti_content row counts when it can return a grade. An LTI launch counts unless the lesson marks it ungraded. A discussion is not a grade.

Parameters
$item : mixed
Return values
string|null

lessonsCourseBaseUrl()

Course mount for expanding /files and /pages hrefs (not site apphome alone).

private static lessonsCourseBaseUrl() : string

A site-root /files/download/{sha} link leaves /courses/{id} and restoreSiteLoginContext() looks up the blob in the wrong course.

Return values
string

resourceLinkHasDueDateInContext()

True when this resource link has end_datetime set for the current context (matches due badge rows).

private resourceLinkHasDueDateInContext(mixed $rlid, array<string, array<string, mixed>> $duedates) : mixed
Parameters
$rlid : mixed
$duedates : array<string, array<string, mixed>>

        
On this page

Search results