The XBlock python API is documented at http://edx.readthedocs.io/projects/xblock/en/latest/xblock.html
However, that documentation does not cover the many attributes, methods, mixins, and decorators that the Open edX LMS and Studio runtimes expect and use which are not inherited from the XBlock base class.
This wiki page aims to describe the Open edX specific API, to help XBlock authors.
This is a work in progress - please help expand / fix this documentation!
Open edX Python XBlock Complete API
Standard XBlock services
Decorate your XBlock with this to get access to the (limited) XBlock i18n features.
Within your XBlock views and handlers, you can use
to get translated text. This service should also be able to load translation files from the "translations" folder of your XBlock - see https://github.com/edx-solutions/xblock-drag-and-drop-v2/tree/master/drag_and_drop_v2/translations for an example.
The user service, which can be used to retrieve data about the user. TBD: What is its API?
The settings service, which can read XBlock-specific settings from the Django settings.
Deprecated. Only used by LibraryContentDescriptor (and library_tools.py).
Standard XBlock attributes/methods/views/handlers:
These are all attributes/methods that you can override/implement on an XBlock:
Boolean value: Can this problem be rescored? Default: True
The view used to preview this XBlock for instructors in Studio.
Defaults to `student_view` if an author_view is not defined.
If using `StudioContainerXBlockMixin`, do not implement this view directly,
but instead implement `author_edit_view` and `author_preview_view`.
Calculate a new raw score based on the state of the problem. This method should not modify the state of the XBlock. If implementing this, the XBlock should subclass ScorableXBlockMixin (see below).
The name of the XBlock as shown to students in various places in the LMS.
Should be an xblock.fields.String instance with a default value.
(TBD: There are subtle bugs if this is set to a fixed or is a @property, not a field?)
Should be an xblock.fields.DateTime - if this is a scorable XBlock with a due date.
Used in GradesTransformer among other places.
Returns True if the problem has been answered by the runtime user.
Return a `progress.Progress` object that represents how far the student has gone in this module. Must be implemented to get correct progress tracking behavior in nesting modules like sequence and vertical.
If this module has no notion of progress, return `None`.
Return the problem's current score as raw values. Should return a Score(raw_earned=float, raw_possible=float). If implementing this, the XBlock should subclass ScorableXBlockMixin (see below).
(Boolean) Whether or not this XBlock can have child XBlocks. Default: False
Return a boolean indicating whether or not the children of this XBlock may be different when seen by different users.
If this XBlock emits scores, this should be True. The recommended way to support scores is to subclass ScorableXBlockMixin (see below), which sets this attribute for you.
What icon to display next to the XBlock when it is the first XBlock in a unit.
Possible values: `problem`, ... ? TBD
If this XBlock emits a score, this method is required. It usually should return `1`, unless you want to emit a score such as '4/5', in which case this should return `5`.
TBD: If this is still required, why is it not part of ScorableXBlockMixin?
Calculate a new raw score and save it to the block. If only_if_higher is True and the score didn't improve, keep the existing score.
The recommended way to support scores is to subclass ScorableXBlockMixin (see below), which implements this method for you.
Persist a score to the XBlock. If implementing this, the XBlock should subclass ScorableXBlockMixin (see below).
The standard view used in the LMS and for mobile app webviews.
Should return a Fragment.
A regular method that can return a JSON-friendly python data object that mobile apps can use to render a native mobile UI for this XBlock. This method is called without being bound to any student, so it cannot access any specific student's state or field data.
The view used in Studio to display a UI for editing this XBlock's settings/data. Use StudioEditableXBlockMixin to generate this view automatically.
The title for any course unit that contains this XBlock as its top level item.
Defaults to the value of display_name_with_default.
Should be an `XBlock.fields.Float`, with default value of `1`.
This allows instructors to define the relative weight of this XBlock for grading purposes compared to other XBlocks in the same course section.
These attributes will get added to your XBlock automatically by the LMS. You should not override them, but you can use them.
TBD: Is this deprecated?
The type of this XBlock. Equivalent to `self.scope_ids.block_type`
The ID of the course. Equivalent to `self.scope_ids.usage_id.course_key`
Provides the `display_name` or a suitable default if the `display_name` is not defined.
See the XBlock API docs.
Return a child XBlock that matches the specified predicate function.
(`selector(child)` should return a boolean)
Returns list of content titles for all of self's children.
Returns true if self has children at the given depth. depth==0 returns
false if self is a leaf, true otherwise.
TBD: Is this deprecated?
The usage ID of this XBlock. Equivalent to `self.scope_ids.usage_id`
These are used for XModules but not XBlocks.
XBlocks use StudioEditableXBlockMixin which has a different API for specifying editable fields.
Useful XBlock Mixins:
Mixin to handle functionality related to scoring.
An XBlock mixin to provide a configuration UI for an XBlock in Studio.
If an XBlock allows children, this mixin makes it easier to implement support for displaying its
children in Studio.
If an XBlock allows children of specific types, this mixin makes it easier to implement support for editing its children in Studio.
Deprecated. XBlocks should just allow themes to override their appearance using SCSS. The recommended way to do this is to add a ".themeable-xblock" class to the XBlock's root element. Then ".themeable-xblock" can be added in the theme code to any CSS selector to increase its level of specificity by one and thus override the XBlock's styles.
In the LMS, these attributes/methods are defined and used internally and should generally not be used on your XBlock unless you understand their purpose. Some of these are also considered deprecated. Avoid declaring fields or attributes/methods with these names.
graded - used for subsections only, to indicate whether they are graded or not.