docs: xblock aside developer docs

[asadali145]

Update developer docs for xblock asides.

[openedx-webhooks]

Thanks for the pull request, @asadali145!

This repository is currently maintained by @openedx/wg-maintenance-docs.openedx.org.

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.

Details

---

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:

• Overview of Review Process for Community Contributions
• Pull Request Status Guide
• Making changes to your pull request

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.

[asadali145]

@sarina I have this PR on top of your aside docs PR. Right now, I have created it against your PR to see the updates.

I have verified all updates in this PR. I need to verify the sample XBlock aside examples from the PR.

Should we create this as a PR against your branch or the main branch?

[asadali145]

@sarina, I have reviewed all of the changes, including the base changes from your PR plus the updates in this PR. I have also tested the sample asides, and they look good.

Please let me know if we want to create this PR against main and then we can proceed to a final review from Dave maybe.

[sarina]

Just a couple questions here, once we work those out we can point this PR at main and merge the whole thing in.

[sarina]

Interesting, I think I'm not following here though. What do you need to do, as a course author), to look at the legacy Studio unit page to see the Asides render?

Expanding on this, will the deprecation of legacy Studio break this flow entirely? And if you can only see Asides in legacy Studio, how do things render in the learning MFE?

[asadali145]

First of all, we should understand that AUTHOR_VIEW and STUDIO_VIEW are 2 different things that can serve an identical UI/View, but it is rendered in different places in legacy Studio. So, I used AUTHOR_VIEW or STUDIO_VIEW in the usage.

What do you need to do, as a course author, to look at the legacy Studio unit page to see the Asides render?

If you are using legacy Studio, and an aside supports both AUTHOR_VIEW and STUDIO_VIEW, you should see it render in 2 places:

• Open a course in Studio
• Open a unit page with a block that the aside supports
• You should see the aside AUTHOR_VIEW rendered with the block contents at the end of the block, like the ol-openedx-chat SS screenshot https://github.com/mitodl/open-edx-plugins/tree/main/src/ol_openedx_chat#8-go-to-any-course-in-cms--settings--advanced-settings-and-add-the-below-in-other-course-settings
• Now click on the edit button of the block
• You should see 3 buttons in the editor: Editor, Settings, and Plugins.
• Click Plugins, and you should see the STUDIO_VIEW of the aside.

If you are using the new authoring MFE:

• Open a course
• Open a unit page with a block that the aside supports
• You should see AUTHOR_VIEW rendered with the block contents at the end of the block. This is the same as above for the legacy unit page.

will the deprecation of legacy Studio break this flow entirely?

No, it will not break because the new authoring MFE uses an iframe to render the unit page, and it still supports the AUTHOR_VIEW, and we use it in the MITODL-maintained asides.

And if you can only see Asides in legacy Studio, how do things render in the learning MFE?

learning MFE displays STUDENT_VIEW of an aside so it will display whatever the Xblock Aside's STUDENT_VIEW returns. Regardless of its support in authoring MFE.

MORE DETAILS

Let me simplify all this for you. We have 2 studio views/UIs: legacy and new authoring MFE.

• We have 2 aside views, AUTHOR_VIEW and STUDIO_VIEW, in an aside's code. The main purpose of these 2 is to configure the Aside data if needed, like enable/disable.
• Legacy studio UI:
  • Legacy studio supports both AUTHOR_VIEW and STUDIO_VIEW of asides. Author and Studio views render in 2 different places.
  • AUTHOR_VIEW renders on the unit page; this is supported in both legacy and new authoring MFE. The unit page is basically an IFrame served by the studio backend. It has no connection to Authoring MFE, apart from the fact that it just renders the Iframe served by the studio backend.
  • STUDIO_VIEW renders at:
    • Click the edit button on a block, like a problem block.
    • In the editing dialog UI, there should be Editor, Settings, and Plugins in the title bar. Click "Plugins".
    • You should see the STUDIO_VIEW rendered here. MITODL's legacy repo for rapid response aside, has some details https://github.com/mitodl/rapid-response-xblock/tree/master. NOTE: This is a deprecated repo referenced here for clarity in Studio View.
• Authoring MFE / new Studio UI:
  • Authoring MFE itself does not have any support for Asides, but as it displays the unit page Iframe served by the studio backend, that unit page supports the AUTHOR_VIEW of the aside. The reason is that it is a preview of the block, and it has the aside's AUTHOR_VIEW rendered with it. i.e., the checkbox you see in screenshots under ol-openedx-chat is basically a unit page of a course with the AUTHOR_VIEW of the aside rendered in it. https://github.com/mitodl/open-edx-plugins/tree/main/src/ol_openedx_chat#8-go-to-any-course-in-cms--settings--advanced-settings-and-add-the-below-in-other-course-settings
• Learning MFE
  • Learning MFE displays the STUDENT_VIEW of an aside, so it does not depend on AUTHOR_VIEW or STUDIO_VIEW.

Let me know if you need more help understanding this. We can even have a meeting to clarify the understanding.