Skip to content

feat: add flashcards and matching block editors - #3351

Draft
samuelallan72 wants to merge 12 commits into
openedx:masterfrom
open-craft:samuel/flashcards-and-matching
Draft

samuelallan72 wants to merge 12 commits into
openedx:masterfrom
open-craft:samuel/flashcards-and-matching

Conversation

@samuelallan72

@samuelallan72 samuelallan72 commented Nov 9, 2026 •

Copy link
Copy Markdown

Description

Add custom editors for the flashcards and matching blocks. These are new blocks being implemented in openedx/xblocks-core#316 .

screenshots image image image

Supporting information

Private-ref: https://tasks.opencraft.com/browse/BB-11379

Testing instructions

Other information

Depends-on: openedx/xblocks-core#316

Best Practices Checklist

We're trying to move away from some deprecated patterns in this codebase. Please
check if your PR meets these recommendations before asking for a review:

  • Any new files are using TypeScript (.ts, .tsx).
  • Avoid propTypes and defaultProps in any new or modified code.
  • Tests should use the helpers in src/testUtils.tsx (specifically initializeMocks)
  • Do not add new fields to the Redux state/store. Use React Context to share state among multiple components.
  • Use React Query to load data from REST APIs. See any apiHooks.ts in this repo for examples.
  • All new i18n messages in messages.ts files have a description for translators to use.
  • Avoid using ../ in import paths. To import from parent folders, use @src, e.g. import { initializeMocks } from '@src/testUtils'; instead of from '../../../../testUtils'

@openedx-webhooks openedx-webhooks added the open-source-contribution PR author is not from Axim or 2U label Nov 9, 2026
@openedx-webhooks

Copy link
Copy Markdown

Thanks for the pull request, @samuelallan72!

This repository is currently maintained by @bradenmacdonald.

Once you've gone through the following steps feel free to tag them in a comment and let them know that your changes are ready for engineering review.

🔘 Get product approval

If you haven't already, check this list to see if your contribution needs to go through the product review process.

  • If it does, you'll need to submit a product proposal for your contribution, and have it reviewed by the Product Working Group.
    • This process (including the steps you'll need to take) is documented here.
  • If it doesn't, simply proceed with the next step.
🔘 Provide context

To help your reviewers and other members of the community understand the purpose and larger context of your changes, feel free to add as much of the following information to the PR description as you can:

  • Dependencies

    This PR must be merged before / after / at the same time as ...

  • Blockers

    This PR is waiting for OEP-1234 to be accepted.

  • Timeline information

    This PR must be merged by XX date because ...

  • Partner information

    This is for a course on edx.org.

  • Supporting documentation
  • Relevant Open edX discussion forum threads
🔘 Get a green build

If one or more checks are failing, continue working on your changes until this is no longer the case and your build turns green.

🔘 Update the status of your PR

Your PR is currently marked as a draft. After completing the steps above, update its status by clicking "Ready for Review", or removing "WIP" from the title, as appropriate.


Where can I find more information?

If you'd like to get more details on all aspects of the review process for open source pull requests (OSPRs), check out the following resources:

When can I expect my changes to be merged?

Our goal is to get community contributions seen and reviewed as efficiently as possible.

However, the amount of time that it takes to review and merge a PR can vary significantly based on factors such as:

  • The size and impact of the changes that it introduces
  • The need for product review
  • Maintenance status of the parent repository

💡 As a result it may take up to several weeks or months to complete a review and merge your PR.

@samuelallan72 samuelallan72 self-assigned this Nov 9, 2026
@github-project-automation github-project-automation Bot moved this to Needs Triage in Contributions Nov 9, 2026
@samuelallan72
samuelallan72 force-pushed the samuel/flashcards-and-matching branch from e2ee74b to e3c735c Compare November 9, 2026 06:59
@bradenmacdonald

Copy link
Copy Markdown
Contributor

Hi, I'd just like to make you aware that this repo is scheduled to be converted to frontend-base starting this month, and we're trying to hold off on merging any new editors until that has happened and we have a new plugin-based system for adding editors. (And when that's ready, you may not need to merge them here at all, though details are TBD.)

From a quick look, it looks like this editor is implemented using our best practices and is well isolated, so I don't anticipate any issues. But I'm not sure exactly how much will change once we have plugin support. Please let me know if not getting it merged in the next few weeks is going to cause any problems.

@samuelallan72

Copy link
Copy Markdown
Author

Thanks for the heads up @bradenmacdonald 🙂

@Kelketek is this timeline ok for you? (waiting for a few weeks) If so, I'll drop development here and resume once the new plugin system is ready.

@Kelketek

Copy link
Copy Markdown
Contributor

@samuelallan72 I'm OK with that so long as the client version is not held up. We don't have a few weeks margin there. So I'd suggest continuing to work on this and backport it, and then we can see about reconciling post-plugin changes later when upstream is ready.

@samuelallan72

Copy link
Copy Markdown
Author

@Kelketek got it, I'll continue working on this then. 👍

@samuelallan72
samuelallan72 force-pushed the samuel/flashcards-and-matching branch 2 times, most recently from bc85851 to fc0f249 Compare November 10, 2026 04:55
@samuelallan72
samuelallan72 force-pushed the samuel/flashcards-and-matching branch from fc0f249 to 78d93e9 Compare November 10, 2026 05:11
@samuelallan72

Copy link
Copy Markdown
Author

@Kelketek I've prepared the editor for the flashcards component for review. I'm in unfamiliar territory, as I haven't worked with contexts, external react stores, etc. very much. To implement the editor, I copied from the existing GamesEditor, and simplified it as much as I could.

I'd appreciate your input, especially since you wrote the PdfEditor, and it looks like it uses a different structure with the context components, which surprises me because the GamesEditor had comments that suggested inspiration from the PdfEditor. I don't understand enough to know if that will work better here, or if there was a particular reason for the diverging designs.

Anyway, comments and suggestions welcome! Once you're happy with it, I'll copy it to implement the MatchingEditor and re-add tests. :)

@Kelketek Kelketek left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, @samuelallan72 . I've left a review--- there are indeed some improvements to how we can leverage contexts here. The games block's editor was originally written in Redux and then was refactored to not need it. There's some artifacting there, so the PDF block is a better canonical example overall of how to use Contexts to build an editor.

settings,
setShuffleStatus,

list,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@samuelallan72 There are a lot of arguments being handed here. Can we use a context instead?

* `useSyncExternalStore`. Changes are the pure functions in flashcardsTransitions.
* React Query owns the requests. No Redux: this app is moving off it.
*/
export const useFlashcardsState = (block: BlockRef | null) => {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@samuelallan72 Rather than doing this, you should create a context that is populated with these values. By making this a hook, it's scoped only to the component which calls it, requiring you to pass the values down to every subcomponent.

Having it in a context means all subcomponents can pull from the context what they need without having to be handed the argument explicitly.

@samuelallan72

Copy link
Copy Markdown
Author

@Kelketek Thanks for the review and for the extra context:

The games block's editor was originally written in Redux and then was refactored to not need it. There's some artifacting there, so the PDF block is a better canonical example overall of how to use Contexts to build an editor.

This makes a lot of sense then! I'll work on refactoring it to follow the PdfEditor design more, and start learning more about react contexts. :)

};

export const saveSettings = (block: BlockRef, args: SaveArgs) =>
postToHandler<SaveResponse>(block, 'save_settings', buildSavePayload(args));

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Kelketek I discovered why the original games editor used the custom logic around saving! The built-in save logic directly modifies the xblock fields (here), which means you can't do server-side validation or post-processing of the data...

Note this means the pdf save_pdf handler is actually unused.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@samuelallan72 We'll likely want to move to the save handler for more flexibility in the PDF block. Makes sense now, at least.

Also some data restructuring and a small fix to UploadWidget
@codecov

codecov Bot commented Nov 12, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 48.24561% with 118 lines in your changes missing coverage. Please review.
✅ Project coverage is 96.09%. Comparing base (e37528e) to head (764994c).
⚠️ Report is 10 commits behind head on master.

Files with missing lines Patch % Lines
...s/FlashcardsEditor/components/FlashcardsEditor.tsx 34.09% 29 Missing ⚠️
...ers/FlashcardsEditor/components/FlashcardsCard.tsx 35.71% 18 Missing ⚠️
...rc/editors/containers/FlashcardsEditor/context.tsx 40.00% 15 Missing ⚠️
...ntainers/FlashcardsEditor/components/CardField.tsx 46.15% 14 Missing ⚠️
...ainers/FlashcardsEditor/components/CardPreview.tsx 40.90% 13 Missing ⚠️
src/editors/containers/FlashcardsEditor/api.ts 40.00% 12 Missing ⚠️
...ntainers/FlashcardsEditor/components/CardImage.tsx 57.14% 6 Missing ⚠️
...rs/FlashcardsEditor/components/SettingsSidebar.tsx 60.00% 4 Missing ⚠️
...ers/FlashcardsEditor/FlashcardsEditorContainer.tsx 62.50% 3 Missing ⚠️
src/editors/containers/FlashcardsEditor/index.tsx 77.77% 2 Missing ⚠️
... and 2 more
Additional details and impacted files
@@            Coverage Diff             @@
##           master    #3351      +/-   ##
==========================================
- Coverage   96.30%   96.09%   -0.21%     
==========================================
  Files        1450     1487      +37     
  Lines       35523    36788    +1265     
  Branches     8205     8898     +693     
==========================================
+ Hits        34209    35353    +1144     
- Misses       1272     1393     +121     
  Partials       42       42              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@Kelketek Kelketek left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@samuelallan72 This looks much better now. The image previews in library form don't work in the studio, though, and when embedding the block as library content into a course, the images don't load, either. You may want to check if the PDF block has a workaround for this.

// Drop state on unmount so that when we open again we have revised state.
useEffect(() => () => {
// We use a unique ID because a component higher up in the chain remounts quickly on
// startup, and cancelling or invalidating that transaction immediately results in

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wrote this originally. I think it's still effectively true, but I believe the actual cause now is React's Strict mode, which automatically remounts every component twice to force any bugs in terms of state handling to the surface, but the mix of redux alongside the state handling here means that things get out of sync in a way that's just really difficult to work around, save for the hack here.

I haven't checked if strict mode is enabled here, but it seems to be in a lot of the frontend projects, and I only learned about it afterward.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This makes sense, nice! I've updated the comment. :)

@samuelallan72

Copy link
Copy Markdown
Author

@Kelketek

The image previews in library form don't work in the studio, though, and when embedding the block as library content into a course, the images don't load, either. You may want to check if the PDF block has a workaround for this.

Nice catches thanks! I'll look into it. Just noting the pdf block doesn't have a workaround, and doesn't need one, because the editor doesn't display a preview of the file. The url is also /static/filename:

image

For components in libraries, the uploaded url is stored as
`/static/filename.jpg`, but to retrieve the file, we need the full
url. Something somewhere does magic to add the full url for the student
view, but not for editing. So we do it manually here.
@samuelallan72

Copy link
Copy Markdown
Author

@Kelketek I've pushed a fix for previewing the images when in libraries. I couldn't reproduce the issue with viewing images in the student view for embedding library content in the course though; could you recheck and share a reproducer if it's still an issue? Thanks! :)

@mphilbrick211 mphilbrick211 moved this from Needs Triage to Waiting on Author in Contributions Nov 16, 2026
@Kelketek

Copy link
Copy Markdown
Contributor

@samuelallan72 Previewing in libraries works now, but embedding flashcards using Library content within a course fails for me still.

The URL it attempts to fetch for a picture of a red fox I uploaded:

http://local.openedx.io:8000/asset-v1:Test+TS100+2026+type@asset+block/red-fox.jpg

In Studio, it is:

http://studio.local.openedx.io:8001/asset-v1:Test+TS100+2026+type@asset+block/red-fox.jpg

Do you get similar URLs? Are they working for you?

I did notice that on my devstack, PDFs are similarly broken and use similar URLs. I tried them both locally and on sandbox.opencraft.com, and they're broken in both places. This might mean that something has changed in asset handling that breaks things, unrelated to this PR. What version of the platform are you using?

@samuelallan72

Copy link
Copy Markdown
Author

@Kelketek sorry I'm not sure exactly what you mean by

embedding flashcards using Library content within a course

😅

@Kelketek

Copy link
Copy Markdown
Contributor

@samuelallan72

  1. Create a library.
  2. Add the flashcards block to the library. If you haven't already added it to your list of supported blocks, you'll need to. Here's an example plugin I'm using for it:
from tutor import hooks

# Make the exemplar blocks available in libraries for creation.
hooks.Filters.ENV_PATCHES.add_item((
    "openedx-cms-common-settings",
"""
LIBRARY_ENABLED_BLOCKS.extend([
    "openedx_flashcards",
])
""",
))
  1. Use the advanced option in the library and select Flashcards
  2. Create a flashcard with an image
  3. Save the block
  4. Publish the library
  5. Go to a course authoring and visit a unit page. Add a 'Library Content' block.
  6. Edit the settings of the 'Library Content' block to select the Flashcard block you created in your library.
  7. Once embedded, notice the image is broken.
  8. Publish and check on the LMS. It is also broken there.

@samuelallan72

Copy link
Copy Markdown
Author

@Kelketek huh interesting, it's working for me.

This is on a local master devstack.

@Kelketek

Kelketek commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

@samuelallan72

huh interesting, it's working for me.

I'll take your word for it, since I know it used to work for the PDF block, and that's failing the same way when I test.

Let me know when you're ready for another look.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

open-source-contribution PR author is not from Axim or 2U

Projects

Status: Waiting on Author

Development

Successfully merging this pull request may close these issues.

4 participants