frontend-app-gradebook

Purpose

Gradebook allows course staff to view, filter, and override subsection grades for a course. Additionally for Masters courses, Gradebook enables bulk management of subsection grades.

Jump to:

• Should I use Gradebook in my course?
• Quickstart

For existing documentation see:

• Basic Usage: Review Learner Grades (read-the-docs)
• Bulk Grade Management: Override Learner Subsection Scores in Bulk (read-the-docs)

Branches and releases

This repository follows OEP-10 ADR 0002:

• master is the unstable development branch; every conventional commit publishes a prerelease of @openedx/frontend-app-gradebook to npm.
• stable carries the current stable major, published on the latest dist-tag. Older stable lines live on n.x / n.m.x branches as needed.
• The repository no longer participates in Open edX releases by branch: the legacy micro-frontend and any further release/RELEASENAME branches for it live on the legacy-mfe branch.

Should I use Gradebook in my course?

What does this offer over the legacy gradebook?

This frontend app offers a great deal more granularity when searching for problems, an easy interface for editing grades, an audit trail for seeing who edited what grade and what reason they gave (if any) for doing so.

Problems can be filtered by student as in the traditional gradebook, but can also be filtered by scores to see who scored within a certain range, and by assignment types (note: Not problem types, but categories like 'Exams' or 'Homework').

What does the legacy gradebook offer that this project does not?

This project does not (yet, at least) create any graphs, which the traditional gradebook does. It also does not give quick links to the problems for the instructor to visit. It expects the instructor to be familiar with the problems they are grading and which unit they refer to.

The gradebook is expected to be much more performant for larger numbers of students as well. The Instructor Dashboard link for the legacy gradebook reports that "this feature is available only to courses with a small number of enrolled learners." However, this project comes with no such warning.

Who should not change to this gradebook?

Groups whose instructors need not ever manually override grades do not need this project, but may not be any worse off depending on their needs. Instructors that expect to review grades infrequently enough that not having a direct link to the problem in question will have a worse UX than the legacy gradebook provides. Instructors that rely on the graphs generated by the current gradebook might find the lack of autogenerated graphs to be frustrating.

Getting Started

Installation

To install gradebook into your project:

npm i --save @openedx/frontend-app-gradebook

Quickstart

Cloning and Setup

1. Clone your new repo:

   git clone https://github.com/openedx/frontend-app-gradebook.git

2. Use the version of Node specified in .nvmrc

3. Stop Tutor, if it's running:

   tutor dev stop

4. Tell Tutor that we're going to be running this repo in development mode, so it should be excluded from the container that otherwise runs every frontend app. Run this:

   tutor mounts add /path/to/frontend-app-gradebook

5. Start Tutor in development mode. This command will start the LMS and Studio, and other required frontend apps like authn and account, but will not start Gradebook, which we're going to run on the host instead of in a container managed by Tutor. Run:

   tutor dev start lms cms mfe

Startup

1. Install npm dependencies:

   cd frontend-app-gradebook && npm install

2. Start the dev server:

   npm run dev

Running the UI Standalone

To install the project please refer to the Tutor MFE plugin instructions.

When not mounted, gradebook runs in the shared frontend app container at http://apps.local.openedx.io/gradebook/course-v1:edX+DemoX+Demo_Course.

When mounted in the tutor gradebook container, or when running a local (host) dev server, the app runs on port 1994, so when you go to http://apps.local.openedx.io:1994/gradebook/course-v1:edX+DemoX+Demo_Course you should see the UI (assuming you have such a Demo Course in your Tutor instance). Note that you always have to provide a course id to actually see a gradebook.

Starting the dev server hot-reloads JavaScript and Sass changes, so you should (:crossed_fingers:) not need to do anything (other than wait) when making changes.

Developing against a local frontend-base

This frontend app supports npm workspaces so you can develop against a local frontend-base checkout and see changes reflected automatically. See the dev:packages script in package.json and the workspace-related targets in the Makefile.

Plugins

This frontend app is built on frontend-base and can be customized through the shell's plugin slot mechanism (<Slot />). Any slots this app exposes for host sites to override live under src/slots.

Running tests

Run:

nvm use

npm ci

npm test

Directory Structure

• public
  • Static assets served at the site root when running the dev harness.
• src
  • Main.tsx
    • Root component the routed entry lazy-loads; sets the document title with <Helmet> and mounts the app's providers around the page tree.
  • app.ts
    • The App object consumed by site.config.*.tsx — wires appId, routes, and providers for frontend-base to register.
  • routes.tsx
    • React Router route definitions for the app.
  • providers.tsx
    • App-scoped context providers registered with frontend-base.
  • slots
    • Slots this app exposes for host sites to plug into.
  • components
    • Presentational and container React components.
  • containers
    • Route-level container components.
  • data
    • API hooks, query keys, React Query client, and shared context (filters, gradebook UI).
  • i18n
    • i18n entry point and generated messages (managed via openedx translations:pull).
• site.config.dev.tsx
  • Dev harness configuration — registers the shell, header, footer, and this app for local development.

License

The code in this repository is licensed under the AGPLv3 unless otherwise noted.

Please see LICENSE for details.

Contributing

Contributions are very welcome. Please read How To Contribute for details.

This project is currently accepting all types of contributions, bug fixes, security fixes, maintenance work, or new features. However, please make sure to have a discussion about your new feature idea with the maintainers prior to beginning development to maximize the chances of your change being accepted. You can start a conversation by creating a new issue on this repo summarizing your idea.

Getting Help

If you're having trouble, we have discussion forums at https://discuss.openedx.org where you can connect with others in the community.

Our real-time conversations are on Slack. You can request a Slack invitation, then join our community Slack workspace. Because this is a frontend repository, the best place to discuss it would be in the #wg-frontend channel.

For anything non-trivial, the best path is to open an issue in this repository with as many details about the issue you are facing as you can provide.

https://github.com/openedx/frontend-app-gradebook/issues

For more information about these options, see the Getting Help page.

The Open edX Code of Conduct

All community members are expected to follow the Open edX Code of Conduct.

Reporting Security Issues

Please do not report security issues in public. Please email security@openedx.org.