Proposal: filters to change how course content is shown to a learner on each request

Open
#420 2 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
30/100
Issue type
Feature
Clarity
Clearly specified
Activity status
Active
Tech stack
python
Domain
api, backend

Research direction

This is a design proposal spanning openedx-filters and openedx-platform, with related pull requests openedx/openedx-filters#410 and openedx/openedx-platform#39269 and a proof of concept at mitodl/open-edx-plugins#917. Start by reviewing those pull requests and the proposed filter triggers, especially how learner-specific changes avoid shared caches and grading data. Done means maintainers agree on the filter design and the required implementation scope.

Written by the indexing model from the issue text.

Description

Use case

A plugin sometimes needs to change how course content is shown to one learner, without changing the course itself: for example cohort-specific wording, accessibility adjustments to block text, or showing course content in the learner's language. The course in the modulestore, the shared caches and grading should keep the original content.

Our case (MIT Open Learning) is the last one: a learner reads a course in their own language without moving to a separate translated copy, so enrollment, progress and grades stay on one course. Our proof of concept keeps the translated text in a plugin table and swaps it in when content is shown to the learner.

Why the current filters are not enough

The content filters today run at render time only (VerticalBlockChildRenderStarted, RenderXBlockStarted, VerticalBlockRenderCompleted). A change made there is lost as soon as the learner:

  • uses the block: XBlock handler calls (problem Submit, Reset, Show Answer, hints, ORA steps) load the block again without these filters;
  • moves around the course: unit titles come from sequence metadata, and the outline, sidebar, breadcrumbs, dates and progress pages are built from cached data;
  • opens course pages: custom pages, handouts, updates and about sections.
Proposed filters
Filter Type Arguments Runs
LearnerXBlockBound org.openedx.learning.xblock.bound.v1 block, user, course_key Each time the LMS binds a block to a learner (get_block_for_descriptor), after the access check: unit children, library and conditional children, handler calls, sequence metadata, course pages
CourseOutlineAPIRenderStarted org.openedx.learning.course_outline.api.render.started.v1 course_key, user, data Serialized learning_sequences outline (breadcrumbs, "next up")
CourseHomeMetadataAPIRenderStarted org.openedx.learning.course_home_metadata.api.render.started.v1 course_key, user, data Course home metadata (course title, tab names)
CoursewareMetadataAPIRenderStarted org.openedx.learning.courseware_metadata.api.render.started.v1 course_key, user, data Courseware metadata (course name)
CourseHomeProgressAPIRenderStarted org.openedx.learning.course_home_progress.api.render.started.v1 course_key, user, data Progress tab
CourseHomeDatesAPIRenderStarted org.openedx.learning.course_home_dates.api.render.started.v1 course_key, user, data Dates tab
CourseHomeOutlineAPIRenderStarted org.openedx.learning.course_home_outline.api.render.started.v1 course_key, user, data Course home outline tab (blocks, dates widget)
CourseNavigationAPIRenderStarted org.openedx.learning.course_navigation.api.render.started.v1 course_key, user, data Courseware navigation sidebar

For the response filters, user is the learner the response is built for, also when staff view it or masquerade.

Design choices we would like feedback on
  • Responses, not the block structure. We first added a filter on the learner's transformed block structure (get_course_blocks), but grading reads that structure too, so a change there could reach grades. We dropped it: the response filters run on serialized data after the platform's caches, so cached and graded data keep the original values.
  • Serialized data only for the outline: the outline objects are cached and shared.
  • When the bind filter runs: once per block and learner; again when the same instance is bound to another learner, after a bind for an unknown user (block structure collection), and on every anonymous bind (each one clears user-scoped fields). It does not run for unknown users, so shared course data is never built from changed blocks. With no pipeline configured, run_pipeline returns at once.
  • One bind filter vs narrower ones: one filter at the bind point covers every load path with one call site. We are open to splitting it into per-view filters if maintainers prefer.
  • One filter per API vs a generic one: we followed the existing one-filter-per-trigger pattern; a single "course API response" filter with a view name argument is an alternative.
Implementation

No change in behaviour unless a pipeline step is configured. We are happy to rename, split or narrow any of these based on feedback.

Dominant language
Python
Stars
10
Forks
30
Avg merge
5h 49m
Merged PRs (30d)
5

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from openedx/openedx-filters

All issues in openedx/openedx-filters

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.