Skip to content
Snippets Groups Projects
Commit 976b7192 authored by brianhw's avatar brianhw
Browse files

Merge pull request #1845 from MITx/feature/brian/doc-html-text 

add documentation for HTML textbook
parents f51aea18 2d9deaf3
No related merge requests found
Hide whitespace changes
Inline Side-by-side
doc/public/course_data_formats/course_xml.rst
+ 63
− 1
View file @ 976b7192
......@@ -359,6 +359,8 @@ Supported fields at the course level
* `auto_cohort_groups`: `["group name 1", "group name 2", ...]` If `cohorted` and `auto_cohort` is true, automatically put each student into a random group from the `auto_cohort_groups` list, creating the group if needed.
* - `pdf_textbooks`
- have pdf-based textbooks on tabs in the courseware. See below for details on config.
* - `html_textbooks`
- have html-based textbooks on tabs in the courseware. See below for details on config.
Available metadata
......@@ -511,6 +513,7 @@ If you want to customize the courseware tabs displayed for your course, specify
"name": "Exciting news"
},
{"type": "textbooks"},
{"type": "html_textbooks"},
{"type": "pdf_textbooks"}
]
......@@ -518,6 +521,7 @@ If you want to customize the courseware tabs displayed for your course, specify
* The first two tabs must have types `"courseware"` and `"course_info"`, in that order, or the course will not load.
* The `courseware` tab never has a name attribute -- it's always rendered as "Courseware" for consistency between courses.
* The `textbooks` tab will actually generate one tab per textbook, using the textbook titles as names.
* The `html_textbooks` tab will actually generate one tab per html_textbook. The tab name is found in the html textbook definition.
* The `pdf_textbooks` tab will actually generate one tab per pdf_textbook. The tab name is found in the pdf textbook definition.
* For static tabs, the `url_slug` will be the url that points to the tab. It can not be one of the existing courseware url types (even if those aren't used in your course). The static content will come from `tabs/{course_url_name}/{url_slug}.html`, or `tabs/{url_slug}.html` if that doesn't exist.
* An Instructor tab will be automatically added at the end for course staff users.
......@@ -538,6 +542,8 @@ If you want to customize the courseware tabs displayed for your course, specify
- Parameters `name`, `link`.
* - `textbooks`
- No parameters--generates tab names from book titles.
* - `html_textbooks`
- No parameters--generates tab names from html book definition. (See discussion below for configuration.)
* - `pdf_textbooks`
- No parameters--generates tab names from pdf book definition. (See discussion below for configuration.)
* - `progress`
......@@ -550,7 +556,7 @@ If you want to customize the courseware tabs displayed for your course, specify
*********
Textbooks
*********
Support is currently provided for image-based and PDF-based textbooks. In addition to enabling the display of textbooks in tabs (see above), specific information about the location of textbook content must be configured.
Support is currently provided for image-based, HTML-based and PDF-based textbooks. In addition to enabling the display of textbooks in tabs (see above), specific information about the location of textbook content must be configured.
Image-based Textbooks
=====================
......@@ -623,6 +629,62 @@ The course content can then link to page 25 using the `customtag` element:
<customtag book="0" page="25" impl="book"/>
HTML-based Textbooks
====================
Configuration
-------------
HTML-based textbooks are configured at the course level in the policy file. The JSON markup consists of an array of maps, with each map corresponding to a separate textbook. There are two styles to presenting HTML-based material. The first way is as a single HTML on a tab, which requires only a tab title and a URL for configuration. A second way permits the display of multiple HTML files that should be displayed together on a single view. For this view, a side panel of links is available on the left, allowing selection of a particular HTML to view.
.. code-block:: json
"html_textbooks": [
{"tab_title": "Textbook 1",
"url": "https://www.example.com/thiscourse/book1/book1.html" },
{"tab_title": "Textbook 2",
"chapters": [
{ "title": "Chapter 1", "url": "https://www.example.com/thiscourse/book2/Chapter1.html" },
{ "title": "Chapter 2", "url": "https://www.example.com/thiscourse/book2/Chapter2.html" },
{ "title": "Chapter 3", "url": "https://www.example.com/thiscourse/book2/Chapter3.html" },
{ "title": "Chapter 4", "url": "https://www.example.com/thiscourse/book2/Chapter4.html" },
{ "title": "Chapter 5", "url": "https://www.example.com/thiscourse/book2/Chapter5.html" },
{ "title": "Chapter 6", "url": "https://www.example.com/thiscourse/book2/Chapter6.html" },
{ "title": "Chapter 7", "url": "https://www.example.com/thiscourse/book2/Chapter7.html" }
]
}
]
Some notes:
* It is not a good idea to include a top-level URL and chapter-level URLs in the same textbook configuration.
Linking from Content
--------------------
It is possible to add links to specific pages in a textbook by using a URL that encodes the index of the textbook, the chapter (if chapters are used), and the page number. For a book with no chapters, the URL is of the form `/course/htmlbook/${bookindex}`. For a book with chapters, use `/course/htmlbook/${bookindex}/chapter/${chapter}` for a specific chapter, or `/course/htmlbook/${bookindex}` will default to the first chapter.
For example, for the book with no chapters configured above, the textbook can be reached using the URL `/course/htmlbook/0`. Reaching the third chapter of the second book is accomplished with `/course/htmlbook/1/chapter/3`.
You can use a `customtag` to create a template for such links. For example, you can create a `htmlbook` template in the `customtag` directory, containing:
.. code-block:: xml
<img src="/static/images/icons/textbook_icon.png"/> More information given in <a href="/course/htmlbook/${book}">the text</a>.
And a `htmlchapter` template containing:
.. code-block:: xml
<img src="/static/images/icons/textbook_icon.png"/> More information given in <a href="/course/htmlbook/${book}/chapter/${chapter}">the text</a>.
The example pages can then be linked using the `customtag` element:
.. code-block:: xml
<customtag book="0" impl="htmlbook"/>
<customtag book="1" chapter="3" impl="htmlchapter"/>
PDF-based Textbooks
===================
......
lms/djangoapps/staticbook/views.py
+ 28
− 6
View file @ 976b7192
from lxml import etree
from django.contrib.auth.decorators import login_required
from django.http import Http404
from mitxmako.shortcuts import render_to_response
......@@ -38,6 +36,20 @@ def index_shifted(request, course_id, page):
@login_required
def pdf_index(request, course_id, book_index, chapter=None, page=None):
"""
Display a PDF textbook.
course_id: course for which to display text. The course should have
"pdf_textbooks" property defined.
book index: zero-based index of which PDF textbook to display.
chapter: (optional) one-based index into the chapter array of textbook PDFs to display.
Defaults to first chapter. Specifying this assumes that there are separate PDFs for
each chapter in a textbook.
page: (optional) one-based page number to display within the PDF. Defaults to first page.
"""
course = get_course_with_access(request.user, course_id, 'load')
staff_access = has_access(request.user, course, 'staff')
......@@ -63,7 +75,6 @@ def pdf_index(request, course_id, book_index, chapter=None, page=None):
for entry in textbook['chapters']:
entry['url'] = remap_static_url(entry['url'], course)
return render_to_response('static_pdfbook.html',
{'book_index': book_index,
'course': course,
......@@ -72,8 +83,21 @@ def pdf_index(request, course_id, book_index, chapter=None, page=None):
'page': page,
'staff_access': staff_access})
@login_required
def html_index(request, course_id, book_index, chapter=None, anchor_id=None):
def html_index(request, course_id, book_index, chapter=None):
"""
Display an HTML textbook.
course_id: course for which to display text. The course should have
"html_textbooks" property defined.
book index: zero-based index of which HTML textbook to display.
chapter: (optional) one-based index into the chapter array of textbook HTML files to display.
Defaults to first chapter. Specifying this assumes that there are separate HTML files for
each chapter in a textbook.
"""
course = get_course_with_access(request.user, course_id, 'load')
staff_access = has_access(request.user, course, 'staff')
......@@ -99,11 +123,9 @@ def html_index(request, course_id, book_index, chapter=None, anchor_id=None):
for entry in textbook['chapters']:
entry['url'] = remap_static_url(entry['url'], course)
return render_to_response('static_htmlbook.html',
{'book_index': book_index,
'course': course,
'textbook': textbook,
'chapter': chapter,
'anchor_id': anchor_id,
'staff_access': staff_access})
lms/templates/static_htmlbook.html
+ 8
− 21
View file @ 976b7192
......@@ -26,32 +26,22 @@
// chapters, and it should be in-bounds.
chapterToLoad = options.chapterNum;
}
var anchorToLoad = null;
if (options.chapters) {
anchorToLoad = options.anchor_id;
}
loadUrl = function htmlViewLoadUrl(url, anchorId) {
loadUrl = function htmlViewLoadUrl(url) {
// clear out previous load, if any:
parentElement = document.getElementById('bookpage');
while (parentElement.hasChildNodes())
parentElement.removeChild(parentElement.lastChild);
// load new URL in:
$('#bookpage').load(url);
};
// if there is an anchor set, then go to that location:
if (anchorId != null) {
// TODO: add implementation....
}
};
loadChapterUrl = function htmlViewLoadChapterUrl(chapterNum, anchorId) {
loadChapterUrl = function htmlViewLoadChapterUrl(chapterNum) {
if (chapterNum < 1 || chapterNum > chapterUrls.length) {
return;
}
var chapterUrl = chapterUrls[chapterNum-1];
loadUrl(chapterUrl, anchorId);
loadUrl(chapterUrl);
};
// define navigation links for chapters:
......@@ -64,15 +54,15 @@
};
for (var index = 1; index <= chapterUrls.length; index += 1) {
$("#htmlchapter-" + index).click(loadChapterUrlHelper(index));
}
}
}
// finally, load the appropriate url/page
if (urlToLoad != null) {
loadUrl(urlToLoad, anchorToLoad);
loadUrl(urlToLoad);
} else {
loadChapterUrl(chapterToLoad, anchorToLoad);
}
loadChapterUrl(chapterToLoad);
}
}
})(jQuery);
......@@ -92,9 +82,6 @@
%if chapter is not None:
options.chapterNum = ${chapter};
%endif
%if anchor_id is not None:
options.anchor_id = ${anchor_id};
%endif
$('#outerContainer').myHTMLViewer(options);
});
......
lms/urls.py
+ 0
− 4
View file @ 976b7192
......@@ -267,10 +267,6 @@ if settings.COURSEWARE_ENABLED:
'staticbook.views.html_index', name="html_book"),
url(r'^courses/(?P<course_id>[^/]+/[^/]+/[^/]+)/htmlbook/(?P<book_index>[^/]*)/chapter/(?P<chapter>[^/]*)/$',
'staticbook.views.html_index'),
url(r'^courses/(?P<course_id>[^/]+/[^/]+/[^/]+)/htmlbook/(?P<book_index>[^/]*)/chapter/(?P<chapter>[^/]*)/(?P<anchor_id>[^/]*)/$',
'staticbook.views.html_index'),
url(r'^courses/(?P<course_id>[^/]+/[^/]+/[^/]+)/htmlbook/(?P<book_index>[^/]*)/(?P<anchor_id>[^/]*)/$',
'staticbook.views.html_index'),
url(r'^courses/(?P<course_id>[^/]+/[^/]+/[^/]+)/courseware/?$',
'courseware.views.index', name="courseware"),
......
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