Metadata-Version: 2.4
Name: ol-openedx-feedback
Version: 0.2.0
Summary: An Open edX plugin to collect per-block learner feedback
Author: MIT Office of Digital Learning
License-Expression: BSD-3-Clause
Keywords: Python,edx
Requires-Python: >=3.11
Requires-Dist: django>=4.0
Requires-Dist: xblock
Description-Content-Type: text/x-rst

ol-openedx-feedback
###################

An Open edX plugin that adds a per-block "Send feedback" trigger to applicable
leaf blocks in the LMS via an ``XBlockAside``.  The trigger is shown only to
authenticated learners (never in Studio author/preview mode and never to
anonymous users).

When a learner clicks the trigger the aside posts an ``ol-feedback::drawer-open``
message to its parent window (the Learning MFE) using ``window.parent.postMessage``.
The message payload carries the block context needed to identify the content
being rated:

- ``courseId`` — the course key
- ``blockUsageKey`` — the block's usage key
- ``blockType`` — the XBlock category (e.g. ``problem``, ``video``)
- ``blockDisplayName`` — the block's display name

The Learning MFE receives the message and opens the feedback drawer, which
submits the learner's feedback directly to the **mit-learn** service.  This
plugin does **not** persist anything in edx-platform and exposes no REST API.

Installation
============

Install the package into the LMS Python environment:

.. code-block:: bash

    pip install ol-openedx-feedback

The plugin registers itself automatically through its entry points — the
``xblock_asides.v1`` aside plus the ``lms.djangoapp`` app config — so no changes
to ``INSTALLED_APPS`` are required. Restart the LMS after installing. (The
trigger is learner-facing only, so the plugin is LMS-only and is not installed
in Studio/CMS.)

Enable XBlock asides in the LMS admin
-------------------------------------

XBlock asides must be turned on for any aside (including this one) to render.
In the LMS Django admin, open **XBlock Asides Config**
(``/admin/lms_xblock/xblockasidesconfig/``), add a new entry, and check
**Enabled**. Make sure the block types you want the feedback trigger on are
**not** listed in **Disabled blocks** (the space-separated field defaults to
``about course_info static_tab``).

Enablement
==========

Feedback is gated by the ``ol_openedx_feedback.feedback_enabled`` course waffle
flag (default off). Enable it for the desired courses (or globally) to roll out.

Configuration
=============

Excluded block types
--------------------

By default the trigger renders on every leaf block and is suppressed only on
structural containers (``course`` / ``chapter`` / ``sequential`` / ``vertical``).
To additionally exclude one or more block types (for example ``html``), override
the excluded set through ``ENV_TOKENS`` (e.g. in ``lms.yml``):

.. code-block:: yaml

    OL_OPENEDX_FEEDBACK_EXCLUDED_BLOCK_TYPES:
      - course
      - chapter
      - sequential
      - vertical
      - html

The plugin reads this value via its ``settings.common`` ``plugin_settings`` hook
and exposes it as the ``OL_OPENEDX_FEEDBACK_EXCLUDED_BLOCK_TYPES`` Django
setting, defaulting to the structural set above when unset.

Text label
----------

The trigger shows only the megaphone icon by default. To also render the
"Feedback" text label beside it, enable it through ``ENV_TOKENS``:

.. code-block:: yaml

    OL_OPENEDX_FEEDBACK_SHOW_LABEL: true

This is exposed as the ``OL_OPENEDX_FEEDBACK_SHOW_LABEL`` Django setting via the
same ``plugin_settings`` hook, defaulting to ``false`` (icon-only) when unset.
