diff --git a/docs/links.rst b/docs/links.rst index 3716041e9..c0ed9c72e 100644 --- a/docs/links.rst +++ b/docs/links.rst @@ -66,3 +66,5 @@ .. _Installing, Configuring, and Running the Open edX Platform: https://edx.readthedocs.io/projects/edx-installing-configuring-and-running/en/latest/index.html .. _Developing Course Components: https://edx.readthedocs.io/projects/edx-partner-course-staff/en/latest/developing_course/course_components.html + +.. _HTML unicode characters: https://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references diff --git a/docs/xblock-tutorial/anatomy/javascript.rst b/docs/xblock-tutorial/anatomy/javascript.rst index 2a35721eb..e5273e23e 100644 --- a/docs/xblock-tutorial/anatomy/javascript.rst +++ b/docs/xblock-tutorial/anatomy/javascript.rst @@ -8,13 +8,13 @@ This section of the tutorial walks through the JavaScript file, `thumbs.js`_, that is part of the Thumbs XBlock in the XBlock SDK. If you completed the steps in :ref:`Build an XBlock Quick Start`, you can find -this file locally at ``xblock_development/xblock-sdk/sample_xblocks/thumbs/static/js/source/thumbs.js``. +this file locally at ``xblock_development/xblock-sdk/sample_xblocks/thumbs/static/js/src/thumbs.js``. In the XBlock JavaScript file, you define code that manages user interaction with the XBlock. The code is added to a :ref:`fragment `. -The XBlock’s JavaScript uses the runtime handler, and can use the ``children`` +The XBlock's JavaScript uses the runtime handler, and can use the ``children`` and ``childMap`` functions as needed. The JavaScript references the XBlock :ref:`fields ` @@ -29,7 +29,7 @@ Note the following details about the JavaScript file. * The function ``ThumbsBlock`` initializes the XBlock. A JavaScript function to initialize the XBlock is required. -* The ``ThumbsBlock`` function maps to the contstructor in the :ref:`XBlock +* The ``ThumbsBlock`` function maps to the constructor in the :ref:`XBlock Python file ` and provides access to its methods and fields. @@ -39,7 +39,7 @@ Note the following details about the JavaScript file. var handlerUrl = runtime.handlerUrl(element, 'vote'); -* The ``ThumbsBlock`` function includes the ``Post`` commands to increase the up +* The ``ThumbsBlock`` function includes the ``POST`` commands to increase the up and down votes in the XBlock. The XBlock JavaScript code can also use the ``children`` and ``childMap`` diff --git a/docs/xblock-tutorial/anatomy/python.rst b/docs/xblock-tutorial/anatomy/python.rst index 8b20ce0c0..57dda2f3f 100644 --- a/docs/xblock-tutorial/anatomy/python.rst +++ b/docs/xblock-tutorial/anatomy/python.rst @@ -1,8 +1,8 @@ .. _The XBlock Python File: -####################### +###################### 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. @@ -18,9 +18,9 @@ scenarios. :local: :depth: 1 -******************** +******************* Thumb XBlock Fields -******************** +******************* The ``thumbs.py`` file defines the following fields for the XBlock in the ``ThumbsBlockBase`` class. @@ -42,9 +42,9 @@ Note the following details about the fields in the Thumbs XBlock. For more information, see :ref:`XBlock Fields`. -************************** +************************* Thumb XBlock Student View -************************** +************************* The ``thumbs.py`` file defines the student view for the XBlock in the ``ThumbsBlockBase`` class. @@ -60,14 +60,18 @@ Note the following details about student view. .. code-block:: python - html_str = pkg_resources.resource_string(__name__, "static/html/thumbs.html") - frag = Fragment(unicode(html_str).format(self=self)) + html_str = pkg_resources.resource_string( + __name__, + "static/html/thumbs.html".decode('utf-8') + ) + frag = Fragment(str(html_str).format(block=self)) * The JavaScript and CSS file contents are added to the fragment with the - ``add_javascript()`` and ``add_css`` methods. + ``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 :ref:`JavaScript file `. + XBlock class. The name also maps to the function that initializes the XBlock + in the :ref:`JavaScript file `. .. code-block:: python @@ -75,9 +79,9 @@ Note the following details about student view. For more information, see :ref:`View Methods`. -************************** +************************* Thumb XBlock Vote Handler -************************** +************************* The ``thumbs.py`` file defines a handler that adds a user's vote to the XBlock. diff --git a/docs/xblock-tutorial/customize/custom-html.rst b/docs/xblock-tutorial/customize/custom-html.rst index 2d5634141..9a6d69a1a 100644 --- a/docs/xblock-tutorial/customize/custom-html.rst +++ b/docs/xblock-tutorial/customize/custom-html.rst @@ -17,9 +17,9 @@ method `. :local: :depth: 1 -******************************* +**************************** The Default XBlock HTML File -******************************* +**************************** When you :ref:`create a new XBlock `, the default static HTML file is created automatically, with skeletal functionality defined. @@ -31,9 +31,9 @@ file ``myxblock.html``. The file contains HTML to display the ``count`` field that was added by default to the XBlock. Delete the HTML between the ``div`` elements. -******************** +**************** Add HTML Content -******************** +**************** You can create HTML as needed to display the state of your XBlock. The Thumbs XBlock displays the up and down votes. Create a single paragraph and follow the @@ -50,13 +50,13 @@ guidelines below. reference the ``upvotes`` and ``downvotes`` fields you defined in the :ref:`Python file ` for the XBlock. -* For the value of each of the outer ``span`` elements, use the entities - ``↑`` and ``&darr`` to show thumbs up and thumbs down symbols next to - the number of votes. +* For the value of each of the outer ``span`` elements, use the `HTML unicode + characters`_ ``↑`` and ``&darr`` to show thumbs up and thumbs down + symbols next to the number of votes. -**************************************** +************************************ Check HTML Against the Thumbs XBlock -**************************************** +************************************ After you have defined the HTML, check your work against the HTML in the Thumbs XBlock, in the file ``xblock_development/xblock-sdk/sample_xblocks/thumbs/static/html/thumbs.html``. @@ -66,11 +66,11 @@ Thumbs XBlock, in the file ``xblock_development/xblock-sdk/sample_xblocks/thumbs If necessary, make corrections to the HTML in your XBlock so that it matches the HTML in the Thumbs XBlock. -********************************** +********* Next Step -********************************** +********* -After you complete your customizations to the HTML file, you continue on and +After you complete your customizations to the HTML file, you can continue on and :ref:`customize the XBlock JavaScript file`. .. include:: ../../links.rst diff --git a/docs/xblock-tutorial/customize/custom-javascript.rst b/docs/xblock-tutorial/customize/custom-javascript.rst index 6bc00487e..e95c0c86d 100644 --- a/docs/xblock-tutorial/customize/custom-javascript.rst +++ b/docs/xblock-tutorial/customize/custom-javascript.rst @@ -1,8 +1,8 @@ .. _Customize myxblock.js: -####################### +##################### Customize myxblock.js -####################### +##################### This section describes how to modify the JavaScript file of the XBlock you created, ``myxblock.js``, to provide the functionality in the Thumbs XBlock @@ -16,13 +16,13 @@ Fragments>`. :local: :depth: 1 -*********************************** +********************************** The Default XBlock JavaScript File -*********************************** +********************************** When you :ref:`create a new XBlock `, the default JavaScript file is created automatically, with skeletal functionality defined. -In the ``xblock_development/myxblock/myxblock/static/js/source`` directory, see +In the ``xblock_development/myxblock/myxblock/static/js/snc`` directory, see the file ``myxblock.js``. .. include:: ../reusable/code_myxblock_js.rst @@ -30,9 +30,9 @@ the file ``myxblock.js``. The file contains JavaScript code to increment the ``count`` field that was added by default to the XBlock. Delete this code. -******************** +******************* Add JavaScript Code -******************** +******************* JavaScript code implements the browser-side functionality you need for your XBlock. The Thumbs XBlock uses clicks on the up and down vote buttons to call @@ -52,28 +52,28 @@ Follow the guidelines below to implement JavaScript code. var handlerUrl = runtime.handlerUrl(element, 'vote'); -* Add ``Post`` commands in the ``MyXBlock`` function to increase the up and +* Add ``POST`` commands in the ``MyXBlock`` function to increase the up and down votes in the XBlock. .. note:: Do not change the main function name, ``MyXBlock``. -******************************************* +****************************************** Check JavaScript Against the Thumbs XBlock -******************************************* +****************************************** After you have defined the JavaScript code, check your work against the code in -the Thumbs XBlock, in the file ``xblock_development/xblock-sdk/sample_xblocks/thumbs/static/js/source/thumbs.js``. +the Thumbs XBlock, in the file ``xblock_development/xblock-sdk/sample_xblocks/thumbs/static/js/src/thumbs.js``. .. include:: ../reusable/code_thumbs_javascript.rst If necessary, make corrections to the code in your XBlock so that it matches the code in the Thumbs XBlock. -********************************** +********* Next Step -********************************** +********* -After you complete your customizations to the JavaScript file, you continue on +After you complete your customizations to the JavaScript file, you can continue on and :ref:`customize the XBlock CSS file`. .. include:: ../../links.rst diff --git a/docs/xblock-tutorial/customize/custom-python.rst b/docs/xblock-tutorial/customize/custom-python.rst index cd06c8e74..2f8bff396 100644 --- a/docs/xblock-tutorial/customize/custom-python.rst +++ b/docs/xblock-tutorial/customize/custom-python.rst @@ -1,8 +1,8 @@ .. _Customize myxblock.py: -####################### +##################### Customize myxblock.py -####################### +##################### This section describes how to modify the Python file of the XBlock you created, ``myxblock.py``, to provide the functionality in the Thumbs XBlock example in @@ -16,9 +16,9 @@ scenarios. :local: :depth: 1 -******************************* +****************************** The Default XBlock Python File -******************************* +****************************** When you :ref:`create a new XBlock `, the default Python file is created automatically, with skeletal functionality defined. In @@ -27,18 +27,18 @@ the ``xblock_development/myxblock/myxblock/`` directory, see the file .. include:: ../reusable/code_myxblock_python.rst -******************** +************ Add Comments -******************** +************ As a best practice and because XBlocks can be shared, you should add comments to the ``myxblock.py`` file. Replace the "TO DO" indicators with a description of what the XBlock does and any details future developers or users would want to know. -******************** +***************** Add XBlock Fields -******************** +***************** You determine the data your XBlock stores through :ref:`fields `. Fields store user and XBlock state as JSON data. @@ -60,9 +60,9 @@ Review the :ref:`XBlock Fields` section, then add the required fields to ``myxblock.py``. You can remove the ``count`` field, which was defined automatically when you created the XBlock. -======================================= +====================================== Check Fields Against the Thumbs XBlock -======================================= +====================================== After you have defined the fields, check your work against the fields in the Thumbs XBlock, in the file ``xblock_development/xblock-sdk/sample_xblocks/thumbs/thumbs.py``. @@ -81,17 +81,17 @@ Note the following details. * ``voted`` has the scope ``Scope.user_state``. This indicates that the data in this field applies to the XBlock and to the specific user. -************************** +*********************** Define the Student View -************************** +*********************** The XBlock Python file must contain one or more :ref:`view methods`. -To run the XBlock in the edX Platform Learning Management System, there must be +To run the XBlock in the Open edX Platform Learning Management System, there must be a method named ``student_view``. If you intend the XBlock to run in a different :ref:`runtime application `, you might need to define a -different name. For more information, see :ref:`EdX Learning Management +different name. For more information, see :ref:`Open edX Learning Management System as an XBlock Runtime`. In ``myxblock.py``, examine the ``student_view`` method that was defined @@ -111,7 +111,7 @@ Note the following details about student view. frag = Fragment(unicode(html_str).format(self=self)) * The JavaScript and CSS files are added to the fragment with the - ``add_javascript()`` and ``add_css`` methods. + ``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 @@ -127,9 +127,9 @@ Check the student view in ``myxblock.py`` against the student view in CSS, and JavaScript files added to the fragment. As the file names are correct for MyXBlock, you do not need to edit the student view at all. -************************** +*********************** Define the Vote Handler -************************** +*********************** :ref:`Handlers ` process input events from the XBlock JavaScript code. You use handlers to add interactivity to your block. In @@ -150,9 +150,9 @@ You can use any name for the vote handler, and you will use the same name in the JavaScript code to connect browser events to the vote handler running in the server. To match the Thumbs XBlock, use the name ``vote``. -============================================ +=========================================== Check the Handler Against the Thumbs XBlock -============================================ +=========================================== After you have defined the vote handler, check your work against the handler in the Thumbs XBlock. @@ -162,11 +162,11 @@ in the Thumbs XBlock. If necessary, make corrections to the handler in your XBlock so that it matches the handler in the Thumbs XBlock. -********************************** +********* Next Step -********************************** +********* -After you complete your customizations to the Python file, you continue on and +After you complete your customizations to the Python file, you can continue on and :ref:`customize the XBlock HTML file`. .. include:: ../../links.rst diff --git a/docs/xblock-tutorial/customize/custom-stylesheets.rst b/docs/xblock-tutorial/customize/custom-stylesheets.rst index 8f906905a..0e72d2a35 100644 --- a/docs/xblock-tutorial/customize/custom-stylesheets.rst +++ b/docs/xblock-tutorial/customize/custom-stylesheets.rst @@ -1,8 +1,8 @@ .. _Customize myxblock.css: -####################### +###################### Customize myxblock.css -####################### +###################### This section describes how to modify the static CSS file of the XBlock you created, ``myxblock.css``, to provide the functionality in the Thumbs XBlock @@ -16,9 +16,9 @@ application. :local: :depth: 1 -******************************* +*************************** The Default XBlock CSS File -******************************* +*************************** When you :ref:`create a new XBlock `, the default static CSS file is created automatically, with skeletal functionality defined. @@ -30,9 +30,9 @@ file ``myxblock.css``. The file contains CSS code to format the ``count`` field that was added by default to the XBlock. Delete this code. -******************** +************ Add CSS Code -******************** +************ You must add CSS code to format the XBlock content. Follow the guidelines below. @@ -48,9 +48,9 @@ below. * The color for ``.upvote`` is green and for ``downvote`` is red. -**************************************** +*********************************** Check CSS Against the Thumbs XBlock -**************************************** +*********************************** After you have defined the CSS code, check your work against the CSS in the Thumbs XBlock, in the file ``xblock_development/xblock-sdk/sample_xblocks/thumbs/static/css/thumbs.css``. @@ -63,4 +63,11 @@ matches the code in the Thumbs XBlock. The styles in ``thumbs.css`` are referenced in the :ref:`XBlock HTML file `. +********* +Congrats! +********* + +You've completed customizing MyXBlock to have up and down voting functionality. +Read on for more about XBlocks - and have fun making your next XBlock! + .. include:: ../../links.rst diff --git a/docs/xblock-tutorial/edx_platform/edx_lms.rst b/docs/xblock-tutorial/edx_platform/edx_lms.rst index fa5928c23..8a33ddb3c 100644 --- a/docs/xblock-tutorial/edx_platform/edx_lms.rst +++ b/docs/xblock-tutorial/edx_platform/edx_lms.rst @@ -1,10 +1,10 @@ -.. _EdX Learning Management System as an XBlock Runtime: +.. _Open edX Learning Management System as an XBlock Runtime: -#################################################### -EdX Learning Management System as an XBlock Runtime -#################################################### +######################################################## +Open edX Learning Management System as an XBlock Runtime +######################################################## -The edX Learning Management System (LMS) is the application in the edX Platform +The Open edX Learning Management System (LMS) is the application in the Open edX Platform that learners use to view and interact with courseware. Because it presents XBlocks to learners and records their interactions, the LMS @@ -28,7 +28,7 @@ The LMS requires XBlocks to have the following properties. In addition, the ``student_view`` method is used to render the XBlock in the Studio preview mode, unless the XBlock also has an ``author_view`` method. - For more information, see :ref:`EdX Studio as an XBlock Runtime`. + For more information, see :ref:`Open edX Studio as an XBlock Runtime`. * A class property named ``has_score`` with a value of ``True`` if the XBlock is to be graded. diff --git a/docs/xblock-tutorial/edx_platform/edx_studio.rst b/docs/xblock-tutorial/edx_platform/edx_studio.rst index cd1770e76..dedad42e8 100644 --- a/docs/xblock-tutorial/edx_platform/edx_studio.rst +++ b/docs/xblock-tutorial/edx_platform/edx_studio.rst @@ -1,10 +1,10 @@ -.. _EdX Studio as an XBlock Runtime: +.. _Open edX Studio as an XBlock Runtime: -############################### -EdX Studio as an XBlock Runtime -############################### +#################################### +Open edX Studio as an XBlock Runtime +#################################### -EdX Studio is the application in the edX Platform that instructors use to build +Open edX Studio is the application in the Open edX Platform that instructors use to build courseware. Because instructors use Studio to add and configure XBlocks, Studio is @@ -31,7 +31,7 @@ Studio requires XBlocks to have the following properties. ``student_view``, but may contain inline editing capabilities. If you do not define an ``author_view``, the preview mode uses the - ``student_view``. For more information, see :ref:`EdX Learning Management + ``student_view``. For more information, see :ref:`Open edX Learning Management System as an XBlock Runtime`. * A class property named ``non_editable_metadata_fields``. This variable diff --git a/docs/xblock-tutorial/reusable/code_myxblock_js.rst b/docs/xblock-tutorial/reusable/code_myxblock_js.rst index 274267a55..4a46fb6df 100644 --- a/docs/xblock-tutorial/reusable/code_myxblock_js.rst +++ b/docs/xblock-tutorial/reusable/code_myxblock_js.rst @@ -1,5 +1,6 @@ .. code-block:: javascript + /* Javascript for MyXBlock. */ function MyXBlock(runtime, element) { function updateCount(result) { diff --git a/docs/xblock-tutorial/reusable/code_myxblock_python.rst b/docs/xblock-tutorial/reusable/code_myxblock_python.rst index 867aa263a..61553efae 100644 --- a/docs/xblock-tutorial/reusable/code_myxblock_python.rst +++ b/docs/xblock-tutorial/reusable/code_myxblock_python.rst @@ -4,9 +4,9 @@ import pkg_resources + from web_fragments.fragment import Fragment from xblock.core import XBlock - from xblock.fields import Scope, Integer - from xblock.fragment import Fragment + from xblock.fields import Integer, Scope class MyXBlock(XBlock): @@ -61,11 +61,14 @@ """A canned scenario for display in the workbench.""" return [ ("MyXBlock", - """ + """ + """), + ("Multiple MyXBlock", + """ - """), + """), ] diff --git a/docs/xblock-tutorial/reusable/code_thumbs_fields.rst b/docs/xblock-tutorial/reusable/code_thumbs_fields.rst index 5288e0699..c9b2fa549 100644 --- a/docs/xblock-tutorial/reusable/code_thumbs_fields.rst +++ b/docs/xblock-tutorial/reusable/code_thumbs_fields.rst @@ -1,9 +1,18 @@ .. code-block:: python 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) + 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 + ) diff --git a/docs/xblock-tutorial/reusable/code_thumbs_student_view.rst b/docs/xblock-tutorial/reusable/code_thumbs_student_view.rst index 2864774f7..5fb191a49 100644 --- a/docs/xblock-tutorial/reusable/code_thumbs_student_view.rst +++ b/docs/xblock-tutorial/reusable/code_thumbs_student_view.rst @@ -11,16 +11,24 @@ # 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)) + html_str = pkg_resources.resource_string( + __name__, + "static/html/thumbs.html".decode('utf-8') + ) + frag = Fragment(str(html_str).format(block=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)) + css_str = pkg_resources.resource_string( + __name__, + "static/css/thumbs.css".decode('utf-8') + ) + frag.add_css(str(css_str)) - js_str = pkg_resources.resource_string(__name__, - "static/js/src/thumbs.js") - frag.add_javascript(unicode(js_str)) + js_str = pkg_resources.resource_string( + __name__, + "static/js/src/thumbs.js".decode('utf-8') + ) + frag.add_javascript(str(js_str)) frag.initialize_js('ThumbsBlock') return frag