6.3. XBlock Fragments#

A fragment is a part of a web page returned by an XBlock view method.

6.3.1. Fragment Contents#

A fragment typically contains all the resources needed to display the XBlock in a web page, including HTML content, JavaScript, and CSS resources.

6.3.1.1. HTML Content#

Content in a fragment is typically HTML, though some runtimes might require views that return other mime-types. Each fragment has only a single content value.

6.3.1.2. JavaScript#

A fragment contains the JavaScript resources necessary to run the XBlock. JavaScript resources can include both external files to link to, and inline source code.

When fragments are composed, external JavaScript links are made unique, so that files are not loaded multiple times.

6.3.1.2.1. JavaScript Initializer#

The JavaScript specified for a fragment can also specify a function to be called when that fragment is rendered on the page.

The DOM element containing all of the content in the fragment is passed to this function, which then executes any code needed to make that fragment operational.

The JavaScript view is also passed a JavaScript runtime object that contains a set of functions to generate links back to the XBlock’s handlers and views on the runtime server.

For example, see the code in the Thumbs XBlock, in the file xblock_development/xblock- sdk/sample_xblocks/thumbs/static/js/source/thumbs.js.

function ThumbsAside(runtime, element, block_element, init_args) {
  return new ThumbsBlock(runtime, element, init_args);
}

function ThumbsBlock(runtime, element, init_args) {
  function updateVotes(votes) {
    $('.upvote .count', element).text(votes.up);
    $('.downvote .count', element).text(votes.down);
  }

  var handlerUrl = runtime.handlerUrl(element, 'vote');

  $('.upvote', element).click(function(eventObject) {
    $.ajax({
        type: "POST",
        url: handlerUrl,
        data: JSON.stringify({voteType: 'up'}),
        success: updateVotes
    });
  });

  $('.downvote', element).click(function(eventObject) {
    $.ajax({
        type: "POST",
        url: handlerUrl,
        data: JSON.stringify({voteType: 'down'}),
        success: updateVotes
    });
  });
  return {};
};

6.3.1.3. CSS#

A fragment contains CSS resources to control how the XBlock is displayed. CSS resources can include both external files to link to and inline source code.

When fragments are composed, external JavaScript links will are made unique, so that files are not loaded multiple times.

6.3.2. Fragments and XBlock Children#

Because XBlocks are nested hierarchically, a single XBlock view might require collecting renderings from each of its children, then composing them together. The parent XBlock view must handle composing its children’s content together to create the parent content.

The fragment system has utilities for composing children’s resources together into the parent.

6.3.3. Fragments and Views#

You configure fragments in XBlock view methods.

In the following example, the Thumbs sample XBlock in the XBlock SDK defines a student view that composes and returns a fragment with HTML, JavaScript, and CSS strings generated from the XBlock’s static files.

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