148 lines
5.7 KiB
ReStructuredText
148 lines
5.7 KiB
ReStructuredText
Integrating XBlocks with edx-platform
|
|
=====================================
|
|
|
|
The edX LMS and Studio have several features that are extensions of the core XBlock
|
|
libraries (https://xblock.readthedocs.org). These features are listed below.
|
|
|
|
* `LMS`_
|
|
* `Studio`_
|
|
* `Testing`_
|
|
* `Deploying your XBlock`_
|
|
|
|
LMS
|
|
---
|
|
|
|
Runtime Features
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
These are properties and methods available on ``self.runtime`` when a view or handler is executed by the LMS.
|
|
|
|
* anonymous_student_id: An identifier unique to the student in the particular course
|
|
that the block is being executed in. The same student in two different courses
|
|
will have two different ids.
|
|
|
|
* publish(block, event_type, event): Emit events to the surrounding system. Events are dictionaries that can contain arbitrary data.
|
|
XBlocks can publish events by calling ``self.runtime.publish(self, event_type, event)``. The ``event_type`` parameter
|
|
enables downstream processing of the event since it uniquely identifies the schema. This call will cause the runtime
|
|
to save the event data in the application event stream. XBlocks should publish events whenever a significant state
|
|
change occurs. Post-hoc analysis of the event stream can yield insight about how the XBlock is used in the context of
|
|
the application. Ideally interesting state of the XBlock could be reconstructed at any point in history through
|
|
careful analysis of the event stream.
|
|
|
|
TODO: Link to the authoritive list of event types.
|
|
|
|
In the future, these are likely to become more formal XBlock services (one related to users,
|
|
and the other to event publishing).
|
|
|
|
Class Features
|
|
~~~~~~~~~~~~~~
|
|
|
|
These are class attributes or functions that can be provided by an XBlock to customize behaviour
|
|
in the LMS.
|
|
|
|
* student_view (XBlock view): This is the view that will be rendered to display the XBlock
|
|
in the LMS. It will also be used to render the block in "preview" mode in Studio, unless
|
|
the XBlock also implements author_view.
|
|
* has_score (class property): True if this block should appear in the LMS progress page.
|
|
* get_progress (method): See documentation in x_module.py:XModuleMixin.get_progress.
|
|
* icon_class (class property): This can be one of (``other``, ``video``, or ``problem``), and
|
|
determines which icon appears in edx sequence headers. There is currently no way to provide
|
|
a different icon.
|
|
|
|
Grading
|
|
~~~~~~~
|
|
|
|
To participate in the course grade, an XBlock should set ``has_score`` to ``True``, and
|
|
should ``publish`` a ``grade`` event whenever the grade changes. The ``grade`` event is a
|
|
dictionary of the following form::
|
|
|
|
{
|
|
'value': <number>,
|
|
'max_value': <number>,
|
|
'user_id': <number>,
|
|
}
|
|
|
|
The grade event represents a grade of ``value/max_value`` for the current user. The
|
|
``user_id`` field is optional, the currently logged in user's ID will be used if it is
|
|
omitted.
|
|
|
|
Restrictions
|
|
~~~~~~~~~~~~
|
|
|
|
* A block can't modify the value of any field with a scope where the ``user`` property
|
|
is ``UserScope.NONE``.
|
|
|
|
Studio
|
|
------
|
|
|
|
Class Features
|
|
~~~~~~~~~~~~~~
|
|
|
|
* studio_view (XBlock.view): The view used to render an editor in Studio. The editor rendering can be completely different from the LMS student_view, and it is only shown when the author selects "Edit".
|
|
|
|
* author_view (XBlock.view): An optional view of the XBlock similar to student_view, but with possible inline editing capabilities. This view differs from studio_view in that it should be as similar to student_view as possible. When previewing XBlocks within Studio, Studio will prefer author_view to student_view.
|
|
|
|
* non_editable_metadata_fields (property): A list of ``xblock.fields.Field`` objects that shouldn't be displayed in the default editing view for Studio.
|
|
|
|
Restrictions
|
|
~~~~~~~~~~~~
|
|
|
|
* A block can't modify the value of any field with a scope where the ``user`` property
|
|
is not ``UserScope.NONE``.
|
|
|
|
|
|
Testing
|
|
-------
|
|
|
|
These instructions are temporary. Once XBlocks are fully supported by edx-platform
|
|
(both the LMS and Studio), installation and testing will be much more straightforward.
|
|
|
|
To enable an XBlock for testing in your devstack (https://github.com/edx/configuration/wiki/edX-Developer-Stack):
|
|
|
|
#. Install your block::
|
|
|
|
$ vagrant ssh
|
|
vagrant@precise64:~$ sudo -u edxapp /edx/bin/pip.edxapp install /path/to/your/block
|
|
|
|
#. Enable the block
|
|
|
|
#. In ``edx-platform/lms/envs/common.py``, uncomment::
|
|
|
|
# from xmodule.x_module import prefer_xmodules
|
|
# XBLOCK_SELECT_FUNCTION = prefer_xmodules
|
|
|
|
#. In ``edx-platform/cms/envs/common.py``, uncomment::
|
|
|
|
# from xmodule.x_module import prefer_xmodules
|
|
# XBLOCK_SELECT_FUNCTION = prefer_xmodules
|
|
|
|
#. In ``edx-platform/cms/envs/common.py``, change::
|
|
|
|
'ALLOW_ALL_ADVANCED_COMPONENTS': False,
|
|
|
|
to::
|
|
|
|
'ALLOW_ALL_ADVANCED_COMPONENTS': True,
|
|
|
|
#. Add the block to your courses' advanced settings in Studio
|
|
|
|
#. Log in to Studio, and open your course
|
|
#. Settings -> Advanced Settings
|
|
#. Change the value for the key ``"advanced_modules"`` to ``["your-block"]``
|
|
|
|
#. Add your block into your course
|
|
|
|
#. Edit a unit
|
|
#. Advanced -> your-block
|
|
|
|
Note the name ``your-block`` used in Studio must exactly match the key you used to add your
|
|
block to your ``setup.py`` ``entry_points`` list (if you are still discovering Xblocks and simply used the ``startnew.py`` script as described at https://github.com/edx/XBlock/blob/master/doc/getting_started.rst , look in the ``setup.py`` file that was created)
|
|
|
|
|
|
Deploying your XBlock
|
|
---------------------
|
|
|
|
To deploy your block to your own hosted version of edx-platform, you need to install it
|
|
into the virtualenv that the platform is running out of, and add to the list of ``ADVANCED_COMPONENT_TYPES``
|
|
in ``edx-platform/cms/djangoapps/contentstore/views/component.py``.
|