Skip to content

XBlock Development

Information on XBlocks, how to develop them, write effective tests, and conform to coding standards.

Introduction

XBlocks are python libraries used to provide custom course units for learners and instructors on the Open edX platform.

Resources

Online resources include:

Prerequisites

XBlocks are written in python, and so all the guides (including this one) assume that you have a basic understanding of how to write python, Javascript, HTML, and CSS.

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

Follow the instructions there to create a new XBlock, and to set up a docker XBlock development and testing environment. If you don't wish to use docker, you can set up the XBlock SDK manually.

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.

Docker devstack

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
$ make lms-shell

$ pip install -e /path/to/your/xblock

Install in Studio

1
2
3
$ make studio-shell

$ pip install -e /path/to/your/xblock

Testing

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.

Coding standards

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.

  • All python dependencies listed in requirements files, e.g. requirements.txt, test_requirements.txt

  • 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.

  • 100% quality report from pylint and pep8.

  • Minimum 80% code coverage.

Writing good code

The Open edX Developer's Guide contains a number of resources on this topic:

Automated tools

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

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

pep8 is another tool for checking python coding standards.

See xblock-lti-consumer's .pep8 for an example configuration file, and quality.sh for an example of how to run pep8.

coverage

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.

See xblock-lti-consumer's .coveragerc for an example configuration file, and test.sh for an example of how to run python tests with coverage enabled.

Deployment and Release management

Installation

Because XBlocks are just python libraries, they can be installed using standard the standard pip install tool, using a github repository URL and revision.

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.

Use tags

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.