Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

Paged course formats: Difference between revisions

From MoodleDocs
m (Update mockup display)
 
(16 intermediate revisions by 3 users not shown)
Line 2: Line 2:
|name = Paged course formats
|name = Paged course formats
|state = FINAL DISCUSSION OF SPECIFICATION
|state = FINAL DISCUSSION OF SPECIFICATION
|tracker = TBA
|tracker = MDL-32476
|discussion = http://moodle.org/mod/forum/discuss.php?d=200470
|discussion = http://moodle.org/mod/forum/discuss.php?d=200470
|assignee = moodle.com
|assignee = moodle.com
Line 14: Line 14:
==Implement paged sections ==
==Implement paged sections ==


The goal here is to avoid "scroll of death" for large courses by allowing teachers to easily show each section on its own sub-page.  This kind of choice is common to many course formats, and is governed by the amount of content, so it makes sense to make it a course setting rather than a new format.
The goal here is to avoid "scroll of death" for large courses by allowing teachers to easily show each section on its own sub-page.  This kind of choice is common to many course formats, and is governed by the amount of content, so it makes sense to make this a *course setting* rather than a new format.  Of course, for many other design decisions it's better just to add new formats.


===New course setting===
===New course setting===
Line 44: Line 44:
More sections can be added by a big "plus" icon at the bottom, and old ones can be deleted if they are empty.
More sections can be added by a big "plus" icon at the bottom, and old ones can be deleted if they are empty.


[[File:paged_course_formats_maincoursepage_mockup.png]]


QUESTION: Should the "current" week/topic be expanded here?  It's not really consistent with the design but it would save people some clicks.
(Mockup files are on MDL-32476)


Example mockup of the main page: [[File:paged_course_formats_maincoursepage_mockup.png|400px|thumb|left]]
(QUESTION: Should the "current" week/topic be expanded here?  It's not really consistent with the design but it would save people some clicks.)


====Section pages====
====Section pages====
Line 55: Line 56:
The navigation bar should show the section name as a sub page and be selected.  It's easy to "go back" one level to the main course page.
The navigation bar should show the section name as a sub page and be selected.  It's easy to "go back" one level to the main course page.


There should also be nav buttons in the top and bottom of the page:
There should also be nav buttons to prev/next sections in the top and bottom of the page.
 
< [Previous_section_name] _______  ^ [Course_name]  _______  [Next_section_name] >


Otherwise the section is displayed normally, very similar to the way a one-section course displays now (except without section 0).
Otherwise the section is displayed normally, very similar to the way a one-section course displays now (except without section 0).


It will be difficult to move an activity to another section so we need an interface for that.  One idea is to have a list of section names appear when dragging an item, and you can drop right onto the section name.  Without JS I think the existing code would all work fine without changes.
It will be difficult to move an activity to another section so we need an interface for that.  One idea is to have a list of section names appear when dragging an item, and you can drop right onto the section name.  Without JS I think the existing code would all work fine without changes.
[[File:paged_course_formats_sectionpage_mockup.png]]
(Mockup files are on MDL-32476)


===Other related changes to the code===
===Other related changes to the code===
Line 89: Line 93:
===Action icons===
===Action icons===


# Clean up the way they look.  Sizes/order/position and alt tags all need to be consistent.  New, larger icons.
# Clean up the way they look.  Sizes/order/position and alt tags all need to be consistent.  New, larger icons. http://vimeo.com/38561642


# With JS on, '''only''' show the icons when hovering over associated activity.
# With JS and editing on, '''only''' show the icons when hovering over associated activity. http://moodle.org/mod/forum/discuss.php?d=197470


==Using renderers==


 
Note: This is specification. Renderers were implemented in 2.3 and the actual implementation may be slightly different.
==Course format refactoring==
 
We will refactor the course formats to support a proper object-oriented design and full support for renderers.
 
===New classes===
 
Course formats must be classes inheriting base class format_base instead of the current collection of callbacks. (Although some callbacks will be converted to static methods)
 
* Method course_get_format($course) will return an instance of the this class for the particular course. Since $course is a DB entry we can’t declare methods within it.
* Method format_base::is_setup_completed() returns boolean. If setup is not yet completed, course/view.php will redirect to course/edit.php
* Method format_base::default_blocks() is to replace config.php with $format[‘defaultblocks’]
* Method format_base::form_fields() defines fields to be used in edit course form
* Method format_base::form_validation() performs additional validation for edit course form
 
Base (default) implementation of functions in format_base check for existing callback functions (Moodle 2.0 - 2.2 style) and calls them (also includes format.php and/or config.php). In this case developer-level warnings are produced. But this way Moodle 2.0-2.2 course format plugins will still work in this new system.
 
===Renderers===


Course API defines two renderers:
Course API defines two renderers:
Line 129: Line 117:
*.init() should be called correctly with correctly passed strings
*.init() should be called correctly with correctly passed strings
class jsportal (AJAX) should be substituted with up-to-date coding style
class jsportal (AJAX) should be substituted with up-to-date coding style
==Extend course settings with format support ==
Add a new form section after ‘General’ in the course settings page, named ‘Display options for Weekly Format’ (or whatever format is chosen).
If case of Javascript enabled this form section is reloaded when course format is changed.  Otherwise the user will have to press a refresh button to refresh the display options for the current format.
Each course format defines which display options it needs. For the standard course formats they are:
    weeks: numsections, startdate, hiddensections, coursedisplay
    topics: numsections, hiddensections, coursedisplay
    scorm:
    social:
    default: numsections, startdate, hiddensections (current behaviour)
Each course format may override label and/or help text for the elements and specify the types and rules for the elements.
Also there is a hook allowing course format to validate the fields it's added to this form (see stage 3 above)


==See also==
==See also==


* [[Talk:Paged course formats]]
* [[Talk:Paged course formats]]
* [[Course_formats_2]]

Latest revision as of 05:55, 30 August 2012

Paged course formats
Project state FINAL DISCUSSION OF SPECIFICATION
Tracker issue MDL-32476
Discussion http://moodle.org/mod/forum/discuss.php?d=200470
Assignee moodle.com


Moodle 2.3


The following features are arranged in stages. What we can't finish for 2.3 can be done for 2.4.


Implement paged sections

The goal here is to avoid "scroll of death" for large courses by allowing teachers to easily show each section on its own sub-page. This kind of choice is common to many course formats, and is governed by the amount of content, so it makes sense to make this a *course setting* rather than a new format. Of course, for many other design decisions it's better just to add new formats.

New course setting

  1. Add a new field to the database called mdl_course.coursedisplay to store the teacher's preference.
  2. Add a new setting named "Course display format" to the course setting page for this field with two settings:
    • Show all sections on one page - exactly as things are currently, and will be the default setting
    • Show one section per page - will abbreviate the course page to a list of links to individual sections

Note that it's up to the course format to interpret this setting. Course formats can use the setting or completely ignore it if they want.

Further options could be added later, perhaps a "collapsible display" like the old Accordion format that lets you flip between sections. However we don't want to add to many new things to this list, as that is why we have different course formats in the first place.


Update core formats: Weekly and Topics

We'll be making sure core formats use the new setting properly straight away, of course.

Main course page

The main course main page will show the General section (section 0) with a nicely-formatted list of sections below it with the current one highlighted. For each topic/week there is:

  • the section name (as a link to the separate page, i.e. course/view.php?id=12&topic=3 or course/view.php?id=2&week=3)
  • the section summary (truncated if it’s too long)
  • a completion summary (if applicable, 1/3, 30%, ?)
  • controls to hide/show that section, as usual
  • Ajax (or arrows for non-JS) to change the order by dragging

The "zoom" boxes that control ‘Show one/all weeks/topics’ are no longer needed and will be removed.

More sections can be added by a big "plus" icon at the bottom, and old ones can be deleted if they are empty.

paged course formats maincoursepage mockup.png

(Mockup files are on MDL-32476)

(QUESTION: Should the "current" week/topic be expanded here? It's not really consistent with the design but it would save people some clicks.)

Section pages

The section pages should be seen as "sub" pages of the course page and can have their own blocks. (If this is too difficult initially then we can just re-use the course blocks on all section pages).

The navigation bar should show the section name as a sub page and be selected. It's easy to "go back" one level to the main course page.

There should also be nav buttons to prev/next sections in the top and bottom of the page.

Otherwise the section is displayed normally, very similar to the way a one-section course displays now (except without section 0).

It will be difficult to move an activity to another section so we need an interface for that. One idea is to have a list of section names appear when dragging an item, and you can drop right onto the section name. Without JS I think the existing code would all work fine without changes.


paged course formats sectionpage mockup.png

(Mockup files are on MDL-32476)

Other related changes to the code

Get rid of user setting for course display

There is no longer need in per-user setting to show only one section in the course (it confused people anyway).

  1. Remove the control
  2. delete function course_get_display, course_set_display and their usage,
  3. DROP TABLE mdl_course_display

Check for regressions in modules caused by course assumptions

For example, make sure that "return to course" actually returns to the appropriate section. Forum module does something like that when you add a new post from the Latest News block. Also editing module settings has a "Save and return to course" button. etc.

UI improvements for course editing mode

The goal is to make interface more user-friendly and get rid of ‘Editing mode’ when Javascript is enabled.

Adding activities and resources

The drop downs for adding activities and resources can be united and shown as a nice window (in the left part of it). When user hovers over the activity/resource name, they help for this action appears in the right part of the window. If JS is disabled there could be a current behaviour but a return to a better help icon containing help for all activities/resources listed. See MDL-30617

Add a user preference controlled by link/button in UI to switch between old-style menu (for expert users) and this new-style pop up (as default, for new users).

Add support for drag and drop straight into any section. See Course drag and drop upload and MDL-22504.

Action icons

  1. Clean up the way they look. Sizes/order/position and alt tags all need to be consistent. New, larger icons. http://vimeo.com/38561642
  1. With JS and editing on, only show the icons when hovering over associated activity. http://moodle.org/mod/forum/discuss.php?d=197470

Using renderers

Note: This is specification. Renderers were implemented in 2.3 and the actual implementation may be slightly different.

Course API defines two renderers:

course_renderer controls output used in course/view.php: hidden form for AJAX, functions including javascript libraries, etc.

class format_renderer_base is the base class for course format renderers. It overrides or uses the functions from course_renderer the same way as plugin_renderer_base deals with the functions from core_renderer (so each class can be overwritten independently in theme). Also it is to make sure that if method render_format_FORMATNAME() is missing, the format.php file is included (for backward compatibility)

Each course format shall define its own renderer inheriting this one. But if the renderer is not defined in plugin, the course API will use an instance of format_renderer_base

course/view.php invokes a renderer for the current course format (or if course format does not define renderer)

See also http://tracker.moodle.org/browse/MDL-10265 Javascript and AJAX YUI3 is to be used instead of YUI2.

  • .init() should be called correctly with correctly passed strings

class jsportal (AJAX) should be substituted with up-to-date coding style

See also