From 6d33cbb6e9b568c6cbecf8503fe0950094d7daf7 Mon Sep 17 00:00:00 2001 From: sarina Date: Thu, 6 Nov 2025 13:37:35 -0500 Subject: [PATCH 01/22] OLX overview overhaul --- source/educators/navigation/olx.rst | 41 +++--- source/educators/olx/about/overview.rst | 2 - .../educators/olx/about/short-description.rst | 2 - source/educators/olx/assets/assets.rst | 3 - .../olx/components/discussion-components.rst | 2 - .../olx/components/html-components.rst | 2 - .../olx/components/problem-components.rst | 2 - .../olx/components/video-components.rst | 2 - .../content_experiments_test_olx.rst | 2 - source/educators/olx/directory-structure.rst | 117 ++++++++++++------ .../olx/example-course/insider-course-xml.rst | 2 - .../olx/example-course/insider-structure.rst | 11 +- source/educators/olx/front_matter/read_me.rst | 30 ----- source/educators/olx/getting-started.rst | 24 ++-- .../course-structure-overview.rst | 2 - .../olx/organizing-course/course-xml-file.rst | 1 - source/educators/olx/pages/pages.rst | 1 - .../educators/olx/policies/assets-policy.rst | 2 - source/educators/olx/policies/course.rst | 2 - source/educators/olx/policies/grading.rst | 2 - .../olx/problem-xml/symbolic_response.rst | 2 - source/educators/olx/studio-example/index.rst | 66 ---------- .../manual-testing-structure.rst | 3 - source/educators/olx/what-is-olx.rst | 17 +-- 24 files changed, 125 insertions(+), 215 deletions(-) delete mode 100644 source/educators/olx/front_matter/read_me.rst delete mode 100644 source/educators/olx/studio-example/index.rst diff --git a/source/educators/navigation/olx.rst b/source/educators/navigation/olx.rst index 96e9acc52..30622ce44 100644 --- a/source/educators/navigation/olx.rst +++ b/source/educators/navigation/olx.rst @@ -16,7 +16,6 @@ OLX General Information :maxdepth: 1 :glob: - ../olx/front_matter/read_me.rst ../olx/what-is-olx.rst ../olx/getting-started.rst @@ -33,6 +32,20 @@ This topic describes the structure of a generic OLX (open learning XML) course. ../olx/directory-structure.rst +.. _OLX Example Course: + +Example of an OLX Course +******************************************************* + +.. toctree:: + :maxdepth: 1 + :glob: + + ../olx/example-course/index.rst + ../olx/example-course/insider-structure.rst + ../olx/example-course/insider-course-xml.rst + ../olx/studio-example/manual-testing-structure.rst + .. _OLX Policies: Policies @@ -182,30 +195,4 @@ The topics in this section describe how to use OLX (open learning XML) to create /educators/how-tos/advanced_features/manage_content_experiments.rst /educators/how-tos/advanced_features/add_content_experiments_olx.rst ../olx/content-experiments/content_experiments_test_olx.rst - - -.. _OLX Example Course: - -Example of an OLX Course -******************************************************* - -.. toctree:: - :maxdepth: 1 - :glob: - - ../olx/example-course/index.rst - ../olx/example-course/insider-structure.rst - ../olx/example-course/insider-course-xml.rst - -.. _OLX Example Studio Course: - -Example of OLX for a Studio Course -******************************************************* - -.. toctree:: - :maxdepth: 1 - :glob: - - ../olx/studio-example/index.rst - ../olx/studio-example/manual-testing-structure.rst diff --git a/source/educators/olx/about/overview.rst b/source/educators/olx/about/overview.rst index dc2126f2b..ad88dc8a9 100644 --- a/source/educators/olx/about/overview.rst +++ b/source/educators/olx/about/overview.rst @@ -100,8 +100,6 @@ Replace the placeholders in the following template with your information. :ref:`OLX Directory Structure` (reference) - :ref:`Example of OLX for a Studio Course` (reference) - **Maintenance chart** +--------------+-------------------------------+----------------+--------------------------------+ diff --git a/source/educators/olx/about/short-description.rst b/source/educators/olx/about/short-description.rst index a4f7e922d..b7c566025 100644 --- a/source/educators/olx/about/short-description.rst +++ b/source/educators/olx/about/short-description.rst @@ -33,8 +33,6 @@ description file. :ref:`OLX Directory Structure` (reference) - :ref:`Example of OLX for a Studio Course` (reference) - **Maintenance chart** +--------------+-------------------------------+----------------+--------------------------------+ diff --git a/source/educators/olx/assets/assets.rst b/source/educators/olx/assets/assets.rst index 636674fe7..67158f17b 100644 --- a/source/educators/olx/assets/assets.rst +++ b/source/educators/olx/assets/assets.rst @@ -27,9 +27,6 @@ see :ref:`Course Asset Policy`. :ref:`OLX Directory Structure` (reference) - :ref:`Example of OLX for a Studio Course` (reference) - - **Maintenance chart** diff --git a/source/educators/olx/components/discussion-components.rst b/source/educators/olx/components/discussion-components.rst index 79ada6b08..2641d6922 100644 --- a/source/educators/olx/components/discussion-components.rst +++ b/source/educators/olx/components/discussion-components.rst @@ -130,8 +130,6 @@ The following example shows an XML file for a discussion component. :ref:`OLX Directory Structure` (reference) - :ref:`Example of OLX for a Studio Course` (reference) - **Maintenance chart** +--------------+-------------------------------+----------------+--------------------------------+ diff --git a/source/educators/olx/components/html-components.rst b/source/educators/olx/components/html-components.rst index 6a3da67f7..109d1d0ad 100644 --- a/source/educators/olx/components/html-components.rst +++ b/source/educators/olx/components/html-components.rst @@ -130,8 +130,6 @@ file for the edX Demo course: :ref:`OLX Directory Structure` (reference) - :ref:`Example of OLX for a Studio Course` (reference) - **Maintenance chart** +--------------+-------------------------------+----------------+--------------------------------+ diff --git a/source/educators/olx/components/problem-components.rst b/source/educators/olx/components/problem-components.rst index 3071a4969..e6eda7668 100644 --- a/source/educators/olx/components/problem-components.rst +++ b/source/educators/olx/components/problem-components.rst @@ -330,8 +330,6 @@ content libraries. For more information, see :ref:`OLX Directory Structure` (reference) - :ref:`Example of OLX for a Studio Course` (reference) - **Maintenance chart** +--------------+-------------------------------+----------------+--------------------------------+ diff --git a/source/educators/olx/components/video-components.rst b/source/educators/olx/components/video-components.rst index 7b3d7b959..97f183e4b 100644 --- a/source/educators/olx/components/video-components.rst +++ b/source/educators/olx/components/video-components.rst @@ -147,8 +147,6 @@ The following example shows an XML file for a video component. :ref:`OLX Directory Structure` (reference) - :ref:`Example of OLX for a Studio Course` (reference) - **Maintenance chart** diff --git a/source/educators/olx/content-experiments/content_experiments_test_olx.rst b/source/educators/olx/content-experiments/content_experiments_test_olx.rst index 40a3c463c..da7bd3459 100644 --- a/source/educators/olx/content-experiments/content_experiments_test_olx.rst +++ b/source/educators/olx/content-experiments/content_experiments_test_olx.rst @@ -25,8 +25,6 @@ For more information, see :ref:`Test Content Experiments`. :ref:`OLX Directory Structure` (reference) - :ref:`Example of OLX for a Studio Course` (reference) - **Maintenance chart** +--------------+-------------------------------+----------------+--------------------------------+ diff --git a/source/educators/olx/directory-structure.rst b/source/educators/olx/directory-structure.rst index 5a01ecb7e..70cf7284f 100644 --- a/source/educators/olx/directory-structure.rst +++ b/source/educators/olx/directory-structure.rst @@ -6,7 +6,25 @@ What is the OLX Course Structure? .. tags:: educator, concept -This topic describes the structure of a generic OLX (open learning XML) course. +You can export a course from the Open edX Studio. When you export the course, +you download a ``.tar.gz`` file with the OLX (open learning XML) course content. You +can then extract the course OLX files for use with local tools or a source +control system such as GitHub. This article describes the structure of an OLX +(open learning XML) course in the format that Open edX Studio exports it in. + +.. warning:: + + There are other ways to structure an OLX course that will (currently) import successfully into Studio that + these pages won't get into, as they're not guarenteed by the Open edX project to work in the future. + + Additionally, however a course is written, if that course is imported into Studio, Studio will export + it in the specifically structured form of OLX described in this guide. + + +This section documents how the Open edX Studio currently exports courses, so that +you can understand and manually navigate through the structure of exported +courses. + .. contents:: :local: @@ -15,57 +33,55 @@ This topic describes the structure of a generic OLX (open learning XML) course. For more information about how a specific OLX course is structured, see :ref:`The Structure of a Sample Course`. -For more information about how a course exported from Open edX Studio is structured, -see :ref:`Example of OLX for a Studio Course`. - - **************************************** OLX and Directory File Structures **************************************** All files and subdirectories that comprise your OLX course are stored within -a single directory. - -OLX provides for some flexibility in the directory and file structure -you use to build your course. +a single directory, called the ``course/`` directory. ************************ Top-level Directory ************************ Starting out, it is easiest to create your courseware structure in a -single file, the ``course.xml file``. - -This file can contain your entire course, but in most cases, it is convenient -to split out large chunks of content into individual files. This is typically -done either at the level of large components, such as problems or homework -assignments. +single file, the ``course.xml`` file. -Currently, when Studio exports a course, it places each component in its own -file. +This file *can* contain your entire course, but in Studio exports, content is +split out into individual files. This is done at the level of *components*, such +as problems, videos, or HTML (text components). -For example, the Open edX Platform contains a directory called -`manual-testing-complete`_ that contains a course with all component -types for testing purposes. +For example, the `Open edX DemoX Course `_ +contains a course with many component types, and the `OLX Example Course `_ +(described in more detail in :ref:`The Structure of a Sample Course`) has human-readable +names to better help you follow the flow of Studio OLX exports. Descriptions of the directories needed for a typical course follow. You should set up these directories in preparation for developing your course content. .. note:: - If you are using custom XBlocks, you can include additional directories that - store the XML for XBlocks of that type. + + If you are using custom XBlocks, you can include additional directories that store the XML for XBlocks of that type. ******************* XBlock Directories ******************* -Open EdX course components can be broken out of the main ``course.xml`` file +Open edX course *components* can be broken out of the main ``course.xml`` file into individual files. Those files go into directories of the name of the component type (XML tag). For example, components of type ``html`` can be placed as individual files in the ``html`` directory. If your -course does not contain .html files, or if they are all embedded in +course does not contain ``.html`` files, or if they are all embedded in their top-level components, you do not need to create an ``html`` -directory. +directory. Studio will place all text components into the ``html`` directory. + +As another example, the ``problem`` directory holds one XML file per default +problem type (eg, multiselect, dropdown) in the course. Note that in Studio and +within the pages on docs.openedx.org, these types of problems are known as +"course components". + +There are other directories for other types of course components, such as the +``html``, ``lti``, or ``video`` directories. For information about several examples of these directories, see the following topics. @@ -81,15 +97,14 @@ and directories. Open edX Platform Directories ******************************* -In addition to the course hierarchy, which is designed to be generic -and cross-platform, OLX courses contain a set of JSON and HTML +In addition to the course hierarchy, OLX courses contain a set of JSON and HTML files that specify course policies and non-courseware content. ==================== ``about`` Directory ==================== -The ``about`` directory contains the following files. +The ``about`` directory contains the following files: * ``overview.html``, which contains the content for the course overview page that learners see in the Learning Management System (LMS). @@ -97,13 +112,25 @@ The ``about`` directory contains the following files. * ``short_description.html``, which contains the content for the course in the course list. +Courses exported from Studio will have more in this directory, such as +``about_sidebar.html``, ``entrance_exam_enabled.html``, and ``duration.html``. +We won't go through these files in this documentation at this time. + For more information, see :ref:`Course Overview`. +========================== +``chapter`` Directory +========================== + +The ``chapter`` directory holds one XML file per "course section" in the course. +Note that in Studio and within the pages on docs.openedx.org, "course section" +will be the term used for anything in the ``chapter`` directory. + ==================== ``info`` Directory ==================== -The ``info`` directory contains the following files. +The ``info`` directory contains the following files: * ``handouts.html``, which contains the content for the **Course Handouts** page in the course. @@ -115,16 +142,27 @@ The ``info`` directory contains the following files. ``policies`` Directory ======================= -The ``policies`` directory contains the following files. +The ``policies`` directory contains: -* ``grading_policy.json``, which defines how work is graded in the course. +* ``assets.json``, which defines all files used in the course, such as images. -* ``policy.json``, which defines various settings in the course. +The ``policies`` directory also contains a folder for the course run, which holds: -* ``assets.json``, which defines all files used in the course, such as images. +* ``grading_policy.json``, which defines how work is graded in the course run. + +* ``policy.json``, which defines various settings in the course run. For more information, see :ref:`Course Policies`. +========================== +``sequential`` Directory +========================== + +The ``sequential`` directory holds one XML file per "course subsection" in the course. +Note that in Studio and within the pages on docs.openedx.org, "course subsection" +will be the term used for anything in the ``sequential`` directory. + + ==================== ``static`` Directory ==================== @@ -143,6 +181,15 @@ course. For more information, see :ref:`Course Tabs`. +========================== +``vertical`` Directory +========================== + +The ``vertical`` directory holds one XML file per "course unit" in the course. +Note that in Studio and within the pages on docs.openedx.org, "course unit" +will be the term used for anything in the ``vertical`` directory. + + .. seealso:: :ref:`What is Open Learning XML?` (concept) @@ -153,12 +200,10 @@ For more information, see :ref:`Course Tabs`. :ref:`The Courseware Structure` (reference) - :ref:`Example of OLX for a Studio Course` (reference) - **Maintenance chart** +--------------+-------------------------------+----------------+--------------------------------+ | Review Date | Working Group Reviewer | Release |Test situation | +--------------+-------------------------------+----------------+--------------------------------+ -| | | | | +| 2025-11-06 | sarina | Ulmo | Pass | +--------------+-------------------------------+----------------+--------------------------------+ diff --git a/source/educators/olx/example-course/insider-course-xml.rst b/source/educators/olx/example-course/insider-course-xml.rst index c9ad40f88..1e0e879e5 100644 --- a/source/educators/olx/example-course/insider-course-xml.rst +++ b/source/educators/olx/example-course/insider-course-xml.rst @@ -99,8 +99,6 @@ The learner sees this sequential as follows. :ref:`OLX Directory Structure` (reference) - :ref:`Example of OLX for a Studio Course` (reference) - :ref:`The Courseware Structure` (reference) diff --git a/source/educators/olx/example-course/insider-structure.rst b/source/educators/olx/example-course/insider-structure.rst index d78d699dc..504e67189 100644 --- a/source/educators/olx/example-course/insider-structure.rst +++ b/source/educators/olx/example-course/insider-structure.rst @@ -12,14 +12,11 @@ This topic describes the structure of a sample course known as the `olx-example` :local: :depth: 1 -For information about how a generic OLX (open learning XML) course is -structured, see :ref:`OLX Directory Structure`. - -For information about how a course exported from Open edX Studio is structured, see -:ref:`Example of OLX for a Studio Course`. +For information about how a course exported from Open edX Studio is structured +see :ref:`OLX Directory Structure`. .. note:: - The structure and content of olx-example can change without corresponding + The structure and content of the ``OLX-example-course`` can change without corresponding updates being made to this reference guide. ****************************************** @@ -229,8 +226,6 @@ And: :ref:`OLX Directory Structure` (reference) - :ref:`Example of OLX for a Studio Course` (reference) - :ref:`The Courseware Structure` (reference) diff --git a/source/educators/olx/front_matter/read_me.rst b/source/educators/olx/front_matter/read_me.rst deleted file mode 100644 index 48c34bd2a..000000000 --- a/source/educators/olx/front_matter/read_me.rst +++ /dev/null @@ -1,30 +0,0 @@ -******* -Read Me -******* - -The *Open edX Open Learning XML Guide* provides the information you need to build an -Open edX course through OLX (open learning XML) and supporting files, without using -Studio. - -This documentation is created using RST_ files and Sphinx_. The Open edX community welcomes contributions from Open edX community -members. You can find guidelines for how to :ref:`contribute to Open edX Documentation`. - -.. seealso:: - - :ref:`What is Open Learning XML?` (concept) - - :ref:`Example of an OLX Course` (reference) - - :ref:`Getting Started with OLX` (quickstart) - - :ref:`OLX Directory Structure` (reference) - - :ref:`Example of OLX for a Studio Course` (reference) - -**Maintenance chart** - -+--------------+-------------------------------+----------------+--------------------------------+ -| Review Date | Working Group Reviewer | Release |Test situation | -+--------------+-------------------------------+----------------+--------------------------------+ -| | | | | -+--------------+-------------------------------+----------------+--------------------------------+ diff --git a/source/educators/olx/getting-started.rst b/source/educators/olx/getting-started.rst index d27824766..3a5eabbc5 100644 --- a/source/educators/olx/getting-started.rst +++ b/source/educators/olx/getting-started.rst @@ -1,12 +1,23 @@ .. _Getting Started with OLX: -########################### Getting Started with OLX -########################### +########################## .. tags:: educator, quickstart -To develop your course in OLX (open learning XML), the XML markup format for the Open edX platform, you +The **Open edX Open Learning XML Guide** provides the information you need to +build an Open edX course through OLX (open learning XML) and supporting files, +without (or in addition to) using Studio. + +This documentation is created using RST_ files and Sphinx_. The Open edX +community welcomes contributions from Open edX community members. You can find +guidelines for how to :ref:`contribute to Open edX Documentation`. + +Create an OLX Course +*********************** + +To develop your course in OLX, the XML markup format for the Open edX platform, you complete the following steps. #. :ref:`Define course policies`. @@ -17,9 +28,10 @@ complete the following steps. #. :ref:`Create course components`. #. :ref:`Create problems and tools`. - .. seealso:: + :ref:`OLX Documentation ` (reference) + :ref:`What is Open Learning XML?` (concept) :ref:`Example of an OLX Course` (reference) @@ -30,12 +42,10 @@ complete the following steps. :ref:`The Courseware Structure` (reference) - :ref:`Example of OLX for a Studio Course` (reference) - **Maintenance chart** +--------------+-------------------------------+----------------+--------------------------------+ | Review Date | Working Group Reviewer | Release |Test situation | +--------------+-------------------------------+----------------+--------------------------------+ -| | | | | +| 2025-11-06 | sarina | Ulmo | Pass | +--------------+-------------------------------+----------------+--------------------------------+ diff --git a/source/educators/olx/organizing-course/course-structure-overview.rst b/source/educators/olx/organizing-course/course-structure-overview.rst index 3c1b3735c..f8d49249e 100644 --- a/source/educators/olx/organizing-course/course-structure-overview.rst +++ b/source/educators/olx/organizing-course/course-structure-overview.rst @@ -82,8 +82,6 @@ control grading and content experiments. For more information, see :ref:`OLX Directory Structure` (reference) - :ref:`Example of OLX for a Studio Course` (reference) - **Maintenance chart** +--------------+-------------------------------+----------------+--------------------------------+ diff --git a/source/educators/olx/organizing-course/course-xml-file.rst b/source/educators/olx/organizing-course/course-xml-file.rst index c16a3cb25..bba3f08bd 100644 --- a/source/educators/olx/organizing-course/course-xml-file.rst +++ b/source/educators/olx/organizing-course/course-xml-file.rst @@ -287,7 +287,6 @@ The following example shows a vertical with two components. :ref:`OLX Directory Structure` (reference) - :ref:`Example of OLX for a Studio Course` (reference) **Maintenance chart** diff --git a/source/educators/olx/pages/pages.rst b/source/educators/olx/pages/pages.rst index f574720b8..6753266c0 100644 --- a/source/educators/olx/pages/pages.rst +++ b/source/educators/olx/pages/pages.rst @@ -33,7 +33,6 @@ content. :ref:`OLX Directory Structure` (reference) - :ref:`Example of OLX for a Studio Course` (reference) **Maintenance chart** diff --git a/source/educators/olx/policies/assets-policy.rst b/source/educators/olx/policies/assets-policy.rst index bb04a7042..f82d10824 100644 --- a/source/educators/olx/policies/assets-policy.rst +++ b/source/educators/olx/policies/assets-policy.rst @@ -115,8 +115,6 @@ The following example shows the JSON policy for one image file. :ref:`OLX Directory Structure` (reference) - :ref:`Example of OLX for a Studio Course` (reference) - **Maintenance chart** diff --git a/source/educators/olx/policies/course.rst b/source/educators/olx/policies/course.rst index fd152494d..1e957599a 100644 --- a/source/educators/olx/policies/course.rst +++ b/source/educators/olx/policies/course.rst @@ -171,8 +171,6 @@ follows. :ref:`OLX Directory Structure` (reference) - :ref:`Example of OLX for a Studio Course` (reference) - **Maintenance chart** diff --git a/source/educators/olx/policies/grading.rst b/source/educators/olx/policies/grading.rst index 3b274ca9c..10fb93ad7 100644 --- a/source/educators/olx/policies/grading.rst +++ b/source/educators/olx/policies/grading.rst @@ -89,8 +89,6 @@ Example Grading Policy File :ref:`OLX Directory Structure` (reference) - :ref:`Example of OLX for a Studio Course` (reference) - **Maintenance chart** +--------------+-------------------------------+----------------+--------------------------------+ diff --git a/source/educators/olx/problem-xml/symbolic_response.rst b/source/educators/olx/problem-xml/symbolic_response.rst index 2479138a3..c7e7595a7 100644 --- a/source/educators/olx/problem-xml/symbolic_response.rst +++ b/source/educators/olx/problem-xml/symbolic_response.rst @@ -60,8 +60,6 @@ This is a partial list of features, to be revised over time. :ref:`OLX Directory Structure` (reference) - :ref:`Example of OLX for a Studio Course` (reference) - **Maintenance chart** +--------------+-------------------------------+----------------+--------------------------------+ diff --git a/source/educators/olx/studio-example/index.rst b/source/educators/olx/studio-example/index.rst deleted file mode 100644 index a5c9c0b8c..000000000 --- a/source/educators/olx/studio-example/index.rst +++ /dev/null @@ -1,66 +0,0 @@ -.. _Example of OLX for a Studio Course: - -################################## -Example of OLX for a Studio Course -################################## - -.. tags:: educator, reference - -You can export a course from the Open edX Studio. When you export the course, you -download a .tar.gz file with the OLX (open learning XML) course content. You -can then extract the course OLX files for use with local tools or a source -control system such as GitHub. - -As explained in this document, OLX provides for flexibility in how you -structure your course content. However, the Open edX Studio exports OLX content in a -specific structure. - -This section documents how the Open edX Studio currently exports courses, so that -you can understand and manually navigate through the structure of exported -courses. - -.. note:: - The format of Studio course exports is subject to change. As a result, any - tools that you create specifically for the current Studio export format might - not work for future versions. To avoid problems with manually authored OLX - courses, we strongly recommend that you base any scripts that you create on - the OLX format specification rather than on the current Studio export format. - -In this section, we use a course that is part of the Open edX Platform, the `Manual -Testing`_ course, as an example of the OLX course exported from the Open edX Studio. We -examine the overall structure of the `Manual Testing`_ course, as well as how -the courseware is defined. - -The files for the `Manual Testing`_ course are stored in GitHub, so you can -explore how the course is structured for yourself. - -For more information, see the following topics. - -.. toctree:: - :maxdepth: 2 - - manual-testing-structure - - -.. seealso:: - - :ref:`What is Open Learning XML?` (concept) - - :ref:`Example of an OLX Course` (reference) - - :ref:`Getting Started with OLX` (quickstart) - - :ref:`OLX Directory Structure` (reference) - - :ref:`The Courseware Structure` (reference) - - :ref:`Example of OLX for a Studio Course` (reference) - - -**Maintenance chart** - -+--------------+-------------------------------+----------------+--------------------------------+ -| Review Date | Working Group Reviewer | Release |Test situation | -+--------------+-------------------------------+----------------+--------------------------------+ -| | | | | -+--------------+-------------------------------+----------------+--------------------------------+ \ No newline at end of file diff --git a/source/educators/olx/studio-example/manual-testing-structure.rst b/source/educators/olx/studio-example/manual-testing-structure.rst index 060946cdb..b18b68eb7 100644 --- a/source/educators/olx/studio-example/manual-testing-structure.rst +++ b/source/educators/olx/studio-example/manual-testing-structure.rst @@ -246,9 +246,6 @@ non-courseware parts of the OLX course. For more information, see :ref:`The Courseware Structure` (reference) - :ref:`Example of OLX for a Studio Course` (reference) - - **Maintenance chart** +--------------+-------------------------------+----------------+--------------------------------+ diff --git a/source/educators/olx/what-is-olx.rst b/source/educators/olx/what-is-olx.rst index cb7997ff2..d26a0bab2 100644 --- a/source/educators/olx/what-is-olx.rst +++ b/source/educators/olx/what-is-olx.rst @@ -7,14 +7,17 @@ What is Open Learning XML? .. tags:: educator, concept OLX (open learning XML) is the XML-based standard used to build courses for the -edX Platform. +Open edX Platform. With OLX, you can: -* Move content between instances of Open edX. +* Move content between different Open edX instances, either by using the + ``.tar.gz`` export of OLX that Studio provides, or by hand-writing OLX and + compiling it into a ``.tar.gz`` file (see :ref:`Work with the targz File`). * Create course content outside of Open edX Studio, including by conversion from - other content formats. -* Ensure content remains free of proprietary encoding and allow portability. + other content formats (note: the `cc2olx converter + `_ can be used to convert Common + Cartridge exports into OLX). ************** XML Resources @@ -32,6 +35,8 @@ For a primer on XML, see the `Wikipedia XML entry`_ . .. seealso:: + :ref:`OLX Documentation ` (reference) + :ref:`Example of an OLX Course` (reference) :ref:`Getting Started with OLX` (quickstart) @@ -40,13 +45,11 @@ For a primer on XML, see the `Wikipedia XML entry`_ . :ref:`The Courseware Structure` (reference) - :ref:`Example of OLX for a Studio Course` (reference) - **Maintenance chart** +--------------+-------------------------------+----------------+--------------------------------+ | Review Date | Working Group Reviewer | Release |Test situation | +--------------+-------------------------------+----------------+--------------------------------+ -| | | | | +| 2025-11-06 | sarina | Ulmo | Pass | +--------------+-------------------------------+----------------+--------------------------------+ From 99ac4313b9530b22cea6ceb8e2cfbcaa4821da68 Mon Sep 17 00:00:00 2001 From: sarina Date: Sun, 9 Nov 2025 10:44:12 -0500 Subject: [PATCH 02/22] Update OLX Structure documentation --- .../olx/example-course/insider-structure.rst | 112 +++++++++++------- source/links.txt | 8 +- 2 files changed, 70 insertions(+), 50 deletions(-) diff --git a/source/educators/olx/example-course/insider-structure.rst b/source/educators/olx/example-course/insider-structure.rst index 504e67189..742fd6e85 100644 --- a/source/educators/olx/example-course/insider-structure.rst +++ b/source/educators/olx/example-course/insider-structure.rst @@ -6,60 +6,68 @@ The OLX Structure of a Sample Course .. tags:: educator, reference -This topic describes the structure of a sample course known as the `olx-example`_ course that was originally developed for edX.org. +This topic describes the structure of a sample course known as the +`olx_example_course`_, a course with the structure of an Open edX Studio export. .. contents:: :local: :depth: 1 -For information about how a course exported from Open edX Studio is structured -see :ref:`OLX Directory Structure`. - .. note:: - The structure and content of the ``OLX-example-course`` can change without corresponding + The structure and content of the *olx_example_course* can change without corresponding updates being made to this reference guide. -****************************************** -olx-example and Directory File Structures -****************************************** +************************************************** +olx_example_course and Directory File Structures +************************************************** -All files and subdirectories that comprise olx-example are stored in the -`olx-example course`_ directory in the olx-example Git repository. +All files and subdirectories that comprise *olx_example_course* are stored in the +`olx_example_course course`_ directory in the ``training-courses`` GitHub repository. -.. Image:: /_images/olx-example-images/olx-example-github.png - :alt: The olx-example course in GitHub. +.. admonition:: TODO FIX THIS IMAGE -******************** -Top-level Directory -******************** +.. Image:: /_images/olx-example-images/olx-example-github.png + :alt: The olx_example_course in GitHub, showing the file structure of the ``course/`` directory. -The `olx-example course`_ directory in the olx-example Git repository contains the -``course.xml`` file as well as XBlock and Platform directories. +********************** +Top-level Directories +********************** -* The `course.xml`_ file contains the XML for the courseware. All chapters and - sequentials are defined in ``course.xml``. +The `olx-example_course course`_ directory in the ``training-courses`` GitHub +repository contains the ``course.xml`` file as well as various XBlock and +Platform directories. -* Most verticals are defined in ``course.xml``; two verticals are referenced in - other files. +* The `course.xml`_ file contains the XML for the courseware. In the + ``olx_example_course``, this simply contains the course key, ````; this is how the Studio + export works. It is possible to define course sections, subsections, and units + (``chapter`` s, ``sequential`` s, and ``vertical`` s) within the ``course.xml`` file, however, + if imported into Studio and then exported, the format of the + ``olx_example_course`` will be applied. -* The content of some HTML XBlocks is embedded within ``course.xml``; other - HTML XBlocks are referenced in other files. +* Course sections are defined in the ``chapter`` directory, subsections in the + ``sequential`` directory, and units in the ``vertical`` directory. -* Problems are referenced in other files. +* HTML units are referenced in the ``html`` directory, where you'll find two + files: an XML file that calls an associated HTML file, which defines the HTML + content. -For more information, see :ref:`The olx-example course.xml File`. +* Videos are defined in the ``video`` directory. -****************************** -The HTML XBlock Directory -****************************** +* Problems are referenced in other directories, such as ``problem`` and ``lti``. -While some HTML content is embedded in ``course.xml``, many HTML XBlocks are -stored as separate files in the ``HTML`` directory. +For more information, see the olx_example_course `course.xml`_ file. ============================== Example of a Referenced XBlock ============================== +.. warning:: + + This part of the guide was written in 2013. As of the Teak release, it is + untested and not guaranteed to work when imported into Open edX Studio, + either currently or in future releases. + You can reference an XBlock from the ``course.xml`` file. For example, in ``course.xml``, the first vertical in the courseware contains a @@ -91,6 +99,12 @@ For a learner, that HTML component appears as the first unit of the course. Example of an Inline XBlock ============================== +.. warning:: + + This part of the guide was written in 2013. As of the Teak release, it is + untested and not guaranteed to work when imported into Open edX Studio, + either currently or in future releases. + You can include XBlock content within the ``course.xml`` file. You can do this for ease of reading and maintenance when you do not need to reuse the content. @@ -128,7 +142,7 @@ way as a referenced HTML component does. Platform Directories ******************** -The olx-example course contains information in the course subdirectories as +The olx_example_course course contains information in the course subdirectories as described below. ==================== @@ -165,7 +179,7 @@ The ``policies`` directory contains the following files. * ``assets.json``, which defines all files used in the course, such as images. -* A course directory named ``course``, which contains: +* A course directory named ``2025`` (the "course run"), which contains: * ``grading_policy.json``, which defines how student work is graded in the course. @@ -187,30 +201,34 @@ For more information, see :ref:`Course Assets`. ``vertical`` Directory ======================= -The ``vertical`` directory contains the XML for two verticals used in the +The ``vertical`` directory contains the XML for the 14 units used in the course. -* ``constructive_ora_exercise.xml`` -* ``in_class_ora.xml`` +You can embed *units* (verticals) in the ``course.xml`` file, however this method +is not guaranteed to work on Open edX Studio imports. It is recommended +to store XML for units in separate files in the ``vertical`` directory. -You can embed verticals in the ``course.xml`` file, and this is usually the -most straightforward option. However, with OLX, you can also store XML for -verticals in separate files in the ``vertical`` directory. - -In this case, verticals for open response assessments are stored in their own -files. - -The vertical files are referenced in ``course.xml`` as follows: +The *units* are referenced in associated XML files for course *subsections* (in the +``sequential/`` directory). For example, in +``sequential/subsection_1_midterm_exam.xml``, you'll see: .. code-block:: html - + + + + + + -And: +And in ``vertical/unit_1_input_problems.xml``: .. code-block:: html - + + + + .. seealso:: @@ -234,6 +252,8 @@ And: +--------------+-------------------------------+----------------+--------------------------------------------------------------------------------------------------------------------+ | Review Date | Reviewer | Release | Test situation | +--------------+-------------------------------+----------------+--------------------------------------------------------------------------------------------------------------------+ +| 2025-11-06 | sarina | Ulmo | Pass | ++--------------+-------------------------------+----------------+--------------------------------------------------------------------------------------------------------------------+ | 2025-03-19 | Peter Pinch | Sumac |`Fail content `_ | | | Sarina Canelake | |`Fail insider course hosting `_ | +--------------+-------------------------------+----------------+--------------------------------------------------------------------------------------------------------------------+ diff --git a/source/links.txt b/source/links.txt index 746cc0d9c..d75d31f05 100644 --- a/source/links.txt +++ b/source/links.txt @@ -24,13 +24,13 @@ .. _2014.xml: https://github.com/openedx/edx-platform/blob/master/common/test/data/manual-testing-complete/course/2014.xml -.. _olx-example: https://github.com/openedx/training-courses/tree/main/olx-example +.. _olx_example_course: https://github.com/openedx/training-courses/tree/main/olx_example_course -.. _olx-example course: https://github.com/openedx/training-courses/tree/main/olx-example/course +.. _olx_example_course course: https://github.com/openedx/training-courses/tree/main/olx_example_course/course -.. _Week_overview.html: https://github.com/openedx/training-courses/blob/main/olx-example/course/html/Week_overview.html +.. _Week_overview.html: https://github.com/openedx/training-courses/blob/main/olx_example_course/course/html/Week_overview.html -.. _course.xml: https://github.com/openedx/training-courses/blob/main/olx-example/course/course.xml +.. _course.xml: https://github.com/openedx/training-courses/blob/main/olx_example_course/course/course.xml .. _Open edX Demo Course GitHub: https://github.com/openedx/openedx-demo-course From bfc7fc2fa074b49230b829e5fb80133dc6f2d2b1 Mon Sep 17 00:00:00 2001 From: sarina Date: Sun, 9 Nov 2025 10:48:27 -0500 Subject: [PATCH 03/22] Add references to the targz article --- source/educators/navigation/olx.rst | 2 ++ source/educators/olx/directory-structure.rst | 11 +++++++---- .../olx/example-course/insider-course-xml.rst | 2 ++ .../olx/example-course/insider-structure.rst | 2 ++ 4 files changed, 13 insertions(+), 4 deletions(-) diff --git a/source/educators/navigation/olx.rst b/source/educators/navigation/olx.rst index 30622ce44..eb27acfc8 100644 --- a/source/educators/navigation/olx.rst +++ b/source/educators/navigation/olx.rst @@ -19,6 +19,8 @@ OLX General Information ../olx/what-is-olx.rst ../olx/getting-started.rst +:ref:`Work with the targz File` + .. _OLX Course Structure: OLX Course Structure diff --git a/source/educators/olx/directory-structure.rst b/source/educators/olx/directory-structure.rst index 70cf7284f..1b88a1f4f 100644 --- a/source/educators/olx/directory-structure.rst +++ b/source/educators/olx/directory-structure.rst @@ -7,10 +7,11 @@ What is the OLX Course Structure? .. tags:: educator, concept You can export a course from the Open edX Studio. When you export the course, -you download a ``.tar.gz`` file with the OLX (open learning XML) course content. You -can then extract the course OLX files for use with local tools or a source -control system such as GitHub. This article describes the structure of an OLX -(open learning XML) course in the format that Open edX Studio exports it in. +you download a ``.tar.gz`` file with the OLX (open learning XML) course content. +You can then extract the course OLX files for use with local tools or a source +control system such as GitHub (see :ref:`Work with the targz File`). This +article describes the structure of an OLX (open learning XML) course in the +format that Open edX Studio exports it in. .. warning:: @@ -200,6 +201,8 @@ will be the term used for anything in the ``vertical`` directory. :ref:`The Courseware Structure` (reference) + :ref:`Work with the targz File` (reference) + **Maintenance chart** +--------------+-------------------------------+----------------+--------------------------------+ diff --git a/source/educators/olx/example-course/insider-course-xml.rst b/source/educators/olx/example-course/insider-course-xml.rst index 1e0e879e5..20bf9eb69 100644 --- a/source/educators/olx/example-course/insider-course-xml.rst +++ b/source/educators/olx/example-course/insider-course-xml.rst @@ -101,6 +101,8 @@ The learner sees this sequential as follows. :ref:`The Courseware Structure` (reference) + :ref:`Work with the targz File` (reference) + **Maintenance chart** diff --git a/source/educators/olx/example-course/insider-structure.rst b/source/educators/olx/example-course/insider-structure.rst index 742fd6e85..6ad4b7c16 100644 --- a/source/educators/olx/example-course/insider-structure.rst +++ b/source/educators/olx/example-course/insider-structure.rst @@ -246,6 +246,8 @@ And in ``vertical/unit_1_input_problems.xml``: :ref:`The Courseware Structure` (reference) + :ref:`Work with the targz File` (reference) + **Maintenance chart** From 702d9a2d7c5599adbb0550320b2bf1807fb35d17 Mon Sep 17 00:00:00 2001 From: sarina Date: Sun, 9 Nov 2025 10:55:12 -0500 Subject: [PATCH 04/22] More direct language regarding alternative course.xml structures --- source/educators/olx/directory-structure.rst | 23 +++++++------- .../olx/example-course/insider-course-xml.rst | 30 ++++++++++++------- 2 files changed, 31 insertions(+), 22 deletions(-) diff --git a/source/educators/olx/directory-structure.rst b/source/educators/olx/directory-structure.rst index 1b88a1f4f..f297a6816 100644 --- a/source/educators/olx/directory-structure.rst +++ b/source/educators/olx/directory-structure.rst @@ -15,8 +15,8 @@ format that Open edX Studio exports it in. .. warning:: - There are other ways to structure an OLX course that will (currently) import successfully into Studio that - these pages won't get into, as they're not guarenteed by the Open edX project to work in the future. + There are other ways to structure an OLX course that may currently import successfully into Studio that + these pages won't get into, as they're not guaranteed by the Open edX project to work in Open edX Studio in the future. Additionally, however a course is written, if that course is imported into Studio, Studio will export it in the specifically structured form of OLX described in this guide. @@ -45,17 +45,16 @@ a single directory, called the ``course/`` directory. Top-level Directory ************************ -Starting out, it is easiest to create your courseware structure in a -single file, the ``course.xml`` file. +The top-level ``course.xml`` file *can* contain your entire course, but in +Studio exports, content is split out into individual files. This is done at the +level of *components*, such as problems, videos, or HTML (text components). -This file *can* contain your entire course, but in Studio exports, content is -split out into individual files. This is done at the level of *components*, such -as problems, videos, or HTML (text components). - -For example, the `Open edX DemoX Course `_ -contains a course with many component types, and the `OLX Example Course `_ -(described in more detail in :ref:`The Structure of a Sample Course`) has human-readable -names to better help you follow the flow of Studio OLX exports. +For example, the `Open edX DemoX Course +`_ contains a course with many +component types, and the `OLX Example Course +`_ +(described in more detail in :ref:`The Structure of a Sample Course`) has +human-readable names to better help you follow the flow of Studio OLX exports. Descriptions of the directories needed for a typical course follow. You should set up these directories in preparation for developing your course content. diff --git a/source/educators/olx/example-course/insider-course-xml.rst b/source/educators/olx/example-course/insider-course-xml.rst index 20bf9eb69..27fc93b50 100644 --- a/source/educators/olx/example-course/insider-course-xml.rst +++ b/source/educators/olx/example-course/insider-course-xml.rst @@ -1,29 +1,33 @@ .. _The olx-example course.xml File: -################################### -The olx-example ``course.xml`` File -################################### +######################################### +The ``course.xml`` file (advanced usage) +######################################### .. tags:: educator, reference -The `olx-example`_ course is a sample course that was originally developed for edX.org. +.. warning:: -The courseware for `olx-example`_ is defined in the `course.xml`_ file and -follows the organization described in :ref:`The Courseware Structure`. + This page was written in 2013 and may no longer work for imports into Open edX Studio. + Alternative ways of structuring OLX aside from the Studio export format described elsewhere + in this OLX guide are not guaranteed by the Open edX project to work with Open edX Studio in the future. + + Additionally, however a course is written, if that course is imported into Studio, Studio will export + it in the specifically structured form of OLX described elsewhere in this guide. .. contents:: :local: :depth: 1 ***************************** -olx-example Course Hierarchy +Example Course Hierarchy ***************************** -The olx-example courseware is organized into chapters, sequentials, and +Open edX courseware is organized into chapters, sequentials, and verticals. For example, the following XML defines the first chapter, sequential, and -vertical in the course. +vertical directly in the ``course.xml`` file. .. code-block:: xml @@ -53,11 +57,15 @@ Sequentials that Contain XBlocks ********************************* One advantage of OLX (open learning XML) is the flexibility it allows in how -you organize your course. For example, olx-example demonstrates that you can +you organize your course. For example, you can nest XBlocks and problems directly in a sequential, without the need for a vertical. This streamlines the course creation process while maintaining consistency in how students interact with courseware. +.. warning:: + + This structure is not guaranteed to successfully import into Open edX Studio. + The following example XML defines a sequential that has, as children, an HTML XBlock, a reference to a vertical that is defined in another file, and a reference to a problem defined in another file. @@ -109,6 +117,8 @@ The learner sees this sequential as follows. +--------------+-------------------------------+----------------+--------------------------------------------------------------------------------------------------------------------+ | Review Date | Reviewer | Release | Test situation | +--------------+-------------------------------+----------------+--------------------------------------------------------------------------------------------------------------------+ +| 2025-11-06 | sarina | Ulmo | Deprecated - this method is no longer guaranteed to work with Open edX Studio | ++--------------+-------------------------------+----------------+--------------------------------------------------------------------------------------------------------------------+ | 2025-04-11 | Sarina Canelake | Sumac |`Fail `_ | +--------------+-------------------------------+----------------+--------------------------------------------------------------------------------------------------------------------+ From 85739c4d9c8fc823e96cffafe8b2bd01e666473b Mon Sep 17 00:00:00 2001 From: sarina Date: Sun, 9 Nov 2025 11:26:16 -0500 Subject: [PATCH 05/22] Update course policy.json documentation --- source/educators/olx/policies/course.rst | 290 +++++++++++++---------- 1 file changed, 166 insertions(+), 124 deletions(-) diff --git a/source/educators/olx/policies/course.rst b/source/educators/olx/policies/course.rst index 1e957599a..6db06f064 100644 --- a/source/educators/olx/policies/course.rst +++ b/source/educators/olx/policies/course.rst @@ -27,66 +27,70 @@ attribute in the ``course.xml`` file. Course Policy JSON Objects ************************************ - .. list-table:: - :widths: 10 80 - :header-rows: 0 - - * - ``start`` - - The start date for the course. For example: ``"2017-09-05T12:00"``. - * - ``advertised_start`` - - The start date displayed in the course listing and course about pages. - For example: ``"2017-09-05T12:00``. - * - ``disable_policy_graph`` - - Whether the policy graph should be disabled (``true``) or not - (``false)``. - * - ``enrollment_start``, ``enrollment_end`` - - The dates in which students can enroll in the course. For example, - ``"2017-09-05T12:00"``. If not specified, students can enroll any - time. - * - ``end`` - - The end date for the course. For example: ``"2017-11-05T12:00"``. - * - ``end_of_course_survey_url`` - - The URL for an end of course survey. The link is shown after the - course is over, next to certificate download links. - * - ``tabs`` - - Custom pages, or tabs, in the courseware. See below for details. - * - ``discussion_blackouts`` - - An array of time intervals during which students cannot create or edit - discussion posts. For example, you could specify blackout dates during - exams. For example: - - ``[[""2017-10-29T04:00", "2017-11-03T04:00"], ["2017-12-30T04:00", "2018-01-02T04:00"]]`` - - Course team members with the Discussion Moderator, Community TAs, or - Administrator role are not restricted during blackout periods. - - * - ``show_calculator`` - - Whether the calculator is shown in the course (``true``) or not - (``false)``. - * - ``days_early_for_beta`` - - The number of days early that students in the beta-testers group can - access the course. - * - ``cohort_config`` - - - * ``cohorted`` : Boolean. Set to ``true`` if this course uses - student cohorts. If so, all inline discussions are automatically - cohorted, and top-level discussion topics are configurable via the - ``cohorted_discussions`` list. Default is ``false``, not cohorted). - * ``cohorted_discussions``: list of discussion topics that should be - cohorted. Any not specified in this list are not cohorted. - * ``auto_cohort_groups``: ``["group name 1", "group name 2", ...]`` - If ``cohorted`` is ``true``, each student is automatically assigned - to a random group from this list, creating the group if needed. - * - ``pdf_textbooks`` - - Have pdf-based textbooks on tabs in the courseware. See below for - details. - * - ``html_textbooks`` - - The addition of HTML-based textbooks on tabs in the courseware has - been deprecated. - - - -.. disable_policy_graph above had "SUPPORTED?" after it, moved to this comment 26 Oct 2015 - Alison +.. note:: + + This is a partial list of supported fields in the ``policy.json`` file. + Many more are available; these can be variously found on the Open edX Studio's "Advanced + Settings" page, the Pages & Resources view, and the Course Settings page. + + + +.. list-table:: + :widths: 10 80 + :header-rows: 0 + + * - ``start`` + - The start date for the course, in UTC. For example: ``"2025-06-01T00:00:00Z"``. + * - ``advertised_start`` + - The start date, in UTC, displayed in the course listing and course about pages. + For example: ``"2025-06-15T00:00:00Z``. + * - ``advanced_modules`` + - A list of non-standard XBlocks to use in the course, eg ``["lti", "scorm"]`` + * - ``enrollment_start``, ``enrollment_end`` + - The dates (in UTC) in which students can enroll in the course. For example, + ``"2025-05-01T00:00:00Z"``. If not specified, students can enroll any + time. + * - ``end`` + - The end date for the course, in UTC. For example: ``"2027-06-01T12:00:00Z"``. + * - ``graceperiod`` + - The amount of time learners have after a deadline to provide their answers, + for example, ``"7200 seconds"``. + * - ``tabs`` + - Custom pages, or tabs, in the courseware. See below for details. + * - ``discussion_blackouts`` + - An array of time intervals during which students cannot create or edit + discussion posts. For example, you could specify blackout dates during + exams. For example: + + ``[[""2017-10-29T04:00", "2017-11-03T04:00"], ["2017-12-30T04:00", "2018-01-02T04:00"]]`` + + Course team members with the Discussion Moderator, Community TAs, or + Administrator role are not restricted during blackout periods. + + * - ``show_calculator`` + - Whether the calculator is shown in the course (``true``) or not + (``false``). + * - ``days_early_for_beta`` + - The number of days early that students in the beta-testers group can + access the course. + * - ``cohort_config`` + - + * ``cohorted`` : Boolean. Set to ``true`` if this course uses + student cohorts. If so, all inline discussions are automatically + cohorted, and top-level discussion topics are configurable via the + ``cohorted_discussions`` list. Default is ``false``, not cohorted). + * ``cohorted_discussions``: list of discussion topics that should be + cohorted. Any not specified in this list are not cohorted. + * ``auto_cohort_groups``: ``["group name 1", "group name 2", ...]`` + If ``cohorted`` is ``true``, each student is automatically assigned + to a random group from this list, creating the group if needed. + * - ``pdf_textbooks`` + - Have pdf-based textbooks on tabs in the courseware. See below for + details. + * - ``html_textbooks`` + - The addition of HTML-based textbooks on tabs in the courseware has + been deprecated. + ******************************* Example Course Policy File @@ -95,69 +99,107 @@ Example Course Policy File An example with a few of the settings defined in the course policy file follows. -:: - - { - "course/course": { - "advanced_modules": [ - "poll", - "survey", - ], - "discussion_blackouts": [], - "discussion_topics": { - "General": { - "id": "course" - } - "show_calculator": true, - "show_reset_button": true, - "start": "2017-10-01T00:30:00Z", - "tabs": [ - { - "course_staff_only": false, - "name": "Course", - "type": "course_info" - }, - { - "course_staff_only": false, - "name": "Discussion", - "type": "discussion" - }, - { - "course_staff_only": false, - "is_hidden": true, - "name": "Wiki", - "type": "wiki" - }, - { - "course_staff_only": false, - "name": "Progress", - "type": "progress" - }, - { - "course_staff_only": true, - "name": "Staff only (Alison)", - "type": "static_tab", - "url_slug": "7cf2fccec33541dc81ce5e0e34e2689c" - } - ], - "user_partitions": [ - { - "active": true, - "description": "The groups in this configuration can be mapped to cohort groups in the LMS.", - "groups": [ - { - "id": 1124782865, - "name": "Group A", - "version": 1 - }, - { - "id": 254579781, - "name": "Group B", - "version": 1 - } - } - ] - } +.. code-block:: json + + + + { + "course/2025": { + "advanced_modules": [ + "edx_sga", + "lti", + "scorm", + "poll", + "survey" + ], + "cert_html_view_enabled": true, + "certificates_display_behavior": "CertificatesDisplayBehaviors.END", + "course_image": "Intro_to_OLX_course_card.png", + "discussion_topics": { + "General": { + "id": "course" + } + }, + "discussions_settings": { + "enable_graded_units": false, + "enable_in_context": true, + "provider_type": "openedx", + "unit_level_visibility": true + }, + "display_name": "OLX Example Course", + "end": "2027-06-01T00:00:00Z", + "enrollment_end": "2026-01-31T00:00:00Z", + "enrollment_start": "2025-05-01T00:00:00Z", + "graceperiod": "7200 seconds", + "instructor_info": { + "instructors": [] + }, + "language": "en", + "learning_info": [], + "lti_passports": [ + "codeboard:codeboard_key_1:codeboard_secret_1234", + "jupyter:811a447706c152588c436ee13addeeb889e7f256033679408737bd5bc4118225:869e9639af7de74929b13ae17ad22e4efb60d9d112143e287589289102e1de00" + ], + "minimum_grade_credit": 0.8, + "pdf_textbooks": [ + { + "chapters": [ + { + "title": "Full Book", + "url": "/asset-v1:OpenedX+OLXex+2025+type@asset+block@Education_for_a_Digital_World.pdf" + } + ], + "id": "6Education_for_a_Digital_World", + "tab_title": "Education for a Digital World: Advice, Guidelines and Effective Practice from Around Globe" + } + ], + "start": "2025-06-01T00:00:00Z", + "tabs": [ + { + "course_staff_only": false, + "name": "Course", + "type": "courseware" + }, + { + "course_staff_only": false, + "name": "Progress", + "type": "progress" + }, + { + "course_staff_only": false, + "name": "Dates", + "type": "dates" + }, + { + "course_staff_only": false, + "name": "Discussion", + "type": "discussion" + }, + { + "course_staff_only": false, + "is_hidden": true, + "name": "Wiki", + "type": "wiki" + }, + { + "course_staff_only": false, + "name": "Textbooks", + "type": "textbooks" + }, + { + "course_staff_only": false, + "name": "Textbooks", + "type": "pdf_textbooks" + }, + { + "course_staff_only": false, + "name": "HTML Custom Tab", + "type": "static_tab", + "url_slug": "html_custom_tab" + } + ] + } + } .. seealso:: @@ -177,5 +219,5 @@ follows. +--------------+-------------------------------+----------------+--------------------------------+ | Review Date | Working Group Reviewer | Release |Test situation | +--------------+-------------------------------+----------------+--------------------------------+ -| | | | | +| 2025-11-06 | sarina | Ulmo | Pass | +--------------+-------------------------------+----------------+--------------------------------+ From 71afd7f5d1645d72ef376816d36a81fcfde87630 Mon Sep 17 00:00:00 2001 From: sarina Date: Sun, 9 Nov 2025 11:30:48 -0500 Subject: [PATCH 06/22] Update course grading_policy.json documentation --- source/educators/olx/policies/grading.rst | 62 +++++++++++++---------- 1 file changed, 36 insertions(+), 26 deletions(-) diff --git a/source/educators/olx/policies/grading.rst b/source/educators/olx/policies/grading.rst index 10fb93ad7..a6e2273e5 100644 --- a/source/educators/olx/policies/grading.rst +++ b/source/educators/olx/policies/grading.rst @@ -39,15 +39,16 @@ Course Policy JSON Objects * - ``GRADER`` - For each assignment type: + * ``drop_count``: The number of assignments of this type that can be + dropped when calculating the final grade. * ``min_count``: TBD - * ``weight``: The percentage of the total grade determined by - assignments of this type. The total value for all assignment types - must equal 1.0. - * ``type``: The name of the assignment type. * ``short_label``: The label for the assignment type shown on the student's Progress page. - * ``drop_count``: The number of assignments of this type that can be - dropped when calculating the final grade. + * ``type``: The name of the assignment type. + * ``weight``: The percentage of the total grade determined by + assignments of this type (for example, ``0.5`` for 50%). + The total value for all assignment types must equal 1.0. + ******************************* Example Grading Policy File @@ -55,25 +56,34 @@ Example Grading Policy File .. code-block:: json - { - "GRADE_CUTOFFS": {"Pass": 0.6}, - "GRADER": [ - { - "min_count": 3, - "weight": 0.75, - "type": "Homework", - "drop_count": 1, - "short_label": "Ex" - }, - { - "short_label": "", - "min_count": 1, - "type": "Exam", - "drop_count": 0, - "weight": 0.25 - } - ] - } + { + "GRADER": [ + { + "drop_count": 2, + "min_count": 1, + "short_label": "HW", + "type": "Homework", + "weight": 0.3 + }, + { + "drop_count": 0, + "min_count": 1, + "short_label": "Midterm", + "type": "Midterm Exam", + "weight": 0.3 + }, + { + "drop_count": 0, + "min_count": 1, + "short_label": "Final", + "type": "Final Exam", + "weight": 0.4 + } + ], + "GRADE_CUTOFFS": { + "Pass": 0.41 + } + } .. seealso:: @@ -94,5 +104,5 @@ Example Grading Policy File +--------------+-------------------------------+----------------+--------------------------------+ | Review Date | Working Group Reviewer | Release |Test situation | +--------------+-------------------------------+----------------+--------------------------------+ -| | | | | +| 2025-11-06 | sarina | Ulmo | Pass | +--------------+-------------------------------+----------------+--------------------------------+ From 91b39851301d8cc73c72e335b4ca504599f4fd9a Mon Sep 17 00:00:00 2001 From: sarina Date: Sun, 9 Nov 2025 11:42:38 -0500 Subject: [PATCH 07/22] Update course assets.json documentation --- .../educators/olx/policies/assets-policy.rst | 121 ++++++++++-------- 1 file changed, 70 insertions(+), 51 deletions(-) diff --git a/source/educators/olx/policies/assets-policy.rst b/source/educators/olx/policies/assets-policy.rst index f82d10824..ba152c84d 100644 --- a/source/educators/olx/policies/assets-policy.rst +++ b/source/educators/olx/policies/assets-policy.rst @@ -7,8 +7,7 @@ Create the Course Asset Policy in OLX .. tags:: educator, how-to You create an asset policy file to provide details of the assets used in your -course. Assets can include image files, textbooks, handouts, and supporting -JavaScript files. +course. Assets can include image files, textbooks, and handouts. .. contents:: :local: @@ -31,73 +30,93 @@ structure. Asset Policy JSON Objects ************************************ - .. list-table:: - :widths: 10 80 - :header-rows: 0 - - * - ``contentType`` - - The MIME type of the file. - * - ``displayname`` - - The file name. - * - ``locked`` - - ``true`` if users can only access the file from within your course. - ``false`` if users can access the file from outside of your course. - * - ``content_son`` - - A collection that contains: +For each asset, the following fields must be provided in a JSON dict for that asset: + +.. list-table:: + :widths: 10 80 + :header-rows: 0 + + * - ``contentType`` + - The MIME type of the file. + * - ``content_son`` + - A collection that contains: * ``category``: Equal to ``asset``. - * ``name``: The file name. * ``course``: The course number. + * ``name``: The file name. * ``tag``: * ``org``: The organization that created the course. * ``revision`` - * - ``filename`` - - The full path and name of the file in the Open edX Platform. - * - ``import_path`` - - TBD - * - ``thumbnail_location`` - - An array containing: + * - ``displayname`` + - The file name. + * - ``filename`` + - The full path and name of the file in the Open edX Platform. + * - ``import_path`` + - ``null`` (TBD - why?) + * - ``locked`` + - ``true`` if users can only access the file from within your course. + ``false`` if users can access the file from outside of your course. + * - ``thumbnail_location`` + - Either ``null`` (for assets without a thumbnail type, such as PDFs), or, an array containing: * ``c4x`` * The organization. * The course number. * ``thumbnail`` * The filename for the thumbnail. + * ``null`` (TBD - why?) ******************************* Example Asset Policy File ******************************* -The following example shows the JSON policy for one image file. +The following example shows the JSON policy for an image file and a PDF textbook. .. code-block:: json - { - "dashboard.png": - { - "contentType": "image/png", - "displayname": "dashboard.png", - "locked": false, - "content_son": - { - "category": "asset", - "name": "dashboard.png", - "course": "Course number", - "tag": "c4x", - "org": "Organization", - "revision": null - }, - "filename": "/c4x/Organization/Course-number/asset/dashboard.png", - "import_path": null, - "thumbnail_location": - [ - "c4x", - "Organization", - "Course number", - "thumbnail", - "dashboard.jpg", - null - ] - } + { + "Education_for_a_Digital_World.pdf": { + "contentType": "application/pdf", + "content_son": { + "category": "asset", + "course": "OLXex", + "name": "Education_for_a_Digital_World.pdf", + "org": "OpenedX", + "revision": null, + "run": "2025", + "tag": "c4x" + }, + "custom_md5": "be2c4a1483397675d7bd124c100d02f9", + "displayname": "Education_for_a_Digital_World.pdf", + "filename": "asset-v1:OpenedX+OLXex+2025+type@asset+block@Education_for_a_Digital_World.pdf", + "import_path": null, + "locked": false, + "thumbnail_location": null + }, + "Intro_to_OLX_course_card.png": { + "contentType": "image/png", + "content_son": { + "category": "asset", + "course": "OLXex", + "name": "Intro_to_OLX_course_card.png", + "org": "OpenedX", + "revision": null, + "run": "2025", + "tag": "c4x" + }, + "custom_md5": "f007dbebf9fb14d666a01614b97a860e", + "displayname": "Intro to OLX course card.png", + "filename": "asset-v1:OpenedX+OLXex+2025+type@asset+block@Intro_to_OLX_course_card.png", + "import_path": null, + "locked": false, + "thumbnail_location": [ + "c4x", + "OpenedX", + "OLXex", + "thumbnail", + "Intro_to_OLX_course_card-png.jpg", + null + ] + }, } @@ -121,5 +140,5 @@ The following example shows the JSON policy for one image file. +--------------+-------------------------------+----------------+--------------------------------+ | Review Date | Working Group Reviewer | Release |Test situation | +--------------+-------------------------------+----------------+--------------------------------+ -| | | | | +| 2025-11-06 | sarina | Ulmo | Pass | +--------------+-------------------------------+----------------+--------------------------------+ From 5f37329d2383f94b4ff85ef4a0730fa7e6fc12f2 Mon Sep 17 00:00:00 2001 From: sarina Date: Sun, 9 Nov 2025 11:50:12 -0500 Subject: [PATCH 08/22] Update course about dir files --- source/educators/olx/about/overview.rst | 11 +++++++---- source/educators/olx/about/short-description.rst | 8 ++++++-- 2 files changed, 13 insertions(+), 6 deletions(-) diff --git a/source/educators/olx/about/overview.rst b/source/educators/olx/about/overview.rst index ad88dc8a9..ed3f3a084 100644 --- a/source/educators/olx/about/overview.rst +++ b/source/educators/olx/about/overview.rst @@ -13,20 +13,23 @@ searching and registering for the course. Create the Overview File ********************************************* -In the ``overview`` directory, you create an HTML file called +In the ``about`` directory, you create an HTML file called ``overview.html``. ********************************************* Overview Sections ********************************************* -The ``overview.html`` must contain specific sections. +The ``overview.html`` contains specific sections. The default Open edX course +catalog does not style the Overview page based on most of these HTML classes, +however, other course catalogs may (and Open edX Studio will export with these +classes). Each section is wrapped in ``section`` tags. The value of the ``class`` attribute specifies what the section is for and how it is displayed to learners. Within the ``section`` tags, you use valid HTML. -The overview must contain sections with the following names. +The overview may contain section(s) with the following names. * ``about`` * ``prerequisites`` @@ -105,5 +108,5 @@ Replace the placeholders in the following template with your information. +--------------+-------------------------------+----------------+--------------------------------+ | Review Date | Working Group Reviewer | Release |Test situation | +--------------+-------------------------------+----------------+--------------------------------+ -| | | | | +| 2025-11-06 | sarina | Ulmo | Pass | +--------------+-------------------------------+----------------+--------------------------------+ diff --git a/source/educators/olx/about/short-description.rst b/source/educators/olx/about/short-description.rst index b7c566025..46c5dd3ab 100644 --- a/source/educators/olx/about/short-description.rst +++ b/source/educators/olx/about/short-description.rst @@ -8,6 +8,10 @@ Create Short Description in OLX Optionally, you can define a short description for your course. +.. admonition:: TODO what behavior in the new Course Catalog? + + Also, there a limit? (below 150char) + Learners see the short description when they move their cursors over the course image in the catalog. @@ -15,7 +19,7 @@ image in the catalog. Create the Short Description File ********************************************* -You create an HTML file called ``short_description.html`` in the ``overview`` +You create an HTML file called ``short_description.html`` in the ``about`` directory. The short description is limited to 150 characters. @@ -38,5 +42,5 @@ description file. +--------------+-------------------------------+----------------+--------------------------------+ | Review Date | Working Group Reviewer | Release |Test situation | +--------------+-------------------------------+----------------+--------------------------------+ -| | | | | +| 2025-11-06 | sarina | Ulmo | Pass | +--------------+-------------------------------+----------------+--------------------------------+ From 443e50dc1b717a781851c1646a145690516d25a7 Mon Sep 17 00:00:00 2001 From: sarina Date: Sun, 9 Nov 2025 13:03:50 -0500 Subject: [PATCH 09/22] Updates on OLX custom pages and textbooks --- source/educators/olx/assets/assets.rst | 7 +-- source/educators/olx/pages/pages.rst | 35 +++++++++++++-- .../educators/olx/policies/assets-policy.rst | 44 +++++++++++++++++-- 3 files changed, 76 insertions(+), 10 deletions(-) diff --git a/source/educators/olx/assets/assets.rst b/source/educators/olx/assets/assets.rst index 67158f17b..ac796f918 100644 --- a/source/educators/olx/assets/assets.rst +++ b/source/educators/olx/assets/assets.rst @@ -15,8 +15,6 @@ see :ref:`Course Asset Policy`. .. seealso:: - :ref:`Add Course Assets` (reference) - :ref:`Course Asset Policy` (reference) :ref:`What is Open Learning XML?` (concept) @@ -27,11 +25,14 @@ see :ref:`Course Asset Policy`. :ref:`OLX Directory Structure` (reference) + :ref:`Add Course Assets` (via Studio) (reference) + + **Maintenance chart** +--------------+-------------------------------+----------------+--------------------------------+ | Review Date | Working Group Reviewer | Release |Test situation | +--------------+-------------------------------+----------------+--------------------------------+ -| | | | | +| 2025-11-06 | sarina | Ulmo | Pass | +--------------+-------------------------------+----------------+--------------------------------+ diff --git a/source/educators/olx/pages/pages.rst b/source/educators/olx/pages/pages.rst index 6753266c0..846a70381 100644 --- a/source/educators/olx/pages/pages.rst +++ b/source/educators/olx/pages/pages.rst @@ -1,12 +1,12 @@ .. _Course Tabs: -################################# +######################################## Create Course Tabs in OLX -################################# +######################################### .. tags:: educator, how-to -You can add tabs, or pages, to your course. Each page appears in your course's +You can add custom tabs, or pages, to your course. Each page appears in your course's navigation bar. ********************************************* @@ -14,13 +14,40 @@ Create the Tab File ********************************************* For each page you want your course to offer, you create an HTML file in the -``tabs`` directory. +``tabs`` directory. It can be as simple as this: + +*Contents of* ``html_custom_tab.html``: + +.. code-block:: html + +

Welcome to the OLX Example Course!

+ +

This is a custom HTML page added as a custom tab to the course.

You can add any text and HTML markup to the page. Pages can also be links or other types of content. One design pattern is to link a tab to a chromeless XBlock in the courseware, which allows for top-level interactive course content. +Ensure you place the custom tab properly in the ``policy.json`` file as detailed +in :ref:`Course Policies`. + +.. code-block:: json + + { + "course/2025": { + ... + + { + "course_staff_only": false, + "name": "HTML Custom Tab", + "type": "static_tab", + "url_slug": "html_custom_tab" + } + } + + + .. seealso:: :ref:`What is Open Learning XML?` (concept) diff --git a/source/educators/olx/policies/assets-policy.rst b/source/educators/olx/policies/assets-policy.rst index ba152c84d..fbf461bb6 100644 --- a/source/educators/olx/policies/assets-policy.rst +++ b/source/educators/olx/policies/assets-policy.rst @@ -1,8 +1,8 @@ .. _Course Asset Policy: -##################################### -Create the Course Asset Policy in OLX -##################################### +##################################################### +Create Course Assets and Textbooks in OLX +##################################################### .. tags:: educator, how-to @@ -119,6 +119,44 @@ The following example shows the JSON policy for an image file and a PDF textbook }, } +.. _Course Textbooks OLX: + +********************************************* +Create Textbooks +********************************************* + +As described above, first upload a textbook asset to +your course in the ``static`` directory. + +.. admonition:: Accessibility concerns + + See the notes in the :ref:`Add Course Textbooks` article around accessibility - namely, that + PDF textbooks are accessible whereas PNG/image files are not. + +Then, as described above, link it in your ``assets.json`` file. + +Finally, update the ``policy.json`` file (described in :ref:`Course Policies`) +with information in the ``pdf_textbooks`` key: + +.. code-block:: json + + { + "course/2025": { + ... + "pdf_textbooks": [ + { + "chapters": [ + { + "title": "Full Book", + "url": "/asset-v1:OpenedX+OLXex+2025+type@asset+block@Education_for_a_Digital_World.pdf" + } + ], + "id": "6Education_for_a_Digital_World", + "tab_title": "Education for a Digital World: Advice, Guidelines and Effective Practice from Around Globe" + } + ], + ... + } .. seealso:: From 62a15c59b9d829481f7b8a80b373bbffe6e2e1dd Mon Sep 17 00:00:00 2001 From: sarina Date: Mon, 10 Nov 2025 07:08:52 -0700 Subject: [PATCH 10/22] Fix build errors --- source/educators/olx/directory-structure.rst | 2 +- source/educators/olx/example-course/index.rst | 4 ++-- .../olx/example-course/insider-structure.rst | 6 +++-- source/educators/olx/getting-started.rst | 2 +- .../course-structure-overview.rst | 2 +- source/educators/olx/pages/pages.rst | 18 +++++++-------- .../educators/olx/policies/assets-policy.rst | 22 +++++++++---------- 7 files changed, 27 insertions(+), 29 deletions(-) diff --git a/source/educators/olx/directory-structure.rst b/source/educators/olx/directory-structure.rst index f297a6816..c858022ad 100644 --- a/source/educators/olx/directory-structure.rst +++ b/source/educators/olx/directory-structure.rst @@ -179,7 +179,7 @@ For more information, see :ref:`Course Assets`. The ``tabs`` directory contains an HTML file for each page you add to your course. -For more information, see :ref:`Course Tabs`. +For more information, see :ref:`Create tabs, or pages, in your course`. ========================== ``vertical`` Directory diff --git a/source/educators/olx/example-course/index.rst b/source/educators/olx/example-course/index.rst index 7f1855871..56609082c 100644 --- a/source/educators/olx/example-course/index.rst +++ b/source/educators/olx/example-course/index.rst @@ -11,8 +11,8 @@ courses in many ways. While there is no best way to structure courses in all situations, there are best practices that help make an OLX course easier to create and maintain. -This section uses the `olx-example`_ course as an example of how to create an -OLX course. The files for `olx-example`_ are stored in GitHub, so you can +This section uses the `olx_example_course`_ as an example of how to create an +OLX course. The files for the `olx_example_course`_ are stored in GitHub, so you can explore how the course is made for yourself. These topics examine the overall structure of the olx-example course and how the diff --git a/source/educators/olx/example-course/insider-structure.rst b/source/educators/olx/example-course/insider-structure.rst index 6ad4b7c16..563af3a8a 100644 --- a/source/educators/olx/example-course/insider-structure.rst +++ b/source/educators/olx/example-course/insider-structure.rst @@ -24,7 +24,9 @@ olx_example_course and Directory File Structures All files and subdirectories that comprise *olx_example_course* are stored in the `olx_example_course course`_ directory in the ``training-courses`` GitHub repository. -.. admonition:: TODO FIX THIS IMAGE +.. admonition:: TODO + + Fix this image .. Image:: /_images/olx-example-images/olx-example-github.png :alt: The olx_example_course in GitHub, showing the file structure of the ``course/`` directory. @@ -33,7 +35,7 @@ All files and subdirectories that comprise *olx_example_course* are stored in th Top-level Directories ********************** -The `olx-example_course course`_ directory in the ``training-courses`` GitHub +The `olx_example_course course`_ directory in the ``training-courses`` GitHub repository contains the ``course.xml`` file as well as various XBlock and Platform directories. diff --git a/source/educators/olx/getting-started.rst b/source/educators/olx/getting-started.rst index 3a5eabbc5..3bb5b86ac 100644 --- a/source/educators/olx/getting-started.rst +++ b/source/educators/olx/getting-started.rst @@ -23,7 +23,7 @@ complete the following steps. #. :ref:`Define course policies`. #. :ref:`Add course assets`. #. :ref:`Create the course Overview page`. - #. :ref:`Create tabs, or pages, in your course`. + #. :ref:`Create tabs, or pages, in your course`. #. :ref:`Organize Courseware`. #. :ref:`Create course components`. #. :ref:`Create problems and tools`. diff --git a/source/educators/olx/organizing-course/course-structure-overview.rst b/source/educators/olx/organizing-course/course-structure-overview.rst index f8d49249e..feb919e81 100644 --- a/source/educators/olx/organizing-course/course-structure-overview.rst +++ b/source/educators/olx/organizing-course/course-structure-overview.rst @@ -56,7 +56,7 @@ following list describes the types of supported content. more information, see :ref:`Course Assets`. * Course pages are custom pages that you can have appear in the top navigation - menu of your course. For more information, see :ref:`Course Tabs`. + menu of your course. For more information, see :ref:`Create tabs, or pages, in your course`. **************************** Course Policies diff --git a/source/educators/olx/pages/pages.rst b/source/educators/olx/pages/pages.rst index 846a70381..998187b30 100644 --- a/source/educators/olx/pages/pages.rst +++ b/source/educators/olx/pages/pages.rst @@ -1,8 +1,8 @@ -.. _Course Tabs: +.. _Course Tabs OLX: ######################################## Create Course Tabs in OLX -######################################### +######################################## .. tags:: educator, how-to @@ -36,14 +36,12 @@ in :ref:`Course Policies`. { "course/2025": { - ... - - { - "course_staff_only": false, - "name": "HTML Custom Tab", - "type": "static_tab", - "url_slug": "html_custom_tab" - } + { + "course_staff_only": false, + "name": "HTML Custom Tab", + "type": "static_tab", + "url_slug": "html_custom_tab" + }, } diff --git a/source/educators/olx/policies/assets-policy.rst b/source/educators/olx/policies/assets-policy.rst index fbf461bb6..90ea34a20 100644 --- a/source/educators/olx/policies/assets-policy.rst +++ b/source/educators/olx/policies/assets-policy.rst @@ -142,20 +142,18 @@ with information in the ``pdf_textbooks`` key: { "course/2025": { - ... "pdf_textbooks": [ - { - "chapters": [ - { - "title": "Full Book", - "url": "/asset-v1:OpenedX+OLXex+2025+type@asset+block@Education_for_a_Digital_World.pdf" - } - ], - "id": "6Education_for_a_Digital_World", - "tab_title": "Education for a Digital World: Advice, Guidelines and Effective Practice from Around Globe" - } + { + "chapters": [ + { + "title": "Full Book", + "url": "/asset-v1:OpenedX+OLXex+2025+type@asset+block@Education_for_a_Digital_World.pdf" + } + ], + "id": "6Education_for_a_Digital_World", + "tab_title": "Education for a Digital World: Advice, Guidelines and Effective Practice from Around Globe" + } ], - ... } .. seealso:: From fcb98626cc0a675b1de9458f01deda4ef0fed92a Mon Sep 17 00:00:00 2001 From: sarina Date: Fri, 14 Nov 2025 20:25:35 -0500 Subject: [PATCH 11/22] Rewrite organizing-course OLX documents --- source/educators/olx/about/overview.rst | 7 + .../course-structure-overview.rst | 26 +- .../olx/organizing-course/course-xml-file.rst | 292 +++++++++++------- 3 files changed, 194 insertions(+), 131 deletions(-) diff --git a/source/educators/olx/about/overview.rst b/source/educators/olx/about/overview.rst index ed3f3a084..0c9873e60 100644 --- a/source/educators/olx/about/overview.rst +++ b/source/educators/olx/about/overview.rst @@ -6,6 +6,13 @@ Create Course Overview in OLX .. tags:: educator, how-to +.. note:: + + This page describes how to create the Course Overview section for + your course, provided your Open edX instance is using the default + Open edX course catalog. Your Open edX instance might utilize a different + way of publishing and advertising courses. + Each course must have an overview page. Learners see the overview page when searching and registering for the course. diff --git a/source/educators/olx/organizing-course/course-structure-overview.rst b/source/educators/olx/organizing-course/course-structure-overview.rst index feb919e81..41a85b92d 100644 --- a/source/educators/olx/organizing-course/course-structure-overview.rst +++ b/source/educators/olx/organizing-course/course-structure-overview.rst @@ -21,19 +21,23 @@ Courseware is the main content of your course and consists mainly of lessons and assessments. The following list describes how courseware is organized in OLX. -* Course chapters are at the top level of your course and typically - represent a time period. In Studio, chapters are called *sections*. +* Course sections are at the top level of your course and typically + represent a time period. In OLX, sections are defined in the ``chapter`` directory. -* A chapter contains one or more children which correspond to - top-level pages in the course. In Studio, these are called 'subsections' and - are currently restricted to ``sequential`` elements at this - level. OLX supports any XBlock at this level. +* A section contains one or more children ("subsections") which correspond to + top-level pages in the course. In Studio, these + are defined within ``sequential`` elements at this level. -* Courses are composed of structural elements, such as ``sequential`` - and ``vertical``, and leaf-nodes or content elements, such as + .. note:: + + Technically, OLX supports any XBlock at this level. This is not + guaranteed to work upon Studio import. + +* Courses are composed of structural elements, such as ``sequential`` (subsections), + ``vertical`` (units), and leaf-nodes (content elements/components), such as ``html`` or ``problem``. Studio has a fixed hierarchy where children of ``sequential`` elements are ``vertical`` elements (called units), - and children of ``vertical`` elements are leaf elements (called modules). + and children of ``vertical`` elements are leaf elements (called components). * :ref:`Course Components` * :ref:`Problems` @@ -48,7 +52,7 @@ In addition to the courseware described above, you course can contain supplemental content, such as textbooks, custom pages, and files. The following list describes the types of supported content. -* Course about pages appear in the course list for prospective students and are +* Course about pages appear in the default Open edX course catalog for prospective students and are used to market your course. For more information, see :ref:`Course Overview`. * Course assets are any supplemental files you use in your course, such as a @@ -87,5 +91,5 @@ control grading and content experiments. For more information, see +--------------+-------------------------------+----------------+--------------------------------+ | Review Date | Working Group Reviewer | Release |Test situation | +--------------+-------------------------------+----------------+--------------------------------+ -| | | | | +| 2025-11-06 | sarina | Ulmo | Pass | +--------------+-------------------------------+----------------+--------------------------------+ diff --git a/source/educators/olx/organizing-course/course-xml-file.rst b/source/educators/olx/organizing-course/course-xml-file.rst index bba3f08bd..07f46c820 100644 --- a/source/educators/olx/organizing-course/course-xml-file.rst +++ b/source/educators/olx/organizing-course/course-xml-file.rst @@ -6,98 +6,145 @@ The OLX Courseware Structure .. tags:: educator, reference -You develop the courseware structure in the ``course.xml`` file, in the top- -level directory. +The courseware structure in the ``course.xml`` file is defined in the top-level +directory. In Studio, the ``course.xml`` file is simple, and points to the specific +course run xml file in the ``course/run.xml`` file like so: + +.. code-block:: xml + + + +The rest of this page would describe the file that this ``course.xml`` points to, +called `course/2025.xml `_. .. contents:: :local: :depth: 1 -For an example of a ``course.xml`` file, see :ref:`The olx-example course.xml -File`. +.. admonition:: Other course.xml usages + + :ref:`The olx-example course.xml File` describes an alternative way of structuring + the top-level ``course.xml`` file - it is not the format Studio exports in, and may + not be supported by Studio. ************************************* -The ``course.xml`` File +The ``course/run.xml`` File ************************************* -The root element of the ``course.xml`` file is ``course``. +In our example ``course.xml`` file, we point to the 2025 run: -An example of the contents of a ``course.xml`` file follows. +.. code-block:: xml + + + +A partial example of the contents of a ``2025.xml`` file follows. .. code-block:: xml - - . . . - . . . + + . . . + ============================== ``course`` Attributes ============================== +.. note:: + + There are many more ``course`` attributes than described in this guide; no such complete guide of all + available attributes currentliy exists. Many attributes can be discovered by setting them in Studio + and then inspecting the exported ``course/run.xml`` file. + .. list-table:: :widths: 10 70 :header-rows: 1 * - Attribute - Meaning - * - ``advanced_modules`` - - The list of advanced modules, or custom XBlocks, used in your course. * - ``url_name`` - The value in the course URL path directly after the domain, - organization, and course name. The url_name must also be the name of the course outline XML file (without the ``.xml`` extension). + organization, and course name. The url_name must also be the name of the course run XML file (without the ``.xml`` extension). * - ``org`` - The organization sponsoring the course. This value is in the course URL path, following the domain and ``/courses/``. * - ``course`` - The name of the course. This value is in the course URL path, following the organization. + * - ``advanced_modules`` + - The list of advanced modules, or custom XBlocks, used in your course. * - ``course_image`` - - The filename of the image used on the course About page. + - The path to the course image, used in the Open edX Course Catalog and on the learner dashboard + * - ``display_name`` + - The human-readable name, used throughout the course * - ``enrollment_start`` - - The date and time that students can start enrolling in the course. + - The date and time that learners can start enrolling in the course (defined as a UTC datestamp such as ``"2025-05-01T00:00:00Z"``) + * - ``grace_period`` + - The amount of time a learner is allowed to submit beyond a problem's due date (applies across all course elements) + * - ``language`` + - The two-letter `ISO 639 language code `_ that the course is authored in + * - ``lti_passports`` + - A list of LTI passports required for LTI units in the course + * - ``minimum_grade_credit`` + - A floating-point number less than or equal to 1.0 which defines the minimum grade required to obtain a course certificate + * - ``pdf_textbooks`` + - A list of PDF textbooks, each defined with lists that contain information about each chapter and its associated asset file + * - ``start`` + - The date and time that the course starts (defined as a UTC datestamp) ============================================================ -``course`` Element Attributes and Course URLS +``course`` Element Attributes and Course URLs ============================================================ The attributes of the ``course`` element are used to construct URLs in the -course. The following course URL shows where these values are used. +course. The following example URL shows where these values are used (note +different areas of the platform have different URL structures, but the course +*key* (`course-v1:<@org value/<@course value>/<@url_name value>/>`)) will be +present in each URL. .. code-block:: none - http://my-edx-server.org/courses/<@org value>/<@course value>/<@url_name value>/info + https://apps.training.openedx.io/learning/course/course-v1:<@org value>/<@course value>/<@url_name value>/home For example: .. code-block:: none - http://my-edx-server.org/courses/edX/DemoX/Demo_Course/info + https://apps.training.openedx.io/learning/course/course-v1:OpenedX+DemoX+Demo_Course/home ******************************* -Course Chapters +Course Sections ******************************* -You create a course chapter with the ``chapter`` element, as a child of the -root ``course`` element. Chapter elements are top-level pages in the course. -The Open edX platform renders navigation chrome around them (tab-set on top and -accordion on the left). It is possible to disable chrome for specific chapters -using the ``chrome`` option. It is possible to associate chapters with -different elements of the tabset with the ``default_tab`` option. It is -possible to hide them from the navigation using the ``hide_from_toc`` option. +You create a course section with the ``chapter`` element, as a child of the +``course`` element. Chapter elements are top-level sections of the course. +The Open edX platform renders navigation chrome around them (accordion on the left). -For example, the course outline is defined by elements in the following format. +For example, the course outline is defined by elements in the following format, +defined in the ``course/run.xml`` (`course/2025.xml +`_, +in our example). .. code-block:: xml - - - . . . - + + + + + . . . + ============================================== ``chapter`` Attributes @@ -109,132 +156,147 @@ For example, the course outline is defined by elements in the following format. * - Attribute - Meaning + * - ``url_name`` + - The url_name must be the name of the XML file (without the ``.xml`` extension) in the ``chapter/`` directory. * - ``display_name`` - - The value that is displayed to students as the name of the chapter, or - section. + - The value that is displayed to learners as the name of the section. * - ``start`` - - The date and time, in UTC, that the chapter is released to students. - Before this date and time, students do not see the chapter. + - The date and time, in UTC, that the section is released to learners. + Before this date and time, learners do not see the section. ========================= ``chapter`` Children ========================= The ``chapter`` element contains one or more children. Studio uses -``sequential`` elements for all children of chapters, and calls these -``subsections``. +*subsections*, defined by ``sequential`` elements, for all children of chapters. -The following example shows a chapter with two sequentials, or subsections. +The following example shows a chapter with two subsections, (``sequential`` items), +from `chapter/section_1_homework.xml `_. .. code-block:: xml - - - . . . - - . . . + + + ******************************* -Course Sequentials +Course Subsections ******************************* -You create a course sequential with the ``sequential`` element, for each +You create a course subsection with the ``sequential`` element, for each subsection in the chapter. -For example, the course can contain a sequential in this format. +For example, the course can contain a subsection in this format, from +`sequential/subsection_2_graded_as_homework.xml +`_. .. code-block:: xml - - - - . . . - - - . . . - + + + + + + + + ============================================== ``sequential`` Attributes ============================================== +.. note:: + + There may be more ``course`` attributes than described in this guide; no such complete guide of all + available attributes currentliy exists. Many attributes can be discovered by setting them in Studio + and then inspecting the exported ``sequential/.xml`` file. + + .. list-table:: :widths: 10 70 :header-rows: 1 * - Attribute - Meaning + * - ``url_name`` + - The url_name must be the name of the XML file (without the ``.xml`` extension) in the ``sequential/`` directory. * - ``display_name`` - - The value that is displayed to students as the name of the sequential, + - The value that is displayed to learners as the name of the sequential, or subsection. + * - ``due`` + - The date and time, in UTC, that the subsection is due. + After this date and time, learners cannot answer questions in this subsection. * - ``start`` - - The date and time, in UTC, that the sequential is released to students. - Before this date and time, students do not see the sequential. + - The date and time, in UTC, that the subsection is released to learners. + Before this date and time, learners do not see the subsection. * - ``graded`` - - Whether the sequential is a graded subsection; ``true`` or ``false``. + - Whether the subsection is a graded subsection; ``true`` or ``false``. * - ``format`` - - If the sequential is graded, the assignment type. + - If the subsection is graded, the assignment type. * - ``graceperiod`` - - If the sequential is graded, the number of seconds in the grace period. - * - ``rerandomize`` - - TBD + - If the subsection is graded, the number of seconds in the grace period. + * - ``hide_after_due`` + - Whether the subsection should be visible past the due date; ``true`` or ``false``. + * - ``show_correctness`` + - Defines when to show whether a learner's answer to the problem is correct; + ``"always"``, ``"never"``, or ``"past_due"`` * - ``showanswer`` - - TBD - * - ``xqa_key`` - - TBD + - Defines when to show the answer to the problem. ``"always"``, ``"answered"``, ``"attempted"``, ``"closed"``, + ``"finished"``, ``"correct_or_past_due"``, ``"past_due"``, ``"never"``, ``"after_attempts"``, ``"after_all_attempts"``, + ``"after_all_attempts_or_correct"``, ``"attempted_no_past_due"``, or ``"never_show_correctness_but_include_grade_description"`` + +.. admonition:: "never_show_correctness_but_include_grade_description" + + This option was added to the Ulmo release. In this option, learners do not see + question-level correctness or scores before or after the due date. However, + once the due date passes, they can see their overall score for the subsection + on the Progress page. ============================================== ``sequential`` Children ============================================== -The ``sequential`` element contains one or more child ``vertical`` elements. +The ``sequential`` element contains one or more units (child ``vertical`` elements). -The ``vertical`` element references a vertical, or unit, in the course. +The ``vertical`` element references a unit in the course. -The following example shows a chapter with a sequential that has three -verticals, or units. +For example, the subsection can contain units in this format, from +`vertical/unit_2_selection_problems.xml +`_. .. code-block:: xml - - - - - . . . . - - . . . . - - - . . . - + + + + + ******************************* -Course Verticals +Course Units ******************************* -In the course structure, a course vertical serves the following functions. +In the course structure, a course unit serves the following functions. -* Defines the display name for the vertical, or unit. -* Organizes components and other verticals in the vertical. +* Defines the display name for the unit. +* Organizes components. -You create a course vertical with the ``vertical`` element, for each -unit in the subsection. +You create a course unit with the ``vertical`` element, for each unit in the +subsection. For example, the course can contain a vertical in this format. .. code-block:: xml - - - - - . . . - - - . . . - + + ========================= ``vertical`` Attributes @@ -246,8 +308,10 @@ For example, the course can contain a vertical in this format. * - Attribute - Meaning + * - ``url_name`` + - The url_name must be the name of the XML file (without the ``.xml`` extension) in the ``vertical/`` directory. * - ``display_name`` - - The value that is displayed to students as the name of the sequential, + - The value that is displayed to learners as the name of the sequential, or subsection. ============================== @@ -255,27 +319,15 @@ For example, the course can contain a vertical in this format. ============================== The ``vertical`` element contains one or more child elements for each component -in the vertical, or unit. +in the unit. -.. note:: - You can embed the content of components in the ``course.xml`` file, as child - elements of the ``vertical`` element. However, you might want to store - components in separate files, to better enable content reuse across courses. +.. warning:: -A vertical element can also contain a vertical element. You can nest -verticals, or units, recursively. + A unit element can also contain a vertical element, potentially creating a recursive definition of verticals. + This is unsupported by Studio and not guaranteed to render properly - or at all - in the Open edX LMS or Libraries. Child elements of ``vertical`` refer to components in your course. The Open edX -Platform supports a wide range of components, including custom XBlocks. - -The following example shows a vertical with two components. - -.. code-block:: xml - - - - +platform supports a wide range of components, including custom XBlocks. .. seealso:: @@ -293,5 +345,5 @@ The following example shows a vertical with two components. +--------------+-------------------------------+----------------+--------------------------------+ | Review Date | Working Group Reviewer | Release |Test situation | +--------------+-------------------------------+----------------+--------------------------------+ -| | | | | +| 2025-11-06 | sarina | Ulmo | Pass | +--------------+-------------------------------+----------------+--------------------------------+ From 7c2d7751424d45ac2fc852a427431fa417254e0c Mon Sep 17 00:00:00 2001 From: sarina Date: Fri, 14 Nov 2025 23:42:39 -0500 Subject: [PATCH 12/22] Update the html, discussion, and video OLX component docs --- .../olx/components/discussion-components.rst | 26 +++- .../olx/components/html-components.rst | 83 +++++------- .../olx/components/video-components.rst | 127 +++++++++--------- 3 files changed, 121 insertions(+), 115 deletions(-) diff --git a/source/educators/olx/components/discussion-components.rst b/source/educators/olx/components/discussion-components.rst index 2641d6922..458841c71 100644 --- 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= + "{"enable_graded_units": true, + "enable_in_context": true, + "provider_type": "openedx", + "unit_level_visibility": true, + "posting_restrictions": "disabled", + "openedx": {"group_at_subsection": 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 index 109d1d0ad..c550cc74c 100644 --- 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 - - - ... - The above has an error. x should be y in the second equation. - +.. 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 - - - . . . + + + . . . -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`` 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 - - +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 -

Lesson 2: Let's Get INTERACTIVE!

-

- InteractiveNow 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. -  

-

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’ve created for past courses. -  They’re fun to play with.  Many courses will have tools - and labs that you need to use to complete homework assignments.

+

OLX (open learning XML) is the XML-based standard used to build courses for the Open edX Platform.

+

With OLX, you can:

+
    +
  • Move content between Open edX instances.
    • +
  • Create course content outside of Open edX Studio, including by conversion from other content formats.
    • +
  • Ensure content remains free of proprietary encoding and allow portability.
    • +
.. 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 index 97f183e4b..6260890ff 100644 --- 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/.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 + 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 - -