Difference between revisions of "Course formats 2"

Jump to: navigation, search
m (Class course (for discussion))
m (Class course (for discussion))
Line 15: Line 15:
 
* add table course_format_options that will store format-specific options for the whole course and for specific secions (fields: id, courseid, format, sectionid[optional], name, value)
 
* add table course_format_options that will store format-specific options for the whole course and for specific secions (fields: id, courseid, format, sectionid[optional], name, value)
 
* deprecate existing fields in table course: numsections, hiddensections, coursedisplay.
 
* deprecate existing fields in table course: numsections, hiddensections, coursedisplay.
 
==Class course (for discussion)==
 
There are number of course-related functions in the core with random names. The argument name/property 'section' is used for both {section}.id and {section}.section, sometimes even the same variable changes it's meaning. Some very important functions completely miss phpdocs.
 
 
Besides it will be more understandable for developers of modules and other plugins to relate to course object and not to course format (for example to get section name, etc.)
 
 
The proposal is:
 
* move code of all those functions into new class 'course'
 
* leave the functions themselves in course/deprecatedlib.php with developer warning and call to corresponding function from course class
 
* update usage of those functions in the core
 
* add function get_course() or course_get_course() to retrieve the cached instance of the course, make sure cache is emptied inside rebuid_course_cache()
 
* try to replace multiple similar queries $DB->get_record('course', array('id'=>$courseid)) in the core code
 
 
Source of course/lib.php: https://github.com/moodle/moodle/blob/master/course/lib.php
 
 
{| class="nicetable"
 
|-
 
! Existing function
 
! New function
 
|-
 
| get_fast_modinfo()
 
| ? course::get_modinfo()
 
|-
 
| get_all_mods()
 
| - deprecate, suggest using get_fast_modinfo() and get_module_types()
 
|-
 
| -
 
| get_module_types_names() ? information about used module types, to replace $modnames and $modnamesplural in get_all_mods()
 
|-
 
| -
 
| course::get_used_module_types(), to replace $modnamesused in get_all_mods()
 
|-
 
| get_array_of_activities()
 
| course::get_array_of_activities() [used only by get_fast_modinfo()]
 
|-
 
| get_all_sections()
 
| - already needs to be deprecated, use get_fast_modinfo()->get_section_info_all()
 
|-
 
| course_set_marker()
 
| course::set_marker()
 
|-
 
| set_section_visible
 
| course::set_section_visible()
 
|-
 
| add_course_module()
 
| course::add_cm_raw() This function only creates an entry in table {course_module}
 
|-
 
| add_mod_to_section()
 
| course::cm_add_to_section() + also update {course_module}
 
|-
 
| -
 
| course::add_cm() calls previous two functions and rebuild_course_cache()
 
|-
 
| get_course_section()
 
| course::get_or_create_section() will return section_info
 
|-
 
| -
 
| course::get_section() will return section_info, alias to get_fast_modinfo()->get_section_info()
 
|-
 
| -
 
| course::get_sections() alias to get_fast_modinfo()->get_section_info_all()
 
|-
 
| set_coursemodule_groupmode()
 
| course::set_cm_groupmode()
 
|-
 
| set_coursemodule_idnumber()
 
| course::set_cm_idnumber()
 
|-
 
| set_coursemodule_visible()
 
| course::set_cm_visible()
 
|-
 
| delete_course_module()
 
| course::delete_cm_raw()
 
|-
 
| delete_mod_from_section()
 
| course::delete_cm_from_section()
 
|-
 
| -
 
| course::delete_cm() will call both previous functions
 
|-
 
| move_section()
 
| - remove completely
 
|-
 
| move_section_to()
 
| course::move_section(), also call rebuild_course_cache()
 
|-
 
| reorder_sections()
 
| course::reorder_sections(), also call rebuild_course_cache()
 
|-
 
| moveto_module()
 
| course::move_cm()
 
|-
 
| course_format_name()
 
| course::get_formatted_name()
 
|-
 
| get_section_name()
 
| format_base::get_section_name() with aliases: course::get_section_name() and section_info::get_name()
 
|-
 
| get_generic_section_name()
 
| format_base::get_generic_section_name() [protected]
 
|-
 
| can_delete_course()
 
| course::can_delete()
 
|-
 
| create_course()
 
| course::create() [static]
 
|-
 
| update_course()
 
| course::update()
 
|-
 
| course_ajax_enabled()
 
| course::is_ajax_enabled()
 
|-
 
| include_course_ajax()
 
| course::include_ajax()
 
|-
 
| course_get_url()
 
| course::get_view_url()
 
|}
 
 
Other course-related functions in course/lib.php
 
 
* get_print_section_cm_text()
 
* print_section()
 
* print_section_add_menus()
 
* get_module_metadata()
 
* print_course
 
* make_editing_buttons()
 
* course_allowed_module()
 
  
 
==Object model==
 
==Object model==

Revision as of 08:14, 24 September 2012

Course formats refactoring
Project state FINAL DISCUSSION OF SPECIFICATION
Tracker issue MDL-35218
Discussion {{{discussion}}}
Assignee Marina Glancy


Moodle 2.4


We will refactor the course formats to support a proper object-oriented design and flexibility

Database changes

  • change course.format from varchar(10) to varchar(32)
  • add field course_sections.parent (default 0) to allow sections hierarchy
  • add field course_sections.visibleold to store original visibility when one of the parent sections is hidden
  • add table course_format_options that will store format-specific options for the whole course and for specific secions (fields: id, courseid, format, sectionid[optional], name, value)
  • deprecate existing fields in table course: numsections, hiddensections, coursedisplay.

Object model

Course formats must be classes inheriting base class format_base instead of the current collection of callbacks. (Although some callbacks will be converted to methods)

Method course_get_format($course) will return an instance of this class for the particular course. May be called with specific format but with empty course id (i.e. when course is being created)

Class format_base

method description
is_setup_completed() returns boolean. If setup is not yet completed, course/view.php will redirect to course/edit.php
default_blocks() replaces config.php with $format[‘defaultblocks’]
 ? form_fields() defines fields to be used in edit course form
 ? form_validation() performs additional validation for edit course form
page_set_course() is called from moodle_page::set_course() allowing course formats to run custom code at that point
page_set_cm() is called from moodle_page::set_cm()
output_course_header() displays the course-specific header. It will be included in all core themes, custom themes need to add support for it. Inside it should call function from renderer
output_course_footer() displays the course-specific footer
 ? output_course_content_header() displays the course-specific header to be displayed in main content section (i.e. prev-next module navigation)
 ? output_course_content_footer() displays the course-specific footer to be displayed in main content section (i.e. prev-next module navigation)
editsection_form() returns an instance of editsection_form (the format can overwrite this form)
is_section_current() replaces format_section_renderer_base::is_section_current()
get_section_name() replaces get_section_name()
uses_sections() replaces course_format_uses_sections()
supports_ajax() replaces course_format_ajax_support()
extend_navigation() replaces callback_FORMAT_load_content()
get_section_url() replaces callback_FORMAT_get_section_url()

Backward compartibility

Define class format_legacy extends format_base that will call the existing callbacks and get blocks from config.php if format class is not defined (2.0-2.3 backward compartibility). Function course_get_format() will return instance of this class if the course format does not define it's own class

Course sections hierarchy

Add support for nested course sections:

  • avoid loops,
  • store visibleold;
  • Process moving, deleting sections;
  • Make sure the hierarchy appears in navigation menu and breadcrumb;
  • Make sure changing of availability rules for both parent and child sections works correctly together

Core formats will NOT support hierarchy, we just want to make sure that non-plugin code can deal with it

Course add/edit form

  • When course is created/edited, the options specific for the format are displayed in separate form section and it dynamically changes when format is changed (with support of non-js mode). Each course format defines which display options it needs. For the standard weeks/topics formatd they are [numsections, hiddensections, coursedisplay], for scrom and social there are no options
  • Make Course format selector on create/edit course page looking similar to "Add activity" with help text for each format
  • Add events_trigger('course_format_changed') in function update_course() if course format was changed. Course format may want to watch it and insert/delete format-specific data in DB

Course sections management

  •  ? Add events_triggers in functions that create/delete/hide/move course sections
  • Refactor class editsection_form so it is easier to overwrite and implements functions set_data() and get_data() instead of pre/post processing data in editsection.php

Add course formats as plugin to site administration

Course formats are plugins in the code, but they are not handled as plugins in the administration. Replace course default settings by this page. Move page to plugins.

  • option to enable/disable a course format
  • each course format may have it's own configurable options such as default and/or sticky blocks, default settings, etc.

Other changes related to course formats

  • Make sure backup/restore correctly works with sections hierarchy and new options. Also backup made in previous versions restores correctly in 2.4
  • Make sure course format can influence navigation menu and breadcrumb. This probably will be done already by set_course/set_cm callbacks
  • Course formats may want to extend course settings navigation. Implement additional callback or do it in set_course() ?
  • Improvement: file_info (Server files repository) should list modules inside the course groupped by sections
  • Describe in course formats dev documentation how formats can watch the events triggers


Wishlist

  • Add field course_module.sortorder and deprecate course_section.sequence. Consider renaming course_section.section into course_section.sortorder (but probably not)