Package: xblock-openedx-utils
xblock-utils: Various utilities for XBlocks===========================================These are a collection of useful utility functions,test base classes and documentation shared by many XBlocks.(Especially those of `edx-solutions`_.).. _edx-solutions: https://github.com/edx-solutionsTo test the utilities, run::python run_tests.pyTo get a coverage report, use:python run_tests.py --with-coverage --cover-package=xblockutils --cover-htmlStudioEditableXBlockMixin-------------------------.. code:: pythonfrom xblockutils.studio_editable import StudioEditableXBlockMixinThis mixin will automatically generate a working ``studio_view`` formthat allows content authors to edit the fields of your XBlock. To use,simply add the class to your base class list, and add a new class fieldcalled ``editable_fields``, set to a tuple of the names of the fieldsyou want your user to be able to edit... code:: python@XBlock.needs("i18n")class ExampleBlock(StudioEditableXBlockMixin, XBlock):...mode = String(display_name="Mode",help="Determines the behaviour of this component. Standard is recommended.",default='standard',scope=Scope.content,values=('standard', 'crazy'))editable_fields = ('mode', 'display_name')That's all you need to do. The mixin will read the optional``display_name``, ``help``, ``default``, and ``values`` settings fromthe fields you mention and build the editor form as well as an AJAX savehandler.If you want to validate the data, you can override``validate_field_data(self, validation, data)`` and/or``clean_studio_edits(self, data)`` - see the source code for details.Supported field types:* Boolean:``field_name = Boolean(display_name="Field Name")``* Float:``field_name = Float(display_name="Field Name")``* Integer:``field_name = Integer(display_name="Field Name")``* String:``field_name = String(display_name="Field Name")``* String (multiline):``field_name = String(multiline_editor=True, resettable_editor=False)``* String (html):``field_name = String(multiline_editor='html', resettable_editor=False)``Any of the above will use a dropdown menu if they have a pre-definedlist of possible values.* List of unordered unique values (i.e. sets) drawn from a small set ofpossible values:``field_name = List(list_style='set', list_values_provider=some_method)``- The ``List`` declaration must include the property ``list_style='set'`` toindicate that the ``List`` field is being used with set semantics.- The ``List`` declaration must also define a ``list_values_provider`` methodwhich will be called with the block as its only parameter and which mustreturn a list of possible values.* Rudimentary support for Dict, ordered List, and any other JSONField-derived field types- ``list_field = List(display_name="Ordered List", default=[])``- ``dict_field = Dict(display_name="Normal Dict", default={})``Supported field options (all field types):* ``values`` can define a list of possible options, changing the UI elementto a select box. Values can be set to any of the formats `defined in theXBlock source code <https://github.com/edx/XBlock/blob/master/xblock/fields.py>`__:- A finite set of elements: ``[1, 2, 3]``- A finite set of elements where the display names differ from the values::[{"display_name": "Always", "value": "always"},{"display_name": "Past Due", "value": "past_due"},]- A range for floating point numbers with specific increments:``{"min": 0 , "max": 10, "step": .1}``- A callable that returns one of the above. (Note: the callable does*not* get passed the XBlock instance or runtime, so it cannot be anormal member function)* ``values_provider`` can define a callable that accepts the XBlockinstance as an argument, and returns a list of possible values in oneof the formats listed above.* ``resettable_editor`` - defaults to ``True``. Set ``False`` to hide the"Reset" button used to return a field to its default value by removingthe field's value from the XBlock instance.Basic screenshot: |Screenshot 1|StudioContainerXBlockMixin--------------------------.. code:: pythonfrom xblockutils.studio_editable import StudioContainerXBlockMixinThis mixin helps to create XBlocks that allow content authors to add,remove, or reorder child blocks. By removing any existing``author_view`` and adding this mixin, you'll get editable,re-orderable, and deletable child support in Studio. To enable authors toadd arbitrary blocks as children, simply override ``author_edit_view``and set ``can_add=True`` when calling ``render_children`` - see thesource code. To restrict authors so they can add only specific types ofchild blocks or a limited number of children requires custom HTML.An example is the mentoring XBlock: |Screenshot 2|SeleniumXBlockTest------------------.. code:: pythonfrom xblockutils.base_test import SeleniumXBlockTestThis is a base class that you can use for writing Selenium integrationtests that are hosted in the XBlock SDK (Workbench).Here is an example:.. code:: pythonclass TestStudentView(SeleniumXBlockTest):"""Test the Student View of MyCoolXBlock"""def setUp(self):super(TestStudentView, self).setUp()self.set_scenario_xml('<mycoolblock display_name="Test Demo Block" field2="hello" />')self.element = self.go_to_view("student_view")def test_shows_field_2(self):"""The xblock should display the text value of field2."""self.assertIn("hello", self.element.text)StudioEditableBaseTest----------------------.. code:: pythonfrom xblockutils.studio_editable_test import StudioEditableBaseTestThis is a subclass of ``SeleniumXBlockTest`` that adds a few helpermethods useful for testing the ``studio_view`` of any XBlock using``StudioEditableXBlockMixin``.child\_isinstance-----------------.. code:: pythonfrom xblockutils.helpers import child_isinstanceIf your XBlock needs to find children/descendants of a particularclass/mixin, you should use.. code:: pythonchild_isinstance(self, child_usage_id, SomeXBlockClassOrMixin)rather than calling.. code:: python``isinstance(self.runtime.get_block(child_usage_id), SomeXBlockClassOrMixin)``.On runtimes such as those in edx-platform, ``child_isinstance`` isorders of magnitude faster... |Screenshot 1| image:: https://cloud.githubusercontent.com/assets/945577/6341782/7d237966-bb83-11e4-9344-faa647056999.png.. |Screenshot 2| image:: https://cloud.githubusercontent.com/assets/945577/6341803/d0195ec4-bb83-11e4-82f6-8052c9f70690.pngXBlockWithSettingsMixin-----------------------This mixin provides access to instance-wide XBlock-specific configuration settings.See [wiki page](https://github.com/edx/xblock-utils/wiki/Settings-and-theme-support#accessing-xblock-specific-settings) for detailsThemableXBlockMixin-------------------This mixin provides XBlock theming capabilities built on top of XBlock-specific settings.See [wiki page](https://github.com/edx/xblock-utils/wiki/Settings-and-theme-support#theming-support) for details