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

@XBlock.needs("i18n")

Decorate your XBlock with this to get access to the (limited) XBlock i18n features.

Within your XBlock views and handlers, you can use

self.runtime.service(self, "i18n").ugettext(text)

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.

@XBlock.wants("user")

The user service, which can be used to retrieve data about the user. TBD: What is its API?

@XBlock.wants("settings")

The settings service, which can read XBlock-specific settings from the Django settings.
TBD: Can XBlocks just read django settings directly?

@XBlock.wants("studio_user_permissions")

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:

allows_rescore(self):

Boolean value: Can this problem be rescored? Default: True

author_view(self, context):

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_score(self):

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).

display_name

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?)

due

Should be an xblock.fields.DateTime - if this is a scorable XBlock with a due date.

Used in GradesTransformer among other places.

has_submitted_answer(self):

Returns True if the problem has been answered by the runtime user.

def get_progress(self):

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`.
Default: None

get_score(self):

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).

has_children

(Boolean) Whether or not this XBlock can have child XBlocks. Default: False

has_dynamic_children(self):

Return a boolean indicating whether or not the children of this XBlock may be different when seen by different users.
Default: false

has_score

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.

icon_class

What icon to display next to the XBlock when it is the first XBlock in a unit.
Possible values: `problem`, ... ? TBD

max_score(self):

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?

rescore(self, only_if_higher):

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.

set_score(self, score):

Persist a score to the XBlock. If implementing this, the XBlock should subclass ScorableXBlockMixin (see below).

student_view(self, context):

The standard view used in the LMS and for mobile app webviews.
Should return a Fragment.

student_view_data(self):

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.

studio_view(self, context):

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.

weight

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.

Automatic attributes:

These attributes will get added to your XBlock automatically by the LMS. You should not override them, but you can use them.

course_id

The ID of the course. Equivalent to `self.scope_ids.usage_id.course_key`

display_name_with_default

Provides the `display_name` or a suitable default if the `display_name` is not defined.

displayable_items

???

get_child

See the XBlock API docs.

get_child_by(self, selector)

Return a child XBlock that matches the specified predicate function.
(`selector(child)` should return a boolean)

get_content_titles

Returns list of content titles for all of self's children.

has_children_at_depth(self, depth):

Returns true if self has children at the given depth. depth==0 returns
false if self is a leaf, true otherwise.

location

TBD: Is this deprecated?
The usage ID of this XBlock. Equivalent to `self.scope_ids.usage_id`

editable_metadata_fields
non_editable_metadata_fields

These are used for XModules but not XBlocks.
XBlocks use StudioEditableXBlockMixin which has a different API for specifying editable fields.

Useful XBlock Mixins:

ScorableXBlockMixin

Mixin to handle functionality related to scoring.

StudioEditableXBlockMixin

An XBlock mixin to provide a configuration UI for an XBlock in Studio.

StudioContainerXBlockMixin

If an XBlock allows children, this mixin makes it easier to implement support for displaying its
children in Studio.

StudioContainerWithNestedXBlocksMixin

If an XBlock allows children of specific types, this mixin makes it easier to implement support for editing its children in Studio.

ThemableXBlockMixin

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.

Reserved/Internal attributes/methods:

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.

```
add_aside
```
```
bind_for_student
```
```
get_asides
```
```
get_child_descriptors
```
```
get_content_titles
```
```
get_explicitly_set_fields_by_scope 
```
```
get_required_module_descriptors
```

graded - used for subsections only, to indicate whether they are graded or not.

```
explicit_graded
```
```
system
```
```
xblock_kvs
```

Open edX JavaScript XBlock Complete API

TBD: Is there any LMS-specific JavaScript API?

It is partially documented at http://edx.readthedocs.io/projects/xblock-tutorial/en/latest/concepts/runtimes.html#javascript-runtimes but that doesn't show how to pass json_args to initialize_js nor explain the suffix/query params of handlerUrl.

Open edX Runtime XBlock API