From 622d49a7d463af983d10a6e6bf6177b42e51e564 Mon Sep 17 00:00:00 2001 From: sarina Date: Sun, 19 Nov 2023 21:16:12 -0500 Subject: [PATCH] docs: Match docs on myxblock html, js, css with the actual code in the xblock sdk --- docs/links.rst | 2 ++ .../xblock-tutorial/customize/custom-html.rst | 24 ++++++++-------- .../customize/custom-javascript.rst | 28 +++++++++---------- .../customize/custom-stylesheets.rst | 23 +++++++++------ .../reusable/code_myxblock_js.rst | 1 + 5 files changed, 44 insertions(+), 34 deletions(-) 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/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-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/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) {