openedx.core.djangoapps.xblock package

openedx.core.djangoapps.xblock package#

Subpackages#

Submodules#

openedx.core.djangoapps.xblock.api module#

Python API for interacting with edx-platform’s new XBlock Runtime.

For content in modulestore (currently all course content), you’ll need to use the older runtime.

Note that these views are only for interacting with existing blocks. Other Studio APIs cover use cases like adding/deleting/editing blocks.

openedx.core.djangoapps.xblock.api.get_block_display_name(block_or_key)#

Efficiently get the display name of the specified block. This is done in a way that avoids having to load and parse the block’s entire XML field data using its parse_xml() method, which may be very expensive (e.g. the video XBlock parse_xml leads to various slow edxval API calls in some cases).

This method also defines and implements various fallback mechanisms in case the ID can’t be loaded.

block_or_key can be an XBlock instance, a usage key or a definition key.

Returns the display name as a string

openedx.core.djangoapps.xblock.api.get_block_metadata(block, includes=())#

Get metadata about the specified XBlock.

This metadata is the same for all users. Any data which varies per-user must be served from a different API.

Optionally provide a list or set of metadata keys to include. Valid keys are:

index_dictionary: a dictionary of data used to add this XBlock’s content: to a search index.
student_view_data: data needed to render the XBlock on mobile or in: custom frontends.

children: list of usage keys of the XBlock’s children editable_children: children in the same bundle, as opposed to linked

children in other bundles.

openedx.core.djangoapps.xblock.api.get_handler_url(usage_key, handler_name, user)#

A method for getting the URL to any XBlock handler. The URL must be usable without any authentication (no cookie, no OAuth/JWT), and may expire. (So that we can render the XBlock in a secure IFrame without any access to existing cookies.)

The returned URL will contain the provided handler_name, but is valid for any other handler on the same XBlock. Callers may replace any occurrences of the handler name in the resulting URL with the name of any other handler and the URL will still work. (This greatly reduces the number of calls to this API endpoint that are needed to interact with any given XBlock.)

Params:: usage_key - Usage Key (Opaque Key object or string) handler_name - Name of the handler or a dummy name like ‘any_handler’ user - Django User (registered or anonymous)

This view does not check/care if the XBlock actually exists.

openedx.core.djangoapps.xblock.api.get_runtime_system()#

Get the XBlockRuntimeSystem, which is a single long-lived factory that can create user-specific runtimes.

The Runtime System isn’t always needed (e.g. for management commands), so to keep application startup faster, it’s only initialized when first accessed via this method.

openedx.core.djangoapps.xblock.api.load_block(usage_key, user)#

Load the specified XBlock for the given user.

Returns an instantiated XBlock.

Exceptions:

NotFound - if the XBlock doesn’t exist or if the user doesn’t have the: necessary permissions

Parameters:

usage_key (OpaqueKey) – block identifier
user (User) – user requesting the block

openedx.core.djangoapps.xblock.api.render_block_view(block, view_name, user)#

Get the HTML, JS, and CSS needed to render the given XBlock view.

The only difference between this method and calling: load_block().render(view_name)

is that this method can fall back from ‘author_view’ to ‘student_view’

Returns a Fragment.

openedx.core.djangoapps.xblock.api.resolve_definition(block_or_key)#: Given an XBlock, definition key, or usage key, return the definition key.

openedx.core.djangoapps.xblock.api.xblock_type_display_name(block_type)#: Get the display name for the specified XBlock class.

openedx.core.djangoapps.xblock.apps module#

Django app configuration for the XBlock Runtime django app

class openedx.core.djangoapps.xblock.apps.LmsXBlockAppConfig(app_name, app_module)#

Bases: XBlockAppConfig

LMS-specific configuration of the XBlock Runtime django app.

get_runtime_system_params()#: Get the XBlockRuntimeSystem parameters appropriate for viewing and/or editing XBlock content in the LMS

get_site_root_url()#: Get the absolute root URL to this site, e.g. ‘https://courses.example.com’ Should not have any trailing slash.

class openedx.core.djangoapps.xblock.apps.StudioXBlockAppConfig(app_name, app_module)#

Bases: XBlockAppConfig

Studio-specific configuration of the XBlock Runtime django app.

BLOCKSTORE_DRAFT_NAME = 'studio_draft'#

get_learning_context_params()#: Get additional kwargs that are passed to learning context implementations (LearningContext subclass constructors). For example, this can be used to specify that the course learning context should load the course’s list of blocks from the _draft_ version of the course in studio, but from the published version of the course in the LMS.

get_runtime_system_params()#: Get the XBlockRuntimeSystem parameters appropriate for viewing and/or editing XBlock content in Studio

get_site_root_url()#: Get the absolute root URL to this site, e.g. ‘https://studio.example.com’ Should not have any trailing slash.

class openedx.core.djangoapps.xblock.apps.XBlockAppConfig(app_name, app_module)#

Bases: AppConfig

Django app configuration for the new XBlock Runtime django app

get_learning_context_params()#: Get additional kwargs that are passed to learning context implementations (LearningContext subclass constructors). For example, this can be used to specify that the course learning context should load the course’s list of blocks from the _draft_ version of the course in studio, but from the published version of the course in the LMS.

get_runtime_system_params()#: Get the XBlockRuntimeSystem parameters appropriate for viewing and/or editing XBlock content.

get_site_root_url()#: Get the absolute root URL to this site, e.g. ‘https://courses.example.com’ Should not have any trailing slash.

label = 'xblock_new'#

name = 'openedx.core.djangoapps.xblock'#

verbose_name = 'New XBlock Runtime'#

openedx.core.djangoapps.xblock.apps.get_xblock_app_config()#: Get whichever of the above AppConfig subclasses is active.

openedx.core.djangoapps.xblock.data module#

Data structures for the XBlock Django app’s python APIs

class openedx.core.djangoapps.xblock.data.StudentDataMode(value)#

Bases: Enum

Is student data (like which answer was selected) persisted in the DB or just stored temporarily in the session? Generally, the LMS uses persistence and Studio uses ephemeral data.

Ephemeral = 'ephemeral'#

Persisted = 'persisted'#

openedx.core.djangoapps.xblock.utils module#

Useful helper methods related to the XBlock runtime

openedx.core.djangoapps.xblock.utils.get_secure_token_for_xblock_handler(user_id, block_key_str, time_idx=0)#

Get a secure token (one-way hash) used to authenticate XBlock handler requests. This token replaces both the session ID cookie (or OAuth bearer token) and the CSRF token for such requests.

The token is specific to one user and one XBlock usage ID, though may be used for any handler. It expires and is only valid for 2-4 days (our current best guess at a reasonable trade off between “what if the user left their browser open overnight and tried to continue the next day” which should work vs. “for security, tokens should not last too long”)

We use this token because XBlocks may sometimes be sandboxed (run in a client-side JavaScript environment with no access to cookies) and because the XBlock python and JavaScript handler_url APIs do not provide any way of authenticating the handler requests, other than assuming cookies are present or including this sort of secure token in the handler URL.

For security, we need these tokens to have an expiration date. So: the hash incorporates the current time, rounded to the lowest TOKEN_PERIOD value. When checking this, you should check both time_idx=0 and time_idx=-1 in case we just recently moved from one time period to another (i.e. at the stroke of midnight UTC or similar). The effect of this is that each token is valid for 2-4 days.

(Alternatively, we could make each token expire after exactly X days, but that requires storing the expiration date of each token on the server side, making the implementation needlessly complex. The “time window” approach we are using here also has the advantage that throughout a typical day, the token each user gets for a given XBlock doesn’t change, which makes debugging and reasoning about the system simpler.)

openedx.core.djangoapps.xblock.utils.get_xblock_id_for_anonymous_user(user)#

Get a unique string that identifies the current anonymous (not logged in) user. (This is different than the “anonymous user ID”, which is an anonymized identifier for a logged in user.)

Note that this ID is a string, not an int. It is guaranteed to be in a unique namespace that won’t collide with “normal” user IDs, even when they are converted to a string.

openedx.core.djangoapps.xblock.utils.validate_secure_token_for_xblock_handler(user_id, block_key_str, token)#

Returns True if the specified handler authentication token is valid for the given Xblock ID and user ID. Otherwise returns false.

See get_secure_token_for_xblock_handler

Module contents#

The new XBlock runtime and related code.