Getting Started with the XBlock SDK#

This section describes how to get started with the XBlock SDK.

Clone the XBlock Software Development Kit#

The XBlock SDK is a Python application you use to help you build new XBlocks. The XBlock SDK contains three main components:

  • An XBlock creation tool that builds the skeleton of a new XBlock.

  • An XBlock runtime for viewing and testing your XBlocks during development.

  • Sample XBlocks that you can use as the starting point for new XBlocks, and for your own learning.

After you create and activate the virtual environment, you clone the XBlock SDK and install its requirements. To do this, complete the following steps at a command prompt.

  1. In the xblock_development directory, run the following command to clone the XBlock SDK repository from GitHub.

    (venv) $ git clone https://github.com/openedx/xblock-sdk.git

  2. In the same directory, create an empty directory called var.

    (venv) $ mkdir var

  3. Run the following command to change to the xblock-sdk directory.

    (venv) $ cd xblock-sdk

  4. Run the following commands to install the XBlock SDK requirements.

    (venv) $ make install

  5. Run the following command to return to the xblock_development directory, where you will perform the rest of your work.

    (venv) $ cd ..

Create an XBlock#

You use the XBlock SDK to create skeleton files for an XBlock. To do this, follow these steps at a command prompt.

  1. Change to the xblock_development directory, which contains the venv and xblock-sdk subdirectories.

  2. Run the following command to create the skeleton files for the XBlock.

    (venv) $ xblock-sdk/bin/workbench-make-xblock

    Instructions in the command window instruct you to determine a short name and a class name. Follow the guidelines in the command window to determine the names that you want to use.

    You will be prompted for two pieces of information:

* Short name: a single word, all lower-case, for directory and file
  names. For a hologram 3-D XBlock, you might choose "holo3d".

* Class name: a valid Python class name.  It's best if this ends with
  "XBlock", so for our hologram XBlock, you might choose
  "Hologram3dXBlock".

Once you specify those two names, a directory is created in the
``xblock_development`` directory containing the new project.

If you don't want to create the project here, or you enter a name
incorrectly, type Ctrl-C to stop the creation script.  If you don't want
the resulting project, delete the directory it created.

  3. At the command prompt, enter the Short Name you selected for your XBlock.

    $ Short name: myxblock

  4. At the command prompt, enter the Class name you selected for your XBlock.

    $ Class name: MyXBlock

The skeleton files for the XBlock are created in the myxblock directory. For more information about the XBlock files, see Anatomy of an XBlock.

Install the XBlock#

After you create the XBlock, you install it in the XBlock SDK.

In the xblock_development directory, use pip to install your XBlock.

(venv) $ pip install -e myxblock

You can then test your XBlock in the XBlock SDK.

Create the SQLite Database#

Before running the XBlock SDK the first time, you must create the SQLite database.

  1. In the xblock_development directory, run the following command to create the database and the tables.

    (venv) $ python xblock-sdk/manage.py migrate

  2. You are prompted to indicate whether or not to create a Django superuser.

    You just installed Django's auth system, which means you don't have any
superusers defined. Would you like to create one now? (yes/no):

  3. Enter no.

Run the XBlock SDK Server#

To see the web interface of the XBlock SDK, you must run the SDK server.

In the xblock_development directory, run the following command to start the server.

(venv) $ python xblock-sdk/manage.py runserver

Note

If you do not specify a port, the XBlock SDK server uses port 8000. To use a different port, specify it in the runserver command.

Then test that the XBlock SDK is running. In a browser, go to http://localhost:8000. You should see the following page.

The XBlock SDK home page.

The page shows the XBlocks installed automatically with the XBlock SDK. Note that the page also shows the MyXBlock XBlock that you created in Create Your First XBlock.

Get Help for the XBlock SDK Server#

To get help for the XBlock SDK runserver command, run the following command.

(venv) $ python xblock-sdk/manage.py help

The command window lists and describes the available commands.