Merge pull request #694 from openedx/sarina/improve-tutorial-2

Update customize section of XBlock tutorial

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

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 <XBlock
 Fragments>`. 
 
-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 <XBlock 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 <The 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``

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,24 +60,28 @@ 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 <The XBlock JavaScript File>`.
+  XBlock class. The name also maps to the function that initializes the XBlock
+  in the :ref:`JavaScript file <The XBlock JavaScript File>`.
 
   .. code-block:: python
 
      frag.initialize_js('ThumbsBlock')
 
 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.
 

docs/xblock-tutorial/customize/custom-html.rst

@@ -17,9 +17,9 @@ method <View Methods>`.
  :local:
  :depth: 1 
 
-*******************************
+****************************
 The Default XBlock HTML File
-*******************************
+****************************
 
 When you :ref:`create a new XBlock <Create Your First 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 <Customize myxblock.py>` for the XBlock.
 
-* For the value of each of the outer ``span`` elements, use the entities
-  ``&uarr;`` 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`_ ``&uarr;`` 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<Customize myxblock.js>`.
 
 .. include:: ../../links.rst

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,23 +16,23 @@ Fragments>`.
  :local:
  :depth: 1 
 
-***********************************
+**********************************
 The Default XBlock JavaScript File
-***********************************
+**********************************
 
 When you :ref:`create a new XBlock <Create Your First 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
 
 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<Customize myxblock.css>`.
 
 .. include:: ../../links.rst

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 <Create Your First 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 <XBlock
 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<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 <XBlock Runtimes>`, 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 <Handler Methods>` 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<Customize myxblock.html>`.
 
 .. include:: ../../links.rst