XBlock Methods#
You use XBlock methods in the XBlock Python file to define the behavior of your XBlock.
View Methods#
XBlock view methods are Python methods invoked by the XBlock runtime to render the XBlock.
An XBlock can have multiple view methods. For example, an XBlock might have a student view for rendering the XBlock for learners, and an editing view for rendering the XBlock to course staff.
Note
The XBlock view names are specified by runtime applications; you cannot use arbitrary view names.
For information about the view requirements in the edX Platform, see Open edX LMS and Open edX Studio.
Typically, you define a view to produce a fragment that is used to render the XBlock as part of a web page. Fragments are aggregated hierarchically. You can use any field to affect the rendering of the XBlock as needed.
In the following example, the Thumbs sample XBlock in the XBlock SDK defines a student view.
def student_view(self, context=None): # pylint: disable=W0613
"""
Create a fragment used to display the XBlock to a student.
`context` is a dictionary used to configure the display (unused)
Returns a `Fragment` object specifying the HTML, CSS, and JavaScript
to display.
"""
# Load the HTML fragment from within the package and fill in the template
html_str = pkg_resources.resource_string(
__name__,
"static/html/thumbs.html".decode('utf-8')
)
frag = Fragment(str(html_str).format(block=self))
# Load the CSS and JavaScript fragments from within the package
css_str = pkg_resources.resource_string(
__name__,
"static/css/thumbs.css".decode('utf-8')
)
frag.add_css(str(css_str))
js_str = pkg_resources.resource_string(
__name__,
"static/js/src/thumbs.js".decode('utf-8')
)
frag.add_javascript(str(js_str))
frag.initialize_js('ThumbsBlock')
return frag
Although view methods typically produce HTML-based renderings, they can be used for other purposes. See the documentation for your runtime application to verify the type of data the view must return and how it will be used.
Handler Methods#
You write handlers to implement the server side of your XBlock’s interactive features.
XBlock handlers are Python methods invoked by AJAX calls from the user’s browser. Handlers accept an HTTP request and return an HTTP response.
An XBlock can have any number of handlers. For example, a problem XBlock
might contain submit
and show_answer
handlers.
Each handler has a specific name of your choosing that is mapped to from
specific URLs by the runtime. The runtime provides a mapping from handler names
to specific URLs so that the XBlock JavaScript code can make requests to its
handlers. Handlers can be used with GET
and POST
requests.
Handler methods also emit events for learner interactions and grades. For more information, see When an XBlock Should Emit Events.
In the following example, the Thumbs sample XBlock in the XBlock SDK defines a handler for voting.
def vote(self, data, suffix=''): # pylint: disable=unused-argument
"""
Update the vote count in response to a user action.
"""
# Here is where we would prevent a student from voting twice, but then
# we couldn't click more than once in the demo!
#
# if self.voted:
# log.error("cheater!")
# return
if data['voteType'] not in ('up', 'down'):
log.error('error!')
return
if data['voteType'] == 'up':
self.upvotes += 1
else:
self.downvotes += 1
self.voted = True
return {'up': self.upvotes, 'down': self.downvotes}
Default Methods in a New XBlock#
When you create a new XBlock, two methods are added automatically.
The view method
student_view
.You can modify the contents of this view, but to use your XBlock with the edX Platform, you must keep the method name
student_view
.The handler method
increment_count
.This method is for demonstration purposes and you can remove it.