You use XBlock fields to store state data for your XBlock.
XBlock fields are Python attributes that store user and XBlock state as JSON data.
You define the fields in the XBlock Python file. For example, the
file in the XBlock SDK includes three fields.
upvotes = Integer(
help="Number of up votes",
downvotes = Integer(
help="Number of down votes",
voted = Boolean(
help="Has this student voted?",
When you initialize an XBlock field, you define three parameters.
help: A help string for the field that can be used in an application such as edX Studio.
default: The default value for the field.
scope: The scope of the field. For more information, see the next section.
Field scope is the relationship of the field to users and the XBlock.
You define the field scope when initializing the field in the XBlock Python
file. For example, in
voted field is initialized to have
voted = Boolean(help="Has this student voted?", default=False,
Fields can relate to users in the following ways.
No user: the field data is not related to any users. No learner activity created modified the field value, and all learners see the same value.For example, a field that contains course content is independent of users.
The XBlock cannot modify the value of a field that is not related to any users.
One user: the field data is specific to a single user. For example, the answer to a problem is specific to the user who submitted it.
All users: the field data is common for all users. Learner activity can change the field value, and all learners see the same value. For example, the total number of learners who answer a question is the same for all users.
Field data related to all users is not the same as aggregate or query data. The same value is shared for all users, and you cannot associate specific actions to specific users.
Fields can relate to XBlocks in the following ways.
Block usage: the field data is related to an instance, or usage, of the XBlock in a particular course. In most cases, you use the Block usage scope. For example, for an XBlock that polls learners and shows totals for each response, you would need the question and available answers to be specific to that instance of the XBlock in your course.
Block definition: the field data is related to the definition of the XBlock. The definition is specified by the content creator. A definition can be shared across one or more uses. For example, you could create a single XBlock definition with many uses, and those uses can appear across courses or within the same course.
Block type: The field data is related to the Python type of the XBlock, and is shared across all instances of the XBlock in all courses.
All: The field data is related to all XBlocks, of all types. Any XBlock can access the field data.
When you use the All scope, there is potential for name conflicts. If you have two fields of the same name with the scope All in different XBlock types, both fields point to the same data. Therefore you should use caution when using All.
User and Block Scope Independence#
The user and block scope of a field are independent of each other. The field scope you define specifies both. The following examples show different ways you can combine user and block scope.
A user’s progress through a particular set of problems is stored in a field with the scope One user and XBlock usage.
The content to display in an XBlock is stored in a field with the scope No user and Block definition.
A user’s preferences for a type of XBlock are stored in a field with the scope with One user and XBlock type.
Information about the user, such as language or timezone, is stored in a field with the scope with One user and All.
Scope combinations that are used together frequently are available is a set of predefined scopes, as described below.
XBlock includes the following predefined scopes that you can use when configuring fields. Each of these scopes includes the indicated user and block scope settings.
Because XBlock fields are written and retrieved as single entities, you cannot store a large amount of data in a single field.
To store very large amounts of data, you should split the data across many smaller fields.
You do not use the
__init__ method with XBlocks.
XBlocks can be used in many contexts, and the
__init__ method might not
work in those contexts.
To initialize field values, use one of the following alternatives.
xblock.fields.UNIQUE_IDto set a default string value for the field.
Use a lazy property decorator, so that when a field is first accessed, a function is called to set the value.
Run the logic to set the default field value in the view instead of the
XBlock fields map to attributes in the OLX (open learning XML) definition.
For example, you might include the fields
maxheight in a
SimpleVideoBlock XBlock. You configure the fields as in
the following example.
An XBlock providing Embed capabilities for video
href = String(help="URL of the video page at the provider",
maxwidth = Integer(help="Maximum width of the video", default=800,
maxheight = Integer(help="Maximum height of the video", default=450,
By default, the
SimpleVideoBlock XBlock is represented in OLX as in the
You can customize the OLX representation of the XBlock by using the
When you create a new XBlock, the
count field is added to the Python file
by default. This field is for demonstration purposes and you should replace it
with your own field definitions.