Notice: This repo will be moved to the openedx organization in April 2021.
Adventure XBlock is an XBlock for creating a simple chose your own adventure style simulation.
It presents the user with a branching sequence of steps,
each which can contain other XBlockLightChildrens.
Choosing a branch is mainly realized by selecting an option from a multiple choice question.
It also has the ability to embed other XBlockLightChildrens such as
html, video, etc.
Install the requirements into the python virtual environment of your
edx-platform installation by running the following command from the
root folder:
$ pip install -r requirements.txtYou can enable the XBlock in studio through the advanced settings.
- From the main page of a specific course, navigate to
Settings -> Advanced Settingsfrom the top menu. - Check for the
advanced_modulespolicy key, and add"adventure"to the policy value list. - Click the "Save changes" button.
When you add the Adventure component to a course in the studio, the
block is field with default XML content.
The various xml elements are explained below.
The wrapping <adventure> element can contain the following child
elements:
<title>- Renders the title of the block.<info>- Renders a shared info, it is displayed on every step, along with the title.<step>- A step of the adventure. A typical adventure has at least a couple of steps.
A step element represent a simple step of the adventure.
The <step> element has the following attributes:
-
name: The name of the step. It must be unique within an adventure, as this is how other steps refer to this one. The first step must be namedfirst. This is how the adventure block finds the initial step for the adventure. This is a mandatory attribute. -
back: The name of the previous step, for backtracking. This is an optional attribute. If missing, the controls for getting back to the previous step is disabled. -
next: The name of the next step. This is an optional attribute. If missing and a choice mechanism such as<mcq>is present, it means this is a choice step. If missing and there are no such mechanism present, it means this is (one of the) final step(s) of the adventure.
The <step> element can contain various XBlockLightChild elements and other XBlocks, such as
<html>, <title>, <mcq>, <ooyala-player>. To know more about them, see their documentation.
Of special interest is the <mcq> element, that can act as a selector for the next step.
In this case, the selected value of the choice must be a valid name for one of the steps.
Once selected, this choice will act the same way as if the step would have it as it's next attribute.
For a complete example, see the contents of the default adventure a new adventure unit defaults to in the Studio.
This repo offers multiple make targets to automate the translation tasks. Each make target will be explained below:
extract_translations. Usei18n_toolextract to create.pofiles based on all the tagged strings in the python and javascript code.compile_translations. Usei18n_toolgenerate to create.mocompiled files.detect_changed_source_translations. Usei18n_toolchanged to identify any updated translations.validate_translations. Compile translations and check the source translations haven't changed.
If you want to add a new language:
- Add language to
adventure/translations/config.yaml - Make sure all tagged strings have been extracted:
make extract_translations- Clone
endirectory toadventure/translations/<lang_code>/for example:adventure/translations/fa_IR/ - Make necessary changes to translation files headers. Make sure you have proper
LanguageandPlural-Formslines. - When you finished your modification process, re-compile the translation messages.
make compile_translationsSee general instructions on installing, using and testing XBlocks with the workbench.
When test are finish and working:
- Add tests for get_student_choice and save_student_choice (previous state saving)