An Open edX plugin showcasing a curated collection of code samples for extending and modifying the stock functionality of an Open edX installation using the built-in plugin architecture. This plugin can be installed in any Open edX installation version Juniper or later, independent of the installation method. This plugin currently runs in native builds, tutor installations, and Cookiecutter-openedx Kubernetes, amongst other proprietary installation methodologies.
Open edX official documentation recommends that you leverage its plugin architecture rather than fork its code repositories. This project provides more than two dozen code examples to help you accomplish this.
Usage:
pip install openedx-plugin-example
Technical features and coding techniques that are showcased in this repo include:
Demonstrates how to create an all-in-one Open edX plugin, with a heterogeneous collection of custom feature additions, including:
Implements a full-featured REST API which is built from snippets of Open edX's built-in rest api libraries. Demonstrates the following:
Implements a custom course audit report in Course Management Studio that depends on a backend Python process to iterate the course content. This process is highly instructive about the Open edX course object hierarchy. This plugin demonstrates the following:
Implements a modified version of the Open edX LMS Mobile REST API. This plugin illustrates best practices for modifying edx-platform source code without actually forking this repository. Demonstrates the following:
See Installing extra xblocks and requirements
tutor config save # to ensure that tutor's root folder system has been created
echo "openedx-plugin-example" >> "$(tutor config printroot)/env/build/openedx/requirements/private.txt"
tutor images build openedx
tutor local launch
# you'll also need to run this on your very first install
# -----------------------------------------------------------------------------
# 1. run migrations
tutor local run lms ./manage.py lms makemigrations
tutor local run lms ./manage.py lms migrate
tutor local run cms ./manage.py cms makemigrations
tutor local run cms ./manage.py cms migrate
# 2. add configuration data to custom models
tutor local run lms ./manage.py lms openedx_plugin_init
tutor local run lms ./manage.py lms openedx_plugin_api_init
tutor local run lms ./manage.py lms openedx_plugin_mobile_api_init
tutor local run cms ./manage.py cms openedx_plugin_cms_init
Each of these four Open edX plugins use django-waffle to toggle features on and off. While edx-platform also uses waffle switches, you should note that they separately manage a wrapper project named edx-toggles, and therefore the source code in this repo interacts with both of these.
Waffle switches in each of these four plugins are automatically initialized. You'll therefore find the switches in the LMS Django Admin console (admin/waffle/switch/) of your Open edX installation. Additionally, you'll find the raw MySL database records in the waffle_switch table
Look for app startup entries in the LMS app log for diagnostics information about the state of each waffle switch
Documentation is available here: Documentation
To get community support, go to the official Open edX discussion forum: https://discuss.openedx.org.
We welcome contributions! openedx-plugin-example is part of the cookiecutter-openedx project. Pull requests are welcome in all repos belonging to this organization. You can also contact Lawrence McDaniel directly.
# Run these from within your edx-platform virtual environment
python3 -m venv venv
source venv/bin/activate
cd /path/to/edx-platform
pip install -r requirements/edx/base.txt
pip install -r requirements/edx/coverage.txt
pip install -r requirements/edx/development.txt
pip install -r requirements/edx/pip-tools.txt
pip install -r requirements/edx/testing.txt
pip install -r requirements/edx/doc.txt
pip install -r requirements/edx/paver.txt
pip install pre-commit black flake8
pre-commit install
black
on modified code before committing.flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
pre-commit run --all-files
before pushing. see: https://pre-commit.com/To avoid freaky version conflicts in prod it's a good idea to install all of the edx-platform requirements to your local dev virtual environment.
At a minimum this will give you the full benefit of your IDE's linter.