Developing

This code runs on Python 3.12 or newer.

# Clone the repository
git clone git@github.com:openedx/xblock-sdk.git
cd xblock-sdk

# Set up a virtualenv with the same name as the repo and activate it
# Here's how you might do that if you have virtualenvwrapper setup.
mkvirtualenv -p python3.12 xblock-sdk

# Install system requirements needed to run this on ubuntu.
# Note: Debian 10 needs libjpeg62-turbo-dev instead of libjpeg62-dev.
sudo apt-get install python-dev libxml2-dev libxslt-dev lib32z1-dev libjpeg62-dev

$ make test

$ make test-all

$ make quality

$ make coverage

Deploying

This repository is deployed to PyPI. To deploy a new version.

1. Bump the version of the package in workbench/__init__.py

2. Make a new release in github or push a new tag up to Github.

The pypi-publish github action should trigger. It will build and deploy the source and wheel package to PyPI.

Documentation

Start by going through the documentation. If you need more help see below.

More Help

If you’re having trouble, we have discussion forums at https://discuss.openedx.org where you can connect with others in the community.

Our real-time conversations are on Slack. You can request a Slack invitation, then join our community Slack workspace.

For anything non-trivial, the best path is to open an issue in this repository with as many details about the issue you are facing as you can provide.

https://github.com/openedx/xblock-sdk/issues

For more information about these options, see the Getting Help page.

Using the workbench

When you open the workbench, you’ll see a list of sample XBlock configurations (scenarios). Each will display a page showing the XBlocks composited together, along with internal information like the “database” contents.

The workbench database defaults to a sqlite3 database. If you’re using devstack, you may want to set WORKBENCH_DATABASES to point to your MySQL db.

If you want to experiment with different students, you can use a URL parameter to set the student ID, which defaults to 1:

http://127.0.0.1:8000/?student=17

Different students will see different student state, for example, while seeing the same content. The default student ID contains only digits but it is not necessary to limit student IDs to digits. Student IDs are represented as strings.

Making your own XBlock

Making an XBlock involves creating a Python class that conforms to the XBlock specification. See the sample_xblocks directory for examples and the XBlock tutorial for a full walk-through.

We provide a script to create a new XBlock project to help you get started. Run bin/workbench-make-xblock in a directory where you want to create your XBlock project. The script will prompt you for the name of the XBlock, and will create a minimal working XBlock, ready for you to begin development.

You can provide scenarios for the workbench to display: see the thumbs.py sample for an example, or the xblock/problem.py file. The scenarios are written in a simple XML language. Note this is not an XML format we are proposing as a standard.

Once you install your XBlock into your virtualenv, the workbench will automatically display its scenarios for you to experiment with.

If you are interested in making an XBlock to run for your course on edx.org, please get in touch with us as soon as possible – in the ideation and design phase is ideal. See our XBlock review guidelines for more information (note that this is not needed for XBlocks running on your own instance of Open edX, or released to the wider community).

Example XBlocks

Included in this repository are some example XBlocks that demonstrate how to use various aspects of the XBlock SDK. You can see a more detailed description of those examples in the README located in that repository:

There is a rich community of XBlock developers that have put together a large number of XBlocks that have been used in various contexts, mostly on the edx-platform. You can see examples of what that community has done in the edx-platform wiki.