This document describes how to extend the edX platform with a new tab that can be added to courses.
An edX course has a notion of a set of tabs that present the student with information about an aspect of their experience:
In Studio, a course author can manage the list of tabs (called Pages in the UX):
Introducing a new course tab
The edX platform provides a Python entry point to allow new course tabs to be registered as plugins. At a high level, we recommend that you do the following:
- Implement your new feature as its own Django app following these guidelines: How to add a new feature to LMS or Studio
- For now, this Django app must live inside the edx-platform repo as your plugin must subclass
CourseTab or one of its subclasses
- We hope to remove this restriction soon by moving this subclass into a separate
- Our current recommendation is to place your new Django app in the folder
- Render the tab as a /wiki/spaces/ArchiveEng/pages/157888616, as this has a number of benefits:
- Allows your tab to be rendered standalone in the mobile apps
- Allows alternate LMS implementations to dynamically render your fragment as part of a single page application
- Removes the need for your template to render the full page using Mako in order to include the platform's main.html template
- Potentially allows your feature to live outside of the edx-platform repo (although this is not currently possible due to the dependency upon the
CourseTab base class)
The following is a more detailed list of the steps required to add a new course tab.
1. Add an entry point like this to your Python library's setup.py
new_tab is the id of your tab, and
example.NewTab is the fully qualified name of your new tab class.
2. Define your new tab class
Define your new tab class as a subclass of
EnrolledTab, if the tab should only be shown to enrolled users, or
CourseTab if unenrolled users should also be able to see it.
The key properties of a course tab are as follows:
|name||The name of the tab. This name is used as the id of the tab when persisted in a course.|
|title||The title of the tab. This is typically shown as the tab's label.|
The name of the fragment view class that renders the tab's contents. This property should only be specified if the tab class uses
The name of the Django view that renders the tab. This field is required if
fragment_view_name is not specified.
Note that for the moment all new tabs must be implemented as Django views. The following JIRA story proposes support for adding new tabs using xblocks:
|priority||The relative priority of this tab. If specified, it affects the order in which this tab is added to a course. Lower priorities appear first, and the built-in tabs use priorities below 50. It is strongly recommended to use the default and allow the tabs to be sorted alphabetically.||None|
|tab_id||The HTML id to be used when the tab is rendered.||uses value of name|
|is_movable||If true, the author can move this tab to a different position.||True|
|is_dynamic||If true, this tab will be shown dynamically to the user, instead of being persisted into the course's tabs. A good example is the "Instructor" tab which is shown only to course staff.||False|
|is_default||If true, this tab will be added to the end of course's list of tabs if it is enabled. For example, the "Notes" tab appears automatically when Student Notes is enabled in a course. This tab will then be exported with the rest of the course. The list of tabs is refreshed after modifying the advanced settings.||True|
|is_hideable||If true, an author can choose to hide this tab from their course.||False|
|allow_multiple||If true, a course can add more than one instance of this view type.||False|
In addition, a tab can override any of the following class methods:
def is_enabled(cls, course, user=None)
|Returns true if this tab is enabled for the current course for the specified user. If user is None, this method is being called by Studio and should generally return True if the tab will be shown to at least some students.|
def validate(cls, tab_dict, raise_error=True)
|Validates a dictionary representing a course tab. If raise_error then issues are raised as exceptions, else the function should return True if the dictionary is valid.|
3. Implement the view
You have two choices when implementing your new tab view:
- Implement a view which renders only the contents of your new tab
- This view must subclass
DjangoView and use the mixin
- Implement the
render_to_fragment method which should render the content.
- See the Discussions tab example below to see how this works.
- Implement a full page view
You must render a mako template with the correct boilerplate to show the tabs correctly. An example would be as follows:
Be sure to fill in PAGE-SLUG and PAGE NAME with the correct slug and name for your new page. Replace
TEMPLATE_CODE with the Mako markup and code for the rest of the page.
- See the Teams tab example below to see how this works.
Fragment Example: Discussions tab
The Discussions feature renders its tab as a /wiki/spaces/ArchiveEng/pages/157888616. Here's how it works:
- the "Discussion" tab is defined here:
- it refers to the fragment view class
- the fragment's URL is declared here:
- the "Discussion" tab is then registered here:
Full Page Example: Teams tab
A simple example of a full Django View is the "Teams" tab. Here's how it gets added to the platform:
- there is a Teams Django app that provides the entire feature
- the "Teams" tab is defined in the file
- the tab is registered in the main
setup.py for the LMS
If your new tab isn't showing up, try the following:
- You can put a breakpoint in this method to see whether or not your tab type is being added:
- The method which returns all possible tab types is here:
If your new tab type isn't returned then that means that the entry point registration didn't work.
- Try the following:
- check that you registered your new tab in setup.py.
- If you added your new Django app into edx-platform, then add it here:
- make sure that you've increased the version number so that pip knows that it needs to reinstall
- try manually reinstalling the app. For an edx-platform extension, do the following in devstack:
sudo su edxapp
pip install -e /edx/app/edxapp/edx-platform