Information on XBlocks, how to develop them, write effective tests, and conform to coding standards.
XBlocks are python libraries used to provide custom course units for learners and instructors on the Open edX platform.
Online resources include:
Open edX XBlock Tutorial: the best source of information on XBlocks and how to develop them. Particularly useful sections are:
Open edX XBlocks Directory: list of existing XBlocks, their support status, and links to their code and maintainers.
Quote of the Day XBlock: example built for Eugeny's XBlock tutorial for the Open edX Conference 2017.
Open edX Developer's Guide: guidelines for developers on the Open edX platform.
You do not need to know everything about the Open edX platform to write XBlocks, or to start the tutorial, but some basic understanding of the LMS and the Studio editor are useful.
We also use git for source code management, and to deploy XBlocks to Open edX environments. See github's Hello World page for how to start using git.
Creating a new XBlock¶
edX provides a template for creating new XBlocks: https://github.com/edx/cookiecutter-xblock
Once you have an XBlock created, use git to share it to a public repository so that it can be used and installed on your Open edX deployments.
Running XBlock in Open edX¶
If you have a devstack set up for Open edX, you can install your XBlock there and run it inside your LMS/Studio environment.
The XBlock Tutorial has not yet been updated to cover development in docker devstacks, but the concepts are similar.
In docker however, you need to be sure to install the same version of your XBlock in both the LMS and Studio, since these services do not share virtual environments.
Install in LMS¶
1 2 3
Install in Studio¶
1 2 3
Writing automated tests protects your XBlock's functionality against breaking changes as your project evolves. It also provides examples of how you expect your XBlock to be used.
Quote of the Day XBlock: good example of how to write unit tests, with quality and code coverage.
XBlock-SDK: Testing: details how to run code coverage and automated tests in the SDK workbench.
Automated Tools: section below provides information on how to measure and manage code quality.
Translations and Internationalization¶
Whenever your XBlock displays text to a learner or instructor, use the gettext utilities to mark the text, and to extract these text strings for translating.
The EDX Platform supports internationalization out of the box, but there is some specifics you need to be aware of. Please see XBlock Tutorial: Internationalization Support. Also, make sure to go over the open edX Developer Resources: Internationalization Coding Guidelines.
Edx's XBlock Cookiecutter template was an example implementation for a basic XBlock with internationalization support. This template demonstrated multiple Make targets to simplify the process; see README.md for details.
A good XBlock will have:
A README file which describes what the XBlock does, how to install it, and how to run its tests, and screenshots to display how the XBlock works.
A setup file to allow the XBlock to be packaged and installed by pip, e.g. setup.py
A conf/locale directory containing extracted learner- or instructor-facing text for translation, e.g. problem-builder/conf/locale
Automated tests to validate functionality.
Minimum 80% code coverage.
Writing good code¶
The Open edX Developer's Guide contains a number of resources on this topic:
Python provides a several tools to assist with maintaining coding standards, quality, and test coverage.
See xblock-lti-consumer for an example of how to use these tools.
pylint is a tool which looks for programming errors and checks python coding standards.
See xblock-lti-consumer's pylintrc for an example configuration file, and quality.sh for an example of how to run pylint. The edx-platform pylintrc file is much more extensive, but is a good guide to use for more complex configuration.
pep8 is another tool for checking python coding standards.
coverage is a python tool which counts the lines of code that are run when a set of tests run, and provides a detailed report of what percentage of the code is tested, and which lines are missing.
Deployment and Release management¶
Because XBlocks are just python libraries, they can be installed using standard the standard pip install tool, using a github repository URL and revision.
Standard XBlocks are listed in the github requirements file, and installed during edxapp setup.
Non-standard XBlocks are installed via configuration, by adding the pip requirement to the list of EDXAPP_EXTRA_REQUIREMENTS.
Use pull requests¶
To update your XBlock, create a pull request, so that your changes can be reviewed and tested before they are merged.
Each pull request should have:
title: summary of the change
Description of the change and its purpose
Detailed instructions for how to test the change in the LMS/Studio.
Updated automated tests to validate the code change.
To get your pull request reviewed, mention one or more developers who know about your project, and ask for a review.
The best way to manage releases of different versions of your XBlock is to mark each release with a git tag. For example, OpenCraft's problem-builder uses tags to mark the different versions available, and then installs them using pip from a github URL using the specific tag.