4.1. The XBlock Python File#

This section of the tutorial walks through the Python file, thumbs.py, for the Thumbs XBlock example in the XBlock SDK.

If you completed the steps in Build an XBlock: Quick Start, you can find this file locally at xblock_development/xblock-sdk/sample_xblocks/thumbs/thumbs.py.

In the XBlock Python file, you define fields, views, handlers, and workbench scenarios.

4.1.1. Thumb XBlock Fields#

The thumbs.py file defines the following fields for the XBlock in the ThumbsBlockBase class.

class ThumbsBlockBase(object):
    upvotes = Integer(help="Number of up votes", default=0,
        scope=Scope.user_state_summary)
    downvotes = Integer(help="Number of down votes", default=0,
        scope=Scope.user_state_summary)
    voted = Boolean(help="Has this student voted?", default=False,
        scope=Scope.user_state)

Note the following details about the fields in the Thumbs XBlock.

  • upvotes and downvotes store the cumulative up and down votes of users.

    These fields have the scope Scope.user_state_summary. This indicates that the data in these fields are specific to the XBlock and the same for all users.

  • voted stores whether the user has voted. This field has the scope Scope.user_state. This indicates that the data in this field applies to the XBlock and to the specific user.

For more information, see XBlock Fields.

4.1.2. Thumb XBlock Student View#

The thumbs.py file defines the student view for the XBlock in the ThumbsBlockBase class.

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")
    frag = Fragment(unicode(html_str).format(self=self))

    # Load the CSS and JavaScript fragments from within the package
    css_str = pkg_resources.resource_string(__name__, "static/css/thumbs.css")
    frag.add_css(unicode(css_str))

    js_str = pkg_resources.resource_string(__name__,
                                           "static/js/src/thumbs.js")
    frag.add_javascript(unicode(js_str))

    frag.initialize_js('ThumbsBlock')
    return frag

The student view composes and returns the fragment from static HTML, JavaScript, and CSS files. A web page displays the fragment to learners.

Note the following details about student view.

  • The static HTML content is added when the fragment is initialized.

    html_str = pkg_resources.resource_string(__name__, "static/html/thumbs.html")
    frag = Fragment(unicode(html_str).format(self=self))
    
  • The JavaScript and CSS file contents are added to the fragment with the add_javascript() and add_css methods.

  • The JavaScript in the fragment must be initialized using the name of the XBlock class. The name also maps to the function that initializes the XBlock in the JavaScript file.

    frag.initialize_js('ThumbsBlock')
    

For more information, see View Methods.

4.1.3. Thumb XBlock Vote Handler#

The thumbs.py file defines a handler that adds a user’s vote to the XBlock.

@XBlock.json_handler
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}

Note the following details about the vote handler.

  • The upvotes or downvotes fields are updated based on the user’s vote.

  • The voted field is set to True for the user.

  • The updated upvotes and downvotes fields are returned.

For more information, see Handler Methods.