branching-xblock 0.3.0

Features

• Interactive Decision Trees: Create multi-path scenarios with branching narratives

• Rich Media Support: Include images, videos, and formatted text in scenarios

• Choice Feedback: Provide immediate feedback and hints for each decision point

• Undo Functionality: Allow learners to backtrack through their choices (optional)

• Scoring Integration: Award points for completed scenarios (optional)

• Completion Tracking: Monitor learner progress through the scenario

• Studio Editor: Visual editor for creating and managing branching scenarios

• Internationalization: Support for multiple languages

Installation

Install the XBlock within your Open EdX instance:

git clone https://github.com/open-craft/branching-xblock.git
cd branching-xblock
pip install -e .

Then add it to your advanced component list in Studio:

ADVANCED_COMPONENT_TYPES = [
    # ... other components
    'branching_xblock',
]

Usage

Frontend development

The Studio editor and learner views are built with React + TypeScript (in frontend/) and bundled with webpack. The compiled bundles are committed under branching_xblock/static/bundles/ and are what the XBlock serves at runtime, so they must be rebuilt and committed whenever frontend code changes.

# Backend dev requirements. This installs pydantic-to-typescript, which
# provides the `pydantic2ts` command used by the frontend type generation.
pip install -r requirements/dev.txt

# Frontend (Node) dependencies
cd frontend
npm ci

cd frontend
npm run build      # generate TS types from Pydantic models, then build bundles
npm run watch      # rebuild on change during development
npm test           # run the Jest unit tests

Testing with Docker

This XBlock comes with a Docker test environment ready to build, based on the xblock-sdk workbench. To build and run it:

make dev.run

The XBlock SDK Workbench, including this XBlock, will be available on the list of XBlocks at http://localhost:8000

Site-config authoring help

Admins can optionally provide a help/instructions HTML snippet shown to authors in the Studio editor (as a collapsible help block in the settings panel).

• Configure this in Django SiteConfiguration site_values under the key branching_xblock:

  {
    "branching_xblock": {
      "AUTHORING_HELP_HTML": "<p>You can use basic HTML in node content…</p>"
    }
  }

• This value is sanitized server-side (via bleach when available). Allowed tags: p, br, strong, b, em, u, code, h3, h4, h5, h6, hr, ul, ol, li, a. Allowed attributes: links permit href, title, target, rel.

Translating

Internationalization (i18n) is when a program is made aware of multiple languages. Localization (l10n) is adapting a program to local language and cultural habits.

Use the locale directory to provide internationalized strings for your XBlock project. For more information on how to enable translations, visit the Enabling Translations on a New Repo.

This cookiecutter template uses django-statici18n to provide translations to static javascript using gettext.

The included Makefile contains targets for extracting, compiling and validating translatable strings. The general steps to provide multilingual messages for a Python program (or an XBlock) are:

1. Mark translatable strings.

2. Run i18n tools to create raw message catalogs.

3. Create language specific translations for each message in the catalogs.

4. Use gettext to translate strings.

from django.utils.translation import ugettext as _

# Translators: This comment will appear in the `.po` file.
message = _("This will be marked.")

// Translators: This comment will appear in the `.po` file.
var message = gettext("Custom message.");

make extract_translations

#  translator-comments
A. extracted-comments
#: reference…
#, flag…
#| msgid previous-untranslated-string
msgid 'untranslated message'
msgstr 'mensaje traducido (translated message)'

$ make pull_translations

make compile_translations

make detect_changed_source_translations

Troubleshooting

If there are any errors compiling .po files run the following command to validate your .po files:

make validate

See django’s i18n troubleshooting documentation for more information.

Unreleased

0.3.0 – 2026-07-21

Added

• Content-search (Meilisearch) support: node content and image alt texts are indexed via index_dictionary.

0.2.0 – 2026-04-28

Added

• Import/export functionality.

0.1.3 – 2026-03-12

Changed

• Refactor the Branching XBlock to support Ren’Py-like flow features.

• Replace hint settings with a reset option.

• Update styling and related tests.

0.1.0 – 2025-04-15

Added

• First release on PyPI.