Update the html, discussion, and video OLX component docs

sarina · sarina · commit 924ad4667f90 · 2025-11-15T00:05:52.000-05:00
diff --git a/source/educators/olx/components/discussion-components.rst b/source/educators/olx/components/discussion-components.rst
@@ -6,7 +6,27 @@ Discussion Components in OLX
 
 .. tags:: educator, reference
 
-.. warning:: This page refers to the older discussion forums (pre-Olive release) and may be out of date.
+.. warning::
+  
+  This page refers to the older discussion forums (pre-Olive release) and is deprecated for post-Olive releases.
+
+  For Olive and newer releases, discussion components are automatically created for each ungraded unit. To
+  enable discussion on graded units, the behavior can be overridden via the ``discussions_settings`` attribute
+  on the ``course`` object in the ``course/run.xml`` file.
+
+  Here is an example of ``discussions_settings`` with ``enable_graded_units`` set to  ``true``:
+
+  .. code-block:: xml
+
+    discussions_settings=
+      "{&quot;enable_graded_units&quot;: true,
+      &quot;enable_in_context&quot;: true,
+      &quot;provider_type&quot;: &quot;openedx&quot;,
+      &quot;unit_level_visibility&quot;: true,
+      &quot;posting_restrictions&quot;: &quot;disabled&quot;,
+      &quot;openedx&quot;: {&quot;group_at_subsection&quot;: false}}"
+
+  The UI for discussions configuration can be found under the Content > Pages & Resources menu in Studio.
 
 You can add inline :term:`Discussion` components to any container in your
 course.
@@ -91,7 +111,7 @@ The ``discussion`` element contains no children.
      - The name of the subcategory for the inline discussion as shown in the
        **Discussion** tab of the course. For example: ``Problem 2``
    * - ``display_name``
-     - Optional. The value that is displayed to students as the name of the
+     - Optional. The value that is displayed to learners as the name of the
        discussion component. If you do not supply a ``display_name`` value,
        "Discussion" is supplied for you.
    * - Optional. ``discussion_id``
@@ -135,5 +155,5 @@ The following example shows an XML file for a discussion component.
 +--------------+-------------------------------+----------------+--------------------------------+
 | Review Date  | Working Group Reviewer        |   Release      |Test situation                  |
 +--------------+-------------------------------+----------------+--------------------------------+
-|              |                               |                |                                |
+| 2025-11-06   | sarina                        |  Ulmo          | Deprecated                     |
 +--------------+-------------------------------+----------------+--------------------------------+
diff --git a/source/educators/olx/components/html-components.rst b/source/educators/olx/components/html-components.rst
@@ -14,29 +14,17 @@ HTML Components in OLX
 Create the HTML Component
 *********************************************
 
-To add an HTML component to your course, you can embed the XML for it in the
-parent XML file, or split it up into either 1 or 2 additional files. You can
-break up the HTML configuration into an .xml file in the html directory and an
-additional .html file in the same directory.
+To add an HTML component to your course, split it up into 2 files: The HTML
+configuration into an .xml file in the html directory and an additional .html
+file in the same directory.
 
-.. caution:: If you are including HTML that is not valid HTML, you must break
- out HTML content in a separate file.
-
-
-*****************************************************
-Example of an HTML Component Embedded in a Vertical
-*****************************************************
-
-.. code-block:: xml
-
-   <vertical display_name="Lesson_1_Unit_1">
-      ...
-      <html>The above has an error. <b>x</b> should be <b>y</b> in the second equation.</html>
-  </vertical>
+.. caution::
+  
+  If you are including HTML that is not valid HTML, you must break out HTML content in a separate file.
 
 
 *********************************************
-Example of Separate HTML Files
+Example of XML & HTML Files
 *********************************************
 
 You create an XML file in the ``html`` directory for the content that you
@@ -45,24 +33,27 @@ choose to break out into separate HTML files.
 The name of the XML file must match the value of the @url_name attribute of the
 ``html`` element in the vertical XML file.
 
-For example, a vertical XML file contains the following url_name.
+For example, the ``vertical/unit_1_what_is_olx.xml`` file contains the following
+``url_name``.
 
 .. code-block:: xml
 
-   <vertical display_name="Lesson_1_Unit_1">
-      <html url_name="Introduction"/>
-      . . .
+  <vertical display_name="Unit 1: What is OLX?">
+    <html url_name="what_is_olx"/>
+    . . .
   </vertical>
 
-You create the file ``html/Introduction.xml`` to define the HTML component.
+This references the file ``html/what_is_olx.xml`` to define the HTML component.
 
 *************************************
-HTML Component XML File Elements
+Example HTML Component XML File
 *************************************
 
-The root element of the XML file for the HTML component is file is ``html``.
+The following example shows the ``html/what_is_olx.xml`` file for an HTML component.
 
-In this case, the ``html`` element contains no children.
+.. code-block:: xml
+
+  <html filename="what_is_olx" display_name="What is OLX?"/>
 
 *************************************
 ``html`` Element Attributes
@@ -75,47 +66,39 @@ In this case, the ``html`` element contains no children.
    * - Attribute
      - Meaning
    * - ``display_name``
-     - Required. The value that is displayed to students as the name of the
+     - Required. The value that is displayed to learners as the name of the
        HTML component. If you do not supply a ``display_name`` value, "html" is
        supplied for you.
    * - ``filename``
      - The name of the HTML file that contains the content for the HTML
        component, without the ``.HTML`` extension.
 
+
 *************************************
-Example HTML Component XML File
+HTML Component XML File Elements
 *************************************
 
-The following example shows an XML file for an HTML component.
-
-.. code-block:: xml
-
-  <html filename="Introduction" display_name="Unit Introduction"/>
+The root element of the XML file for the HTML component is file is ``html``.
 
+In this case, the ``html`` element contains no children.
 
 *************************************
 Example HTML Component Content
 *************************************
 
 In the component's HTML file, you add valid HTML to represent the content you
-want to be displayed to students. For example, the following is from an HTML
-file for the edX Demo course:
+want to be displayed to learners. For example, the following is from an HTML
+file from the olx_example_course:
 
 .. code-block:: html
 
-    <h3>Lesson 2: Let's Get INTERACTIVE!</h3>
-    <p>
-    <img
-    src="/static/interactive_x250.png" alt="Interactive" width="250"
-    hspace="12" vspace="12" border="0" align="right" />Now that you know your
-    way around an Open edX course let's look at some of the exciting interactive
-    tools you may encounter. Use the unit navigation bar above to explore.
-    &nbsp;</p>
-    <p>Once you have tried the interactive tools in this lesson,
-    make sure to check out the week 2 homework where we show you several of the
-    really cool interactive labs we&rsquo;ve created for past courses.
-    &nbsp;They&rsquo;re fun to play with. &nbsp;Many courses will have tools
-    and labs that you need to use to complete homework assignments.</p>
+  <p><span style="font-size: 1em;">OLX (open learning XML) is the XML-based standard used to build courses for the Open edX Platform.</span></p>
+  <p><span style="font-size: 1em;">With OLX, you can:</span></p>
+  <ul>
+  <li>Move content between Open edX instances.</li>
+  <li>Create course content outside of Open edX Studio, including by conversion from other content formats.</li>
+  <li>Ensure content remains free of proprietary encoding and allow portability.</li>
+  </ul>
 
 
 .. seealso::
@@ -135,5 +118,5 @@ file for the edX Demo course:
 +--------------+-------------------------------+----------------+--------------------------------+
 | Review Date  | Working Group Reviewer        |   Release      |Test situation                  |
 +--------------+-------------------------------+----------------+--------------------------------+
-|              |                               |                |                                |
+| 2025-11-06   | sarina                        |  Ulmo          | Pass                           |
 +--------------+-------------------------------+----------------+--------------------------------+
diff --git a/source/educators/olx/components/video-components.rst b/source/educators/olx/components/video-components.rst
@@ -6,9 +6,7 @@ Video Components in OLX
 
 .. tags:: educator, reference
 
-You can add video components to any container in your course (such as
-a vertical or sequential). Studio places all video components inside
-verticals (which it calls units).
+You can add video components to a course unit via the ``video/<video_name>.xml`` file.
 
 .. contents::
   :local:
@@ -19,19 +17,23 @@ Create the XML File for a Video Component
 **********************************************
 
 To add a video component to your course, add it to the course XML tree as
-follows.
+follows. This is ``video/purpose_power_reach.xml`` in the olx_example_course.
 
 .. code-block:: xml
 
   <video
-    youtube="1.00:o2pLltkrhGM"
-    url_name="Introduction_Lecture"
-    display_name="Introduction Lecture"
-    youtube_id_1_0="o2pLltkrhGM">
-  </video>
+    youtube="1.00:lVPPPpyUOR4"
+    url_name="purpose_power_reach"
+    display_name="The Purpose, Power and Reach of the Open edX® Platform"
+    edx_video_id=""
+    end_time="00:00:00"
+    html5_sources="[]"
+    start_time="00:00:00"
+    track=""
+    youtube_id_1_0="lVPPPpyUOR4"/>
+
 
-If you prefer to place the video component in its own file, you create an XML
-file in the ``video`` directory for each video component in your course.
+Place an XML file in the ``video`` directory for each video component in your course.
 
 The name of the XML file must match the value of the @url_name attribute of the
 ``video`` element in the vertical XML file.
@@ -40,12 +42,12 @@ For example, the vertical XML file uses the following format.
 
 .. code-block:: xml
 
-   <vertical display_name="Lesson_1_Unit_1">
-      <video url_name="Introduction_Lecture"/>
-      . . .
+  <vertical display_name="Unit 1: Video">
+    <video url_name="purpose_power_reach"/>
   </vertical>
 
-You create the file ``video/Introduction_Lecture.xml`` to define the video
+
+You create the file ``video/purpose_power_reach.xml`` to define the video
 component.
 
 *************************************
@@ -54,24 +56,6 @@ Video Component XML File Elements
 
 The root element of the XML file for the HTML component is file is ``video``.
 
-The ``video`` element contains a single ``source`` element.
-
-==============================
-``source`` Element
-==============================
-
-The ``source`` element contains the following attribute.
-
-.. list-table::
-   :widths: 10 70
-   :header-rows: 1
-
-   * - Attribute
-     - Meaning
-   * - ``src``
-     - The file path for the video file.
-
-
 *************************************
 ``video`` Element Attributes
 *************************************
@@ -83,33 +67,53 @@ The ``source`` element contains the following attribute.
    * - Attribute
      - Meaning
    * - ``display_name``
-     - Required. The value that is displayed to students as the name of the
-       video component. If you do not supply a ``display_name`` value, "video"
-       is supplied for you.
+     - Required. The value that is displayed to learners as the name of the
+       video component. If a ``display_name`` is not supplied, "video" will appear to learners.
    * - ``youtube``
-     - The speed and ID pairings for the YouTube video source. The value can
-       contain multiple speed:ID pairs, separated by commas.
+     - The speed and 1.0 pairings for the YouTube video source (see Note below)
+   * - ``youtube_id_1_0``
+     - The YouTube id for the video
    * - ``download_track``
-     - Whether students can download the video track. ``true`` or ``false``.
+     - Whether learners can download the video track. ``true`` or ``false``.
    * - ``download_video``
-     - Whether students can download the video. ``true`` or ``false``.
+     - Whether learners can download the video. ``true`` or ``false``.
    * - ``html5_sources``
      - The file path for the HTML5 version of the video.
    * - ``show_captions``
-     - Whether students can view the video captions. ``true`` or ``false``.
-   * - ``source``
+     - Whether learners can view the video captions. ``true`` or ``false``.
+   * - ``start_time``
+     - The HH:MM:SS value of when within the video playback should begin. Defaults to ``00:00:00``
+   * - ``end_time``
+     - The HH:MM:SS value of when within the video playback should end. Defaults to ``00:00:00`` (will play whole video)
+   * - ``track``
      - TBD
-   * - ``sub``
-     - TBD
-   * - ``youtube_id_0_75``
-     - The YouTube ID for the video that plays at 75% normal speed.
-   * - ``youtube_id_1_0``
-     - The YouTube ID for the video that plays at 100% normal speed.
-   * - ``youtube_id_1_25``
-     - The YouTube ID for the video that plays at 125% normal speed.
-   * - ``youtube_id_1_5``
-     - The YouTube ID for the video that plays at 150% normal speed.
+   * - ``edx_video_id``
+     - Only used on ``edx.org`` courses. Will be deprecated.
+
+.. note::
+
+  For historical reasons, the ``youtube`` attribute requires a speed mapping. Since YouTube introduced the
+  native ability to speed up/slow down video circa 2014, the speed mapping is no longer required. However, the ``youtube``
+  attribute still maps the YouTube id to the 1.0 speed as follows:
+
+  .. code-block:: xml
+
+    youtube="1.00:lVPPPpyUOR4"
+
+==============================
+``source`` Element
+==============================
 
+The optional ``source`` element contains the following attribute.
+
+.. list-table::
+   :widths: 10 70
+   :header-rows: 1
+
+   * - Attribute
+     - Meaning
+   * - ``src``
+     - The file path for the video file.
 
 *************************************
 Example Video Component XML File
@@ -120,16 +124,15 @@ The following example shows an XML file for a video component.
 .. code-block:: xml
 
   <video
-    youtube="0.75:xGKlr7nT_Zw,1.00:o2pLltkrhGM,1.25:XGsB9bA6rGU,1.50:_HuIF16HdTA"
-    url_name="Introduction_Lecture"
-    display_name="Introduction Lecture"
-    download_video="true"
-    html5_sources="[&quot;https://s3.amazonaws.com/edx-course-videos/school/DemoCourseIntroductionVideo.mov&quot;]"
-    source=""
-    youtube_id_0_75="xGKlr7nT_Zw"
-    youtube_id_1_0="o2pLltkrhGM"
-    youtube_id_1_25="XGsB9bA6rGU"
-    youtube_id_1_5="_HuIF16HdTA">
+    youtube="1.00:lVPPPpyUOR4"
+    url_name="purpose_power_reach"
+    display_name="The Purpose, Power and Reach of the Open edX® Platform"
+    edx_video_id=""
+    end_time="00:00:00"
+    html5_sources="[]"
+    start_time="00:00:00"
+    track=""
+    youtube_id_1_0="lVPPPpyUOR4">
 
     <source src="https://s3.amazonaws.com/edx-course-videos/mit-6002x/6002-Tutorial-00010_100.mov"/>
   </video>
