Skip to content

E
edx-platform
Commit 8b98c08d by Mark Hoeber
Options

Merge pull request #5525 from edx/pmitros/olx-doc-fixups 

First pass at improving OLX docs
parents fba0b7b8 ed0cf738
Showing with 227 additions and 173 deletions
docs/en_us/olx/source/advanced-components/index.rst deleted 100644 → 0
.. _Advanced Components:
#################################
Advanced Components
#################################
Use the chapters in this section to create advanced course components.
.. toctree::
:maxdepth: 2
annotation
lti_component
open_response_assessment
word_cloud
\ No newline at end of file
docs/en_us/olx/source/change_log.rst
......@@ -13,6 +13,19 @@ October, 2014
* - Date
- Change
* - 10/17/14
- Provided more explanation to the introduction to :ref:`Problems and
Tools`.
* -
- Reorganized the :ref:`Problems and Tools` and :ref:`Course Components`
sections to properly categorize these types of objects.
* -
- Updated the :ref:`ODL Directory Structure` chapter to accurately reflect
how an OLX course is organized.
* -
- Updated the :ref:`HTML Components`, :ref:`Discussion Components`, and
:ref:`Video Components` chapters to explain the option to embed content
in container objects.
* - 10/07/14
- Added pages for the :ref:`Graphical Slider Tool` and
:ref:`Symbolic Response` to the :ref:`Problems and Tools` section.
......
docs/en_us/olx/source/components/discussion-components.rst
.. _Discussion Components:
#################################
Discussion Components
#################################
You can add inline discussion components to a vertical, or unit, in your
You can add inline discussion components to any container in your
course.
See:
......@@ -22,13 +24,28 @@ discussion component in your course.
The name of the XML file must match the value of the @url_name attribute of the
``discussion`` element in the vertical XML file.
For example, if the vertical XML file contains:
In-line, you can create, if the vertical XML file contains:
.. code-block:: xml
<vertical display_name="Lesson_1_Unit_1">
<discussion url_name="Introduce_Yourself"/>
. . .
<discussion
discussion_category="Essays"
discussion_id="peer_grading_component"
discussion_target="Peer Grading"
display_name="Peer Grading"
url_name="peer_grading_discussion"
/>
</vertical>
If you prefer to create the discussion in its own file, you can create:
.. code-block:: xml
<vertical display_name="Lesson_1_Unit_1">
<discussion
url_name="Introduce_Yourself"
/>
</vertical>
You create the file ``discussion/Introduce_Yourself.xml`` to define the inline
......
docs/en_us/olx/source/components/html-components.rst
......@@ -4,27 +4,50 @@
HTML Components
#################################
To add an HTML component to your course, you create both XML and HTML files.
See:
* `Create the XML File for an HTML Component`_
* `Create the HTML Component`_
* `Example of an HTML Component Embedded in a Vertical`_
* `Example of Separate HTML Files`_
* `HTML Component XML File Elements`_
* `html Element Attributes`_
* `Example HTML Component XML File`_
* `Create the HTML File for an HTML Component`_
* `Example HTML Component Content`_
*********************************************
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.
.. 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
Both files, for each component, must be in the ``html`` directory.
<vertical display_name="Lesson_1_Unit_1">
...
<html>The above has an error. <b>x</b> should be <b>y</b> in the second equation.</html>
</vertical>
*********************************************
Create the XML File for an HTML Component
Example of Separate HTML Files
*********************************************
You create an XML file in the ``html`` directory for each HTML component in your course.
You create an XML file in the ``html`` directory for each HTML component in
your course.
The name of the XML file must match the value of the @url_name attribute of the ``html`` element in the vertical XML file.
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, if the vertical XML file contains:
......@@ -43,7 +66,7 @@ HTML Component XML File Elements
The root element of the XML file for the HTML component is file is ``html``.
The ``html`` element contains not children.
In this case, the ``html`` element contains no children.
*************************************
``html`` Element Attributes
......@@ -73,22 +96,6 @@ The following example shows an XML file for an HTML component:
<html filename="Introduction" display_name="Unit Introduction"/>
*********************************************
Create the HTML File for an HTML Component
*********************************************
You create an HTML file in the ``html`` directory for each HTML component in your course.
The name of the HTML file must match the value of the @file_name attribute of the ``html`` element in the component's XML file.
For example, if the component's XML file contains:
.. code-block:: xml
<html filename="Introduction" display_name="Unit Introduction"/>
You create the file ``html/Introduction.html`` to define the HTML component content.
*************************************
Example HTML Component Content
*************************************
......@@ -113,5 +120,3 @@ file for the edX Demo course:
&nbsp;They&rsquo;re fun to play with. &nbsp;Many courses will have tools
and labs that you need to use to complete homework assignments.</p>
docs/en_us/olx/source/components/index.rst
.. _Course Components:
#################################
Course Components
Course Components (XBlocks)
#################################
Use the chapters in this section to create course components.
Use the chapters in this section to create course components.
.. toctree::
:maxdepth: 2
......@@ -12,3 +12,15 @@ Use the chapters in this section to create course components.
html-components
discussion-components
video-components
annotation
conditional_module
full_screen_image
google_hangout
graphical_slider_tool
iframe
lti_component
open_response_assessment
periodic_table
poll
word_cloud
zooming_image
docs/en_us/olx/source/components/video-components.rst
......@@ -4,7 +4,9 @@
Video Components
#################################
You can add video components to a vertical, or unit, in your course.
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).
See:
......@@ -17,8 +19,20 @@ See:
Create the XML File for a Video Component
**********************************************
You create an XML file in the ``video`` directory for each video component in
your course.
To add a video component to your course, add it to the course XML tree as:
.. code-block:: xml
<video
youtube="1.00:o2pLltkrhGM"
url_name="Introduction_Lecture"
display_name="Introduction Lecture"
youtube_id_1_0="o2pLltkrhGM"
</video>
If you would prefer to break this out into its own file, you create 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.
......
docs/en_us/olx/source/directory-structure.rst
.. _ODL Directory Structure with edX Studio:
.. _ODL Directory Structure:
###############################################
OLX Directory Structure
OLX Course Structure
###############################################
See:
* `OLX and Directory File Structures`_
* `Top-level Directory`_
* `about Directory`_
* `html Directory`_
* `info Directory`_
* `policies Directory`_
* `problem Directory`_
* `static Directory`_
* `tabs Directory`_
* `video Directory`_
* `XBlock directories`_
* `edX Platform Directories`_
****************************************
OLX and Directory File Structures
......@@ -26,26 +18,27 @@ OLX and Directory File Structures
All files and sub-directories that comprise your OLX course are stored within
a single directory.
OLX provides for flexibility in the directory and file structure you use to
build your course.
OLX provides for some flexibility in the directory and file structure
you use to build your course.
************************
Top-level Directory
************************
In most cases, it is easiest to create your courseware structure in a
Starting out, it is easiest to create your courseware structure in a
single file, the ``course.xml file``.
The ``course.xml`` file would contain the
definition of all chapters (sections), sequentials (subsections), and verticals
(units) in your courseware. The courseware structure would then refer to files
for components, which are stored in a directory for each type of XBlock.
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.
For example, the edX Platform contains a directory called `manual-testing-complete`_ that contains a course with all component types for testing
purposes.
Currently, when Studio exports a course, it places each component in its own
file.
Course content, other than the courseware, is stored in separate directories
and files as shown in the rest of this chapter.
For example, the edX Platform contains a directory called
`manual-testing-complete`_ that contains a course with all component
types for testing purposes.
Following are descriptions of directories needed for a typical course. You
should set up these directories in preparation for developing your course
......@@ -55,9 +48,38 @@ content.
If you are using custom XBlocks, you can have
additional directories that store the XML for XBlocks of that type.
********************
*******************
XBlock directories
*******************
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
their top-level components, you do not need to create an ``html``
directory.
For information about several examples of these directories, see:
See :ref:`HTML Components` for more information.
See :ref:`Problems and Tools` for more information.
See :ref:`Video Components` for more information.
As the set of XBlocks grows, so does the set of associated XML tags
and directories.
*************************
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
files that specify course policies and non-courseare content.
====================
``about`` Directory
********************
====================
The ``about`` directory contains:
......@@ -70,21 +92,9 @@ The ``about`` directory contains:
See :ref:`The Course About Pages` for more information.
********************
``html`` Directory
********************
The ``html`` directory contains an HTML file for each HTML component in
the course.
If you do not need HTML components in the course, you do not need to create
this directory.
See :ref:`HTML Components` for more information.
********************
====================
``info`` Directory
********************
====================
The ``info`` directory contains:
......@@ -94,9 +104,9 @@ The ``info`` directory contains:
* ``updates.html``, which contains the course updates students see when opening
a course.
***********************
=======================
``policies`` Directory
***********************
=======================
The ``policies`` directory contains:
......@@ -109,46 +119,22 @@ The ``policies`` directory contains:
See :ref:`Course Policies` for more information.
**********************
``problem`` Directory
**********************
The ``problem`` directory contains an XML file for each problem component you
use in your course.
If you do not need problem components in the course, you do not need to create
this directory.
See :ref:`Problems and Tools` for more information.
********************
====================
``static`` Directory
********************
====================
The ``static`` directory contains the files used in your course, such as images
or PDFs.
See :ref:`Course Assets` for more information.
********************
====================
``tabs`` Directory
********************
====================
The ``tabs`` directory contains an HTML file for each page you add to your
course.
See :ref:`Course Pages` for more information.
********************
``video`` Directory
********************
The ``video`` directory contains an XML file for each video component you use
in your course.
If you do not need video components in the course, you do not need to create
this directory.
See :ref:`Video Components` for more information.
See :ref:`Course Tabs` for more information.
.. include:: links.rst
\ No newline at end of file
.. include:: links.rst
docs/en_us/olx/source/index.rst
......@@ -26,9 +26,9 @@ This document is intended for those developing edX courses through Open Learning
organizing-course/index
components/index
problem-xml/index
advanced-components/index
tools/index
drafts/index
demo-course/index
\ No newline at end of file
docs/en_us/olx/source/links.rst
......@@ -3,4 +3,6 @@
.. _Wikipedia XML entry: http://en.wikipedia.org/wiki/XML
.. _manual-testing-complete: https://github.com/edx/edx-platform/tree/master/common/test/data/manual-testing-complete
\ No newline at end of file
.. _manual-testing-complete: https://github.com/edx/edx-platform/tree/master/common/test/data/manual-testing-complete
.. _LONCAPA XML format: https://s1.lite.msu.edu/adm/help/Authoring_XML_Intro.hlp#Authoring_XML_Intro
\ No newline at end of file
docs/en_us/olx/source/organizing-course/course-structure-overview.rst
......@@ -13,22 +13,23 @@ building blocks of an edX course. See:
Courseware
**************
Courseware is the main content of your course, namely lessons and assessments.
The following list describes how courseware is organized in OLX:
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 sections are at the top level of your course and typically represent a
time period. In OLX, sections are represented by ``chapter`` elements.
* Course chapters are at the top level of your course and typically
represent a time period. In Studio, chapters are called *sections*.
* A section contains one or more subsections. Course subsections are parts of a
section, and usually represent a topic or other organizing principle. In
OLX, subsections are represented by ``sequential`` elements.
* A section 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 subsection contains one or more units. In OLX, units are represented by
``vertical`` elements.
* Course units are lessons in a subsection that students view as single pages.
A unit contains one or more components. Course components are objects within
units that contain your actual course content. For more information, see:
* Courses are composed of structural elements, such as ``sequential``
and ``vertical``, and leaf-nodes or content elements, 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).
* :ref:`Course Components`
* :ref:`Problems and Tools`
......@@ -61,4 +62,4 @@ Course Policies
Course policies determine how your course functions. For example, policies
control grading and content experiments. For more information, see
:ref:`Policies`.
\ No newline at end of file
:ref:`Policies`.
docs/en_us/olx/source/organizing-course/course-xml-file.rst
......@@ -20,8 +20,6 @@ The ``course.xml`` File
The root element of the ``course.xml`` file is ``course``.
The ``course`` element does not contain any child elements.
For example, the ``course.xml`` file may contain:
.. code-block:: xml
......@@ -82,7 +80,13 @@ For example:
Course Chapters
*******************************
You create a course chapter with the ``chapter`` element, as a child of the root ``course`` element.
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 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.
For example, if the course outline file contains:
......@@ -114,10 +118,7 @@ For example, if the course outline file contains:
``chapter`` Children
=========================
The ``chapter`` element contains one or more child ``sequential`` elements.
The ``sequential`` element references a sequential, or subsection, in the
course.
The ``chapter`` element contains one or more children. Studio uses ``sequential`` elements for all children of chapters, and calls these ``subsections``.
The following example shows a chapter with two sequentials, or subsections. :
......
docs/en_us/olx/source/pages/pages.rst
.. _Course Pages:
.. _Course Tabs:
#################################
Course Pages
Course Tabs
#################################
You can add pages to your course. Each page appears in your course’s navigation
bar.
You can add tabs, or pages, to your course. Each tab appears in your course’s
navigation bar.
*********************************************
Create the Page File
Create the Tab File
*********************************************
You create an HTML file for each page you want to add to the course in the
You create an HTML file for each tab you want to add to the course in the
``tabs`` directory.
You can add any text and HTML markup to the page.
\ No newline at end of file
You can add any text and HTML markup to the page. Tabs can also be
links, and other types of content. One common design pattern is to
link a tab to a chromeless XBlock in the courseware, which allows for
top-level interactive course content.
docs/en_us/olx/source/problem-xml/index.rst
.. _Problems and Tools:
#################################
Problems and Tools
Problems
#################################
Use the chapters in this section to create course problems and tools.
The format for edX problems is based on the `LONCAPA XML format`_,
although the two are not quite compatible. In the edX variant, problems are
composed of four types of tags:
* **inputtypes** are similar to XBlocks. They define ways for users to enter
input into the problem.
* **responsetypes** are graders. They define how inputs are mapped to grades.
* **hinters** are used to provide feedback to problems.
* Standard HTML tags are used for formatting.
OLX is designed to allow mixing-and-matching of inputtypes,
responsetypes, and hinters. For example, a numerical grader could match
7+-0.1%. It would be okay to use this with any inputtype which output a number,
whether this was a text box, equation input, slider, or multiple choice
question. In practice, this doesn't always work. For example, in the former
case, a multiple choice question would not give an output in a format a
numerical grader could handle.
In addition, in many cases, there is a 1:1 mapping between graders and inputs.
For some types of inputs (especially discipline-specific specialized ones), it
simply does not make sense to have more than one grader.
The most general grader is ``customresponse``. This uses Python code
to evaluate the input. By design, this ought to work with any inputtype,
although there are bugs mixing this with a small number of the newer
inputtypes.
Like LON-CAPA, OLX allows embedding of code to generate parameterized problems.
Unlike LON-CAPA, edX supports Python (and not Perl). Otherwise, the syntax is
approximately identical.
.. toctree::
:maxdepth: 2
......@@ -12,16 +41,11 @@ Use the chapters in this section to create course problems and tools.
checkbox
chemical_equation
circuit_schematic_builder
conditional_module
custom_javascript
custom_python
drag_and_drop
dropdown
full_screen_image
gene_explorer
google_hangout
graphical_slider_tool
iframe
image_mapped_input
math_expression_input
mathjax
......@@ -29,12 +53,11 @@ Use the chapters in this section to create course problems and tools.
mult_choice_num_input
multiple_choice
numerical_input
periodic_table
poll
problem_in_latex
problem_with_hint
protein_builder
symbolic_response
text_input
vitalsource
zooming_image
\ No newline at end of file
.. include:: ../links.rst
docs/en_us/olx/source/problem-xml/vitalsource.rst deleted 100644 → 0
.. include:: ../../../shared/exercises_tools/vitalsource.rst
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment