LearnDash Gradebook

Documentation

Manage Gradebooks

In order to use this plugin, you will need to create one or more Gradebooks. Each Gradebook can have customized settings.

Access

In order to manage your Gradebooks, visit the main Gradebook page under “LearnDash LMS” and then click the “Manage Gradebooks” tab at the top of the page. From there you can edit Gradebooks or create new ones.

Customization

There are various settings you will need to customize for each Gradebook.

Grading

This section of the Gradebook determines what will go into factoring the final user grades.

You must first select a Course to be graded, or leave it to “All Courses”. Note: If left as “All Courses”, you will not be able to grade Topics and Lessons, because the completion of these is Course-specific.

You may then add any number of Components. Each Component is something that will have a grade calculated depending on what is inside it. Each Component grade will factor towards the Gradebook final grade for each user. Some examples of Components would be: Lessons, Quizzes, Semester 1, At Home Projects, etc. Add any number of Quizzes, Assignments, Lessons, and Topics to each Component. You may also set the All Toggle to active, which will automatically include all current and future items. Be sure to also give each Component a name.

Weighting

Each Gradebook offers the ability to use a weighted grading system. This is turned off by default, but you can toggle it on by clicking on the toggle under “Enable Gradebook Weighting”. Once enabled, you will see a list of all Components you have created (if any) and an input to enter a “Weight %”. Enter a percentage out of 100% for each Component, so that all Components total 100%. Now, when factoring the final grade, each Component’s grade will only count for whatever weight you assign it.

Settings

Completion Grading is a setting you can modify that will determine how Lessons and Topics are graded. By default, this is set to “Only count on completion”. What this means is that if you have any Lessons and Topics inside any Components, they will not count towards the final grade until they are completed, at which point they will receive 100% for each. If you change this setting to “Fail until completion”, each uncompleted Lesson and Topic will count as a failing grade at 0% until the user marks them complete, at which point they will receive 100% for each.

Users

This does not contain any settings, but it allows you to quickly search for a user, and then click the “View/Edit User Grades”, where you can view or modify a user’s grades for the current Gradebook.

The Gradebook

The Gradebook page is where site admins, instructors, or anyone else who has proper access can go to view a snapshot of each Gradebook’s grades.

Access

This page is accessible via the LearnDash LMS admin menu under Gradebook.

Usage

Each row in the table provides information about a single user and his/her overall grade and any other pre-defined Component grades. When more Components are added to each Gradebook, they will show here respectively.

Sorting

Clicking on any column header will reload the page with all of the user results sorted by the selected column in ascending order, indicated by an upwards facing triangle next to the column header. Clicking the same column header will reload the page with the results sorted in descending order.

Searching Users

Use the user search in the top right to search through all users. This search field works like the default WordPress admin user search. You may enter a user ID, user display name, user login name, or even user email.

Groups

The Gradebook allows you to filter the results by groups. If you are an administrator of the website, you will be able to see all users without any group restrictions, and you will be able to view individual groups via the “Showing Gradebook for:” select box in the top left of the screen.

If you are a group leader that only belongs to 1 group, you will not see the dropdown and you will only see users in your group. If you are a leader of more than 1 group, you will be able to see a dropdown and switch groups.

Safe Mode

If you have a slow performing website, or you have a very large user base, and the Gradebook will not load, try enabling “Safe Mode”. This will disable some sorting features and grade snapshots within the Gradebook, but will load significantly faster and load more reliably on larger websites.

To enable Safe Mode, see here.

Report Card

The Report Card is a presentational tool to give users information about their grades for a Gradebook.

Display

The report card contains information about the user’s overall grade, individual Component grades, and individual scores on various grade details. Clicking on any Component, or the arrow to the left, will expand a breakdown of scores. Scores can be manual grades, quizzes, assignments, lessons, or topics.

Usage

In order to use the report card, you must use the report card shortcode: [ld_report_card gradebook="1"]

Copy and paste this shortcode into any text that accepts shortcodes, the most common being the main content of any page or post. Replace the number “1” with the ID of the Gradebook you want to show. You can also find the shortcode to copy when editing each Gradebook.

If you use the shortcode without a Gradebook ID defined like [ld_report_card] then it will attempt to show all relevant Gradebooks for the user one after another.

You may also use the shortcode attribute user to specify a specific user by the user’s ID. This will cause the report card to contain information about whatever user is supplied.

To find a user’s ID, go to the Users page in the WordPress administration area of the site and click on the username of whichever user you want to find the ID of. This will take you to the user edit page. In the URL you will see part of the URL that looks like user_id=107. The number is the user ID.

If you only want to show the Overall Grade (For instance, as part of a Certificate) then you can alternatively use the [ld_overall_grade] shortcode. The arguments are identical to those used in [ld_report_card], however for the Overall Grade shortcode the Gradebook ID is required.

Assignments

LearnDash has the ability to set a custom grade for assignments. By default, the grade of an assignment is assumed to be 100%, unless modified.

Manual Grades

Manual grades may be entered for users at any time. They are used to add any grade that cannot be represented by a quiz or assignment.

Accessing the Edit Screen

In order to manage a user’s manual grades, you will need to access the Gradebook user edit screen. This can be done either by clicking the “View/Edit User Grades” text in the “User” column of the Gradebook or by searching for a user and clicking “View/Edit User Grades” from the Gradebook edit screen.

Each row represents a grade. Each grade type is represented by the icon on the left side. Hovering over the icon will reveal text to help identify.

  •  Pencil – Manual Grade
  •  Question Mark – Quiz
  •  Paper – Assignment
  • Writing – Lesson
  •  Folder – Topic

Managing Manual Grades

From here you may add, delete, or modify manual grades for the user.

NOTE: All changes you make are live immediately, so be cautious.

Add a Manual Grade

To add a manual grade, click the “Add Manual Grade” button. This will display a manual grade edit panel. From here you must:

  1. Enter a unique name for the manual grade. This can be anything, but it must be unique to the Type you are adding the grade to. It may be “Crossword Puzzle” or “Attendance” or anything else.
  2. Enter the score for the grade. It can be any number above 0.
  3. (Optional) Enter a status for the grade.
  4. Click the “Add” button.

NOTE: By default, there is no special status, but you may set the grade to have a special status. Currently, the only status to select is “Incomplete”. By setting the grade to “Incomplete”, the grade will not be factored into the final grade calculations.

Remove a Manual Grade

A manual grade may be removed at any time. You must:

  1. Hover over any manual grade (manual grades are represented with a pencil icon on the left side).
  2. Click the “Remove” link that appears.
  3. Confirm deletion.

WARNING: Manual grades cannot be recovered. You can always add it back yourself, but you cannot undo it automatically.

Edit a Manual Grade

A manual grade may be edited at any time. You must:

  1. Hover over any manual grade.
  2. Click the “Edit” link that appears.
  3. Follow the same steps as adding a manual grade, except click the “Change” button when finished.

Modifying Other Grades

You are able to also modify quiz and assignment grades from here. Currently, the only modifications you can make from here are assigning them a special status. You cannot edit the actual grade score from here.

Settings

LearnDash – Gradebook provides robust customization over the plugin functionality via settings.

Accessing the Settings Pages

This page is accessed by first accessing the Gradebook page (as explained above here), and then clicking on the “Settings” tab at the top of the screen.

From here, use the blue links at the top to move to different Settings sections.

General

From the “General” section of the Settings page, you can adjust various general plugin settings.

Quizzes

Depending on your site setup, users may be able to re-take quizzes. If so, you must choose whether the user’s most recent quiz score will be used, or the user’s best (highest) score.

Grade Display Mode

By default, Gradebook uses letters (A, B, D-, C+, etc.) to display grades. If you would rather have the system use percentages (0-100%), change this setting to “Percentage”.

Grade Rounding Precision

Individual user grade component (assignment, quiz, manual grade) rounding is determined by these settings. This does not impact rounding of Component grades or the user’s final grade.

Precision determines how many decimal places a grade will be rounded to. 0 will not use any decimals and only allow whole numbers (integers). You may set this to any value between (inclusive) 0 and 10.

Grade Rounding Mode

Rounding mode determines how the precision will be rounded. Rounding up will allows round the precision point up. Rounding down will allows round it down. Closest will round it up or down based on which it is closest to (5 rounding up).

Gradebook Safe Mode

Safe Mode can be toggled on and off. To see more information on what Safe Mode is, see here.

Note: If you are unable to even access the Settings page because the Gradebook page won’t load, take your site address (let’s say https://example.com), figure out your WordPress admin base (most likely /wp-admin/), and then append admin.php?page=learndash-gradebook-settings (so, in our example, full URL would be https://example.com/wp-admin/admin.php?page=learndash-gradebook-settings

Restart Quickstart Guide

Once you dismiss the Quickstart Guide, you may restart it by clicking the button here. You may also copy and share the link provided to other users to restart the guide (only if they have access).

Roles

This is where you can make changes to roles and capability aspects of the plugin.

View the Gradebook

By default, only Administrators and Group Leaders can view the Gradebook. If you would like to allow other user roles to view the Gradebook, you may add them here.

DEVELOPER NOTE: This will add the capability view_gradebook to the selected roles. You may add this capability to roles in any method desired, including any role manager plugins, and the results will be reflected here.

Create and Edit their own Gradebooks

By default, only Administrators can create and edit Gradebooks. If you would like to allow other user roles to create and edit their own Gradebooks, you may add them here. Any user roles you grant this capability to can only manage their own Gradebooks, but Administrators can manage anyone’s Gradebooks.

DEVELOPER NOTE: This will add the capabilities read_gradebook, read_private_gradebooks, publish_gradebooks, edit_gradebook, edit_gradebooks, edit_private_gradebooks, edit_published_gradebooks, delete_gradebooks, delete_private_gradebooks, delete_published_gradebooks, and delete_gradebook to the selected roles. You may add these capabilities to roles in any method desired, including any role manager plugins, and the results will be reflected here. In order for the Gradebook menu item to appear, they must also be granted the view_gradebook capability.

Quickstart Guide Visibility

Only administrators can view the Quickstart Guide. If you would other users to be able to use the guide, you may add them here. Only user roles with enough capability to access all of the LearnDash and LearnDash – Gradebook pages will appear here. In a typical setup, this is only the “Administrator” role.

Styles

This is where you can change some styling parts of the plugin.

Letter Grade Scale

LearnDash – Gradebook uses a very typical letter grade system by default to display user grades. You may edit this in any way you like here. Simply modify the existing values, delete existing values, or even add new letters using the “Add Letter Grade” button at the bottom.

NOTE: You cannot change the order of letters, but they are automatically displayed in ascending order by the grade and will be automatically re-sorted after saving changes.

Grade Color Scale

You may also edit the color displayed with user grades here. Same with the letter grade scale, you may modify what already exists, delete any, and add new values.

Note on both scales:

Both scales will function in the following manner: Once a grade has reached the percentage you enter as a minimum, the letter or color will be applied up until the next interval.

Licensing

This page is where you manage your plugin license. It is VERY IMPORTANT that you enter and activate your license as soon as possible. Activating the license on your site gives you access to important updates to the plugin including new features, bug fixes, and potential security patches.

Developer

Report Card Template

The Report Card template can be heavily or lightly modified as needed. There are 2 ways to override an aspect of the report card.

Overriding Theme Template Files

The plugin first looks in your theme for template files before loading the plugin template files. If a child theme is active, that will take precedence, then your parent theme, then the plugin. Any number of the template files that make up the report card may be replaced. It is recommended to copy whichever files you need to replace first, and then modify from there. The structure in your theme would be as follows:

  • learndash/report-card/report-card.php
  • learndash/report-card/title.php
  • learndash/report-card/overall-grade.php
  • learndash/report-card/expand-collapse.php
  • learndash/report-card/component/component.php
  • learndash/report-card/component/grade.php
  • learndash/report-card/component/grades-header.php
  • learndash/report-card/component/title.php
  • learndash/report-card/component/toggle.php
  • learndash/report-card/grade/grade.php
  • learndash/report-card/grade/name.php
  • learndash/report-card/grade/score.php
  • learndash/report-card/grade/type.php

Take a look at how these files work within the plugin itself. To locate them in the plugin, simply replace the “learndash” directory with “templates” directory.

Removing or Modifying the Hooks

These files are loaded via action hooks. You can easily remove or replace them to use your own functions to load files. You can get a better look at them and how to use them inside the file in the plugin includes/shortcodes/class-ld-gb-sc-reportcard.php

Changelog

1.6.6

  • Add option to mark Assignments/Quizzes as incomplete until completion
  • Fix for removing Component Grade overrides
  • If a Course is chosen for a Gradebook, ensure that Quiz Grades that are grabbed are only for that Course. This is important if a Quiz is shared across multiple Courses.
  • If a User Role can see the Gradebook but cannot create their own Gradebooks, ensure that they do not see the “Create Gradebook” button if no Gradebooks are found.

1.6.5

  • Adds a Completion timestamp to the Quiz Grades within Components. This is a developer-centric change for those who may be using the ld_gb_get_user_grade Filter

1.6.4

  • Adds the Overall Grade Shortcode. This can be a useful utility in LearnDash Certificates.
    • Usage: [ld_overall_grade gradebook=123]
  • Fixes a potential issue when using the ld_gb_adminpage_gradebook_select_query_args filter to ensure that the default Gradebook will always be the first one in the Select dropdown
  • If a Quiz was manually marked as “Complete” from the User Edit screen, LearnDash Gradebook will now show a 0% for that Quiz instead of hitting an error

1.6.3

  • Fixes bug when using [ld_report_card] with no Gradebook set

1.6.2

  • Adds Gradebook ID to ld_gb_gradebook_data Filter
  • Adds ld_gb_gradebook_list_table_grade_display Filter
  • Adds ld_gb_get_user_grade Filter which allows overriding the returned value of ld_gb_get_user_grade() before anything is processed

1.6.1

  • The ld_gb_adminpage_gradebook_select_query_args filter was placed on the incorrect query. This will now do what is expected of it.

1.6.0

  • Now respects the Custom Labels given to LearnDash Content Types in its Settings
  • Assignment Lesson/Topic fields now will only show results for Assignments that have Assignment Uploads enabled
  • If Lessons or Topics are chosen to pull Assignment Grades for and the Gradebook has “Fail until completion” enabled, then a failing score of 0% will be shown for every Assignment that a Student has not submitted
    • Note: These will show below other Assignments in their User Grades and in the Report Card regardless of your Component Ordering settings.
      If an Assignment has been submitted but not approved, then it will show “Pending Approval” in their User Grades and within the Report Card and not count toward or against the Student.
  • If [ld_report_card] is used without a gradebook defined, it will attempt to output all relevant Gradebooks for that Student.
    • To help facilitate this, the Gradebook ID needed to be passed into each Report Card template. This means that if you are overriding any Report Card template files in your Theme, they will require updating.
    • These changes only impact if you’re showing multiple Report Cards on the same page.
  • Added the ld_gb_adminpage_gradebook_select_query_args filter to allow adjusting the Query Args for the Gradebooks shown in the Gradebooks dropdown on the primary Gradebook admin page.
  • Added the learndash_gradebook_delete_manual_grade() and learndash_gradebook_update_manual_grade() functions to make interacting with Manual Grades programmatically easier.
  • Added the learndash_gradebook_manual_grade_default_score filter so that a default score for Manual Grades on the User Grades screen can be defined. This does not impact using the functions listed above.

1.5.1

  • Fixes an issue where when choosing a Group, it was possible for the Gradebook to show all Users if no Users within the Group had started the Course yet.
  • Add ability to disable Manual Grades
  • Add ability to disable Component grade Overrides
  • Fixes issue where using a non-existing Gradebook with the Report Card Shortcode would cause a Fatal Error
  • Fixes an issue where sometimes elements could be missing from the Gradebook/Report Card
  • Adds the ability to show the containing Lesson/Topic title for Assignment entries in the Gradebook/Report Card rather than the uploaded file name.
  • The Report Card template file at templates/report-card/report-card-error.php has been updated. If any Themes are overriding this file, they will need to update it.

1.5.0

  • Fixes issue where when a User was granted the ability to view or create/edit Gradebooks, they were unable to within LearnDash v3.0
  • Fixes an issue where if a User did not dismiss the Quickstart Guide they were unable to utilize any aspects of the Gradebook
  • If a website had a lot of Course Content, it was possible that when creating a new Gradebook the page would fail to load. The default Course is no longer set to “All Courses” to avoid this. For sites where this is an issue, they will be unable to use “All Courses” at this time.
  • Fixes some styling with the Gradebook and Report Card shortcode
  • The Report Card template file at templates/report-card/report-card.php has been updated. If any Themes are overriding this file, they will need to update it.

1.4.7

  • Fixes incompatibility with Gravity Forms Advanced Post Creation when attempting to create a Post Creation Feed

1.4.6

  • Fixes an issue where Gradebooks of Courses where no User had started the Course yet would show all Users even when the “Show All Users” option was disabled

1.4.5

  • Fixes issues with loading resources on Windows Servers

1.4.4

  • Prevents a possible PHP error when using the [ld_report_card] shortcode
  • Corrects a PHP warning when using the [ld_report_card] shortcode

1.4.3

  • Fixes incompatibility with Download Manager Pro

1.4.2

  • Fixes incompatibility with WisdmLabs’ Instructor Role Plugin causing data to not populate in the Gradebook or User Grade views.

1.4.1

  • Gradebooks can now have their Author changed via the Edit screen or the Quick Edit dialog. This is useful if you’ve granted other Roles the ability to Edit Gradebooks, but you want to create one for them and “assign” it to them afterward.

1.4.0

  • You can now grant any User Role the ability to Create their own Gradebooks. This can be found under LearnDash LMS -> Gradebook -> Settings -> Roles.
  • Fix: Minimum LearnDash version now set to v2.3.0.
  • Fix: Minimum WordPress version now set to v4.8.0.

1.3.8

  • Fix: Fixes stying bug when Grade Display Mode is set to “Percentage”
  • Fix: Quiz grades were not showing as failed if the “Fail until completion” setting was checked in the Gradebook Settings.

1.3.7

  • Fix: Bug in upgrade routine that caused Gradebook to think the last upgrade preformed was one for v2.0.0
  • Fix: Administrators are now able to edit Gradebooks made by other Users again (Database Upgrade Required)
  • Added a hierarchy context for each item when Editing a Gradebook
    • Example: Lesson 2 -> Topic 3 -> Quiz 4
    • This is helpful if you have multiple different Topics or Quizzes with the same name so that they can be visually differentiated from each other when configuring a Gradebook

1.3.6

  • Fix: Components sometimes lost their ID’s, not allowing weights to be set properly.

1.3.5

  • Fix: Unable to edit others gradebooks on multisite if not super-admin.

1.3.4

  • Fix: Gradebook safemode not loading users.
  • Fix: Edge case narrow dropdown for group selector on Gradebook page.
  • Fix: Unable to edit user component grade overrides.
  • Add ability to manually setup roles.

1.3.3

  • Fix: Upgrade RBM FH to prevent Select2 conflict.
  • Fix: Broken capability

1.3.2

  • Fix: Gradebook not showing pagination.

1.3.1

  • Fix: Gradebook only showing 10 users.

1.3.0

  • Feature: Grade display mode. Allows displaying grades as percentages.
  • Feature: Report Card resource ordering. Allows customization of ordering of resources on Report Card.
  • Feature: Assignments from Topics. Allows adding assignments from topics on Gradebook, similar to assignments form lessons.
  • Improvement: Better select box for group selector on Gradebook page.

1.2.101

  • Fix assignments not populating dropdown on Gradebook edit page.
  • (Version 101 due to error)

1.2.10

  • Report Card shortcode user logged out message.

1.2.9

  • Fix broken setting for Grade Color Scale.

1.2.8

  • Fix “All Quizzes” in Gradebook with new LearnDash Course Builder.

1.2.7

  • Fix “disappearing” options in components within Gradebook management.

1.2.6

  • Allow Group Leaders (or anyone with the “view_gradebook” capability) to view and edit user grades.
  • Fix incompatibility with the new Shared Course Steps feature.

1.2.5

  • Fix some PHP notices

1.2.4

  • Fix pre PHP 7 conflict

1.2.3

  • Gradebook safemode fix
  • Gradebook page hide users verbiage update
  • Pre PHP 7 conflict fix

1.2.2

  • Filter users in Gradebooks based on Course enrollment
  • Modify upgrade process

1.2.1

  • Potential but with upgrade process

1.2.0

  • Multiple Gradebooks
  • Premium support
  • Assignment points integration

1.1.7

  • Allow Group Leaders to assign Gradebook Types to Assignments and Quizzes.

1.1.6

  • Fix new “Gradebook Safe Mode” loading bug.

1.1.5

  • Improve user searching in Gradebook.
  • Add “Gradebook Safe Mode” for faster loading on sites with large databases.

1.1.4

  • Fix Group Leader edit assignment grade bug.

1.1.3

  • Fix translatable string in Report Card

1.1.2

  • Require min LearnDash version of 2.1.0

1.1.1

  • Fix infinite quickstart loop

1.1.0

  • LearnDash groups support
  • New settings page structure and improved settings API
  • New report card templating system
  • Gradebook role access customization
  • Gradebook Type grade override capability
  • Gradebook searching and sorting
  • Improved Gradebook styles
  • Gradebook Type grade information tool tip
  • Gradebook dashboard widget
  • Customizeable grade rounding
  • Fix radio select bug

1.0.4

  • Fix obtrusive settings page styling.

1.0.3

  • Fix broken admin Gradebook pagination.

1.0.2

  • Quickstart can be cutoff on tall admin menus.

1.0.1

  • Revise user edit screen Gradebook interface.
  • Grade Statuses.
  • Add indicators to the Types page to see what each Type is currently being used by.
  • Move licensing to the Gradebook Settings page.
  • Bug fixes.

1.0.0

  • Initial release.