Add developer's docs on XBlock Asides by sarina · Pull Request #1443 · openedx/docs.openedx.org

sarina · 2026-05-02T05:23:18Z

Co-authored-by: Claude <claude@anthropic.com>

ormsbee

@sarina: Some change requests. I haven't actually run through the instructions here myself yet, and probably won't get around to it until mid-week.

@pdpinch: Would you or someone on your team familiar with Asides like to review this? There are places where I'm unsure and wrote that I need to verify things, but if someone on your team knows, their feedback would be most appreciated. Thank you.

ormsbee · 2026-05-03T15:18:56Z

+XML child element under its host block, named after the aside's entry point
+name. On import, the runtime reconstitutes the asides automatically. This


Note to self: Check this. I thought Asides serialized into the tag itself as namespaced attributes.

@arslanashraf7 or @asadali145 can you confirm?

ormsbee · 2026-05-03T16:16:45Z

+The Studio runtime does not consult this configuration. Asides render
+in Studio author views independently of ``XBlockAsidesConfig``, as soon
+as they are installed and registered.


Note to self: Verify this and file a bug if necessary.

Not a bug, studio has its own model to gate asides.

ormsbee · 2026-05-03T17:06:50Z

+
+Inherited from ``Blocklike``. Override these to customize how the aside is
+read from and written to OLX. The default implementations serialize the
+aside's fields as XML attributes and child elements, identical to the


Note to self: verify this.

ormsbee · 2026-05-03T17:09:36Z

+* An aside's data only round-trips through OLX if both the source and
+  destination platforms have the same aside installed under the same
+  entry point name.


Note to self: Verify this

pdpinch

Pretty impressive, especially creating two different example Asides, one for the how-to and one for the quickstart. I left some notes.

I'm going to ask a couple of the devs who have worked with Asides to review this as well.

pdpinch · 2026-05-03T21:25:09Z

+An XBlock aside is a class that injects content into the rendered views of
+existing XBlocks without modifying those XBlocks. Asides let you add behavior,
+data, and UI elements to many XBlock instances at once, across XBlock types you
+do not own, while preserving the host XBlock's code, fields, and Open Learning


What does this mean, "across XBlock types you do not own" ?

Claude describes what it meant:

By "XBlock types you do not own," I meant XBlocks whose source code you don't maintain — typically core platform blocks like problem and video (owned by the edx-platform team), or third-party blocks like ORA2, or blocks maintained by another organization. If you wanted to enhance one of those, your non-aside options are: fork it (and maintain a parallel copy), upstream a PR (slow, narrow design space, may be rejected), or wrap it in a replacement block (forces every existing course to migrate). Asides give you a fourth option: attach behavior from your own installable package, leaving the upstream code untouched.

That said — if you're asking, the phrasing wasn't self-explanatory, which is its own signal. Some options to make it clearer:

Option A (minimal — define the term in place):

across XBlock types whose source you do not maintain (for example, the platform's built-in problem and video blocks, or third-party blocks installed as separate packages)

Option B (recast — drop the ownership framing, lead with the practical consequence):

Asides let you add behavior, data, and UI elements to many XBlock instances at once — including instances of XBlock types maintained by other teams or installed as third-party packages — while preserving the host XBlock's code, fields, and Open Learning XML (OLX) representation.

Option C (cut it):

Asides let you add behavior, data, and UI elements to many XBlock instances at once, while preserving the host XBlock's code, fields, and OLX representation.

The "without modifying those XBlocks" earlier in the same paragraph already implies this, so cutting the phrase entirely is defensible. The rest of the concept doc, particularly the "The Problem Asides Solve" section, makes the fork-vs-replace-vs-aside trade-off explicit.

Do any of these options feel correct, and worth applying?

pdpinch · 2026-05-03T21:33:29Z

+XML child element under its host block, named after the aside's entry point
+name. On import, the runtime reconstitutes the asides automatically. This


@arslanashraf7 or @asadali145 can you confirm?

pdpinch · 2026-05-03T21:35:56Z

+
+The Studio author view for an aside is rendered by the legacy course
+authoring frontend. The current Course Authoring micro-frontend has no
+defined location to display aside author UI. If your project depends on the


This is old news. The authoring view in the MFE works just fine, although it is different from the legacy studio UI.

pdpinch · 2026-05-03T21:36:57Z

+with the export process. Some XBlocks, including ORA2, do not preserve
+aside data through their export and import paths. If your aside must
+survive a course export and re-import on a course that uses one of these
+blocks, test the round trip end to end before depending on it.


@arslanashraf7 or @asadali145 do you recall the details of this?

Co-authored-by: David Ormsbee <dave@axim.org> Co-authored-by: Peter Pinch <pdpinch+github@hawklake.com>

sarina · 2026-05-04T01:58:35Z

Belatedly, I'm 100% realizing these docs should live in https://github.com/openedx/XBlock/tree/master/docs not here. However, I think it'd be best since we're already mid-review to continue to review here, and when we're satisfied I'll close this PR and open it appropriately over in the XBlock repo for final review.

asadali145 · 2026-05-06T10:26:41Z

+No Authoring Story in the Course Authoring MFE
+==============================================
+
+The Studio author view for an Aside is rendered by the legacy course
+authoring frontend. The current Authoring micro-frontend has no
+defined location to display Aside author UI. If your project depends on the
+new MFE for authoring, plan to render the Aside's author UI through a
+different mechanism, or accept that authors will use the legacy Studio for
+this part of the workflow.


There are 2 views, AUTHOR_VIEW and STUDIO_VIEW.
Previously, we used STUDIO_VIEW to display any aside field, like enable/disable checkbox, etc., and it was displayed in the editor. By editor, I mean the edit view that opens when we click the edit button of an XBlock in Studio. There used to be a settings tab in that editor. This is not available in the authoring MFE.
Alternatively, we shifted to AUTHOR_VIEW and used it to display the fields on the unit page in authoring MFE, and this works fine.
In ol_openedx_chat aside, we have an author_view, and it displays the checkbox field in the unit view like:

We should note that we are using an XBlock handler to save the state of this checkbox. XBlock handler is called from JS when state of this checkbox changes.

asadali145 · 2026-05-06T10:41:55Z

+with the export process. Some XBlocks, including ORA2, do not preserve
+aside data through their export and import paths. If your aside must
+survive a course export and re-import on a course that uses one of these
+blocks, test the round trip end to end before depending on it.


@ormsbee If I understand it correctly, this is related to openedx/openedx-platform#36576.

asadali145 · 2026-05-06T10:48:20Z

+.. _rapid-response-xblock: https://github.com/mitodl/open-edx-plugins/tree/main/src/rapid_response_xblock
+.. _ol-openedx-chat: https://github.com/mitodl/open-edx-plugins/tree/main/src/ol_openedx_chat
+.. _xblock-sdk: https://github.com/openedx/xblock-sdk


FYI, that StructuredTagsAside was helpful for us.

asadali145 · 2026-05-06T11:03:09Z

+The Studio runtime does not consult this model. Asides will render in
+Studio author views as soon as they are installed, independently of
+whether ``XBlockAsidesConfig`` is enabled.


This is partially correct, for studio, there is similar model in studio admin at http://studio.local.openedx.io:8001/admin/xblock_config/studioconfig/ that gates the asides.

asadali145 · 2026-05-06T11:17:11Z

+The Studio runtime does not consult this configuration. Asides render
+in Studio author views independently of ``XBlockAsidesConfig``, as soon
+as they are installed and registered.


As mentioned in Quickstart, Studio has its own model http://studio.local.openedx.io:8001/admin/xblock_config/studioconfig/. We need to enable it to enable the aside author view.

asadali145 · 2026-05-06T11:33:58Z

+       @XBlockAside.aside_for("studio_view")
+       def studio_view_aside(self, block, context=None):
+           """Render the author-side toggle UI in Studio."""
+           checked = "checked" if self.enabled else ""
+           html = (
+               f'<label><input type="checkbox" {checked} '
+               f'class="feedback-badge-toggle"> Show feedback link</label>'
+           )
+           return Fragment(html)


Changing the state of this checkbox won't save the setting. We will need to implement a handler and write custom JS to call the handler when the state of this field changes to save the setting. I have mentioned this in my other comment in about_xblock_asides.rst

asadali145 · 2026-05-06T11:40:22Z

+   ``"about course_info static_tab"``). The Studio runtime does not
+   apply this gate. See :ref:`Add an XBlock Aside` for the
+   administrative steps to enable the configuration.


As mentioned already, studio also gates the asides.

asadali145 · 2026-05-06T12:31:34Z

+   tutor mounts add /path/to/feedback_badge_aside
+   tutor dev launch


I couldn't test this with mounts. I'll give it another go later today.

Add developer's docs on XBlock Asides

9416fbb

Co-authored-by: Claude <claude@anthropic.com>

sarina requested review from ormsbee and pdpinch May 2, 2026 16:16

ormsbee requested changes May 3, 2026

View reviewed changes

pdpinch reviewed May 3, 2026

View reviewed changes

sarina and others added 3 commits May 3, 2026 21:49

temp: Apply suggestions from code review

7065077

Co-authored-by: David Ormsbee <dave@axim.org> Co-authored-by: Peter Pinch <pdpinch+github@hawklake.com>

temp: Remove note about sparse documentation

80f0184

Consistently capitalize 'Aside'

a0d95b0

asadali145 reviewed May 6, 2026

View reviewed changes

		XML child element under its host block, named after the aside's entry point
		name. On import, the runtime reconstitutes the asides automatically. This

		tutor mounts add /path/to/feedback_badge_aside
		tutor dev launch

Conversation

sarina commented May 2, 2026

Uh oh!

ormsbee left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pdpinch left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sarina commented May 4, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants